sage plugin for vlc

Overview  

The SAGE-enabled version of  vlc  that was available for some time from EVL was first constructed a long time ago (actually for  vlc  version 0.8.5) and is now difficult to compile due to differences in library and related software versions in use at that time and now. In addition, the  vlc  plugin API appears to have changed since 0.8.5 so it hasn't been possible to just apply the original sage related changes from 0.8.5 into a newer version of  vlc .

The sage plugin was then rewritten at UQVislab to conform with  vlc  at version 1.0.5. That rewrite was based on the previous sage plugin for vlc from EVL (in their  vlc-3.tar.gz download) as well as  vlc 's own opengl plugin.

The latest release (22nd November, 2010) of the new plugin is for  vlc  version 1.1.8. Apart from whatever new features are available by upgrading  vlc  itself from 1.0.5 to 1.1.8, the new  SAGE  plugin also incorporates selectable DXT compression.


Method  

-   download the modified vlc source tarball .
-  extract the source code from the tarball:
         tar xvf vlc-1.1.8-sage.tar.bz2  

-  compile the modified  vlc  (a script named  GO  contains the necessary commands - just run it):
         cd vlc-1.1.8  
         sh ./GO  

  The GO script will compile the source code and install  vlc  and  cvlc  into  $SAGE_DIRECTORY/bin/  along with all the other  SAGE  executables i.e. make sure SAGE_DIRECTORY is set in your environment (as it should be if you're generally set up to run SAGE).


As an alternative to using the modified tarball as described above, the pristine  original tarball from Videolan  can be used after applying  this SAGE-DXT patch for vlc  before running the GO script.


Running VLC with SAGE  

In the $SAGE_DIRECTORY/bin directory, create a vlc.conf file; perhaps copy/rename and adjust atlantis.conf or some other existing .conf file. Then for a live capture from a PAL capture card, run something like:
     vlc --vout sage v4l2:///dev/video3 :v4l2-width=720 :v4l2-height=576 :v4l2-aspect-ratio=4\:3 :v4l2-fps=25  

To replay a movie, try something like:
     vlc --vout sage ~/movies/testmovie_HD.mp4  

If the pesky vlc interface annoys you (it serves no purpose with  SAGE  anyway), run with  cvlc  instead of  vlc  i.e.
     cvlc --vout sage ~/movies/testmovie_HD.mp4  
(use of cvlc also enables remote launching via ssh - no need to fiddle with DISPLAY variables)

To use DXT compression for the streams to your tile machines, add the  sage-dxt  option to the  vlc  or  cvlc  command like this:
     cvlc --vout sage ~/movies/testmovie_HD.mp4 :sage-dxt=1

To have the movie loop continuously, add the  --loop  option to the command line i.e.:
     cvlc --vout sage ~/movies/testmovie_HD.mp4 :sage-dxt=1 --loop


Issues  

- if the build fails with a message: 
    util.h:103: error: redefinition of 'class data_path',
it is related to the SAGE version on the machine. Fix the problem by editing the modules/video_out/util.h file; remove everything from line 98 (should be "// From NVIDIA Toolkit") to the end of the file. Now continue the build.

- if build fails with a message like: 
    error: 'UINT64_C' was not declared in this scope,
it may be fixed by inserting the line: 
    #define __STDC_CONSTANT_MACROS
as the first line of code in the file modules/video_output/sage.cpp. Now continue with the build.

- DXT compression only working correctly on x86_64 cpus (others may experience Segmentation faults). It will also fail on video files with "strange" sizes (anything with vertical or horizontal size not a multiple of 4).

-  different Linux distributions may not already have the required build dependencies installed. They will become apparent as the configure and/or make steps in the GO script fail. Install the necessary dependency and run the GO script again, repeating the cycle until success. As a guide, over and above the additional packages already installed to build SAGE itself,  builders on Slackware 13.x would need to install the twolame, a52dec and lua packages (available from UQVislab repository).

-  16 or 24bpp output? A 1920x1080@25fps video stream using 24bits per pixel (RGB888) requires network throughput of about 1.2Gb/s. This is just beyond the capacity of 1G NICs and if the plugin is built to use 24bpp, this insufficient network capacity is typically manifested as a reduced frame rate e.g. 20fps instead of 25fps. The latest version of vlc with sage plugin supports a command line option to enable the user to choose 16, 24 or even 32 bpp as the output format to stream to the sage dispay. The previous sage plugin for vlc used 16bpp (RGB565) and this has been carried over to the new plugin as the default setting i.e. if no particular value is specified,  then 16bpp is used. This allows full frame rate to be displayed with a network throughput of about 850Mb/s. Of course the trade off is somewhat reduced colour resolution.
   If your tile machines and network can tolerate the increased load inherent in a higher bpp setting e.g. if you have a 10G network and NICs as well as cpu cycles to spare, then try a command line option like
        :sage-bpp=24
or even
        :sage-bpp=32
and of course the default 16bpp can be explicitly specified with
        :sage-bpp=16

Remember that there's nothing to be gained by setting bpp to be higher than the source material - it will just consume additional cpu and network resources.