NHP-pRF/Toolboxes/chronux/fly_track/videoIO/videoIO_2006b/FAQ.txt

##############################################################################
#### Frequently Asked Questions
##############################################################################

------------------------------------------------------------------------------
Q: Why should I use videoIO?

A: See README.txt's "Motivation" section.

------------------------------------------------------------------------------
Q: How do I use videoIO?

A: See INSTALL.dshow.txt (Windows) or INSTALL.ffmpeg.txt (Linux) for 
   installation instructions.  Then look at the documentation in
   the constructors @videoReader/videoReader.m and @videoWriter/videoWriter.m
   by typing
     help videoReader
     help videoWriter
   in Matlab.  A simple videoReader example is given in README.txt and 
   tests/videoWriterDemo.m is a good example of writing videos.

------------------------------------------------------------------------------
Q: videoIO, videoReader, and videoWriter: what's what?

A: Originally, this library was just called videoReader because it was only
   used to stream videos into Matlab using mex function plugins to access
   3rd party libraries like ffmpeg and DirectShow.  Later we found it 
   natural to  extend the capabilities to include writing videos as well.
   videoIO is the name of the library that allows reading videos with 
   videoReader objects and their plugins and writing videos with videoWriter
   objects and their plugins.

------------------------------------------------------------------------------
Q: How do I install videoIO?

A: See INSTALL.ffmpeg.txt on GNU/Linux and similar operating systems and
   INSTALL.dshow.txt on Microsoft Windows.

------------------------------------------------------------------------------
Q: Why are precompiled binary mex files only supplied for 32-bit Windows?

A: With respect to core library interfaces, Windows is a very stable and 
   consistent operating system and thus the provided binary mex files are
   likely to work on any 32-bit Windows XP or Vista system.  
   
   We have not had a chance to test the 64-bit Windows version recently and
   there are very few 64-bit codecs available.  Thus prebuilt 64-bit mex files 
   are not provided at this time.
   
   There are vast differences in versions of ffmpeg, gcc, and base system
   libraries between different Linux distributions and different releases of
   a given distribution.  To avoid maintaining a large set of binary 
   packages, we instead provide the source and step-by-step installation
   instructions (see INSTALL.ffmpeg.txt).

------------------------------------------------------------------------------
Q: Why should I install videoIO on a local hard drive and not on a 
   networked location like my home directory?
   
A: It is very easy to have different versions of ffmpeg running on different 
   machines, especially if you have compiled from sources and/or if you have
   some 32-bit and some 64-bit machines.  There are incompatibilities between 
   different versions of ffmpeg that can be hard to track down if the binary 
   version of a videoIO plugin was built against a one version of ffmpeg's 
   libraries and loaded with a different one.  These include changes in
   data structures that are not detected at runtime and different sets of
   supported codecs.  Thus we strong recommend *not* placing videoIO in a 
   networked location such as your home directory.  See INSTALL.ffmpeg.txt for 
   some suggested locations.
   
------------------------------------------------------------------------------
Q: What is the difference between the ffmpegPopen2 and the ffmpegDirect 
   plugins on Linux?

A: ffmpegPopen2 is more robust to gcc version incompatibilites and ffmpeg
   segmentation faults.  ffmpegPopen2 uses a small and simple mex file to
   launch and communicate with a server process that does the actual encoding
   or decoding of videos.  ffmpegDirect communicates directly with the ffmpeg
   libraries without using a server process.  For a list of tradeoffs of these
   approaches, type 
     help videoReader
   in Matlab.

------------------------------------------------------------------------------
Q: When I build videoIO on Linux, I see warning messages of the form
      Warning: You are using gcc version "3.3.5".  The earliest gcc version 
      supported with mex is "4.0.0".  The latest version tested for use with 
      mex is "4.2.0".  To download a different version of gcc, visit 
      http://gcc.gnu.org 
   
A: If your version of gcc is incompatible with the one used to build Matlab,
   very strange errors can occur when running mex files.  We have created the
   ffmpegPopen2 plugin specifically to address this issue.  Use it instead of
   the ffmpegDirect to be safe.

------------------------------------------------------------------------------
Q: The linker can't find sws_freeContext, sws_getCachedContext, or sws_scale
   on Linux.  What's wrong?

A: Rebuild ffmpeg from the sources using the --enable-swscaler flag when
   running ./configure.  See INSTALL.ffmpeg.txt.

   These are swscaler functions used to do image scaling and color conversion.  
   Starting with version 51.11.0 of libavcodec, ffmpeg has deprecated 
   img_convert (a more user-friendly, but less powerful and less efficient 
   colorspace converter) in favor of using swscaler.  Since the public header 
   files give no mechanism for determining whether ffmpeg was compiled with 
   swscaler vs. img_convert support, we assume swscaler is used when 
   libavcodec's version is at least 51.11.0 and that img_convert is to be used 
   for earlier versions.  
   
------------------------------------------------------------------------------
Q: I had some error with one videoReader or videoWriter object and now all
   of the rest of my opened videos are having troubles and/or I'm having 
   troubles opening new ones.  What do I do?

A: Best case: try opening the video file again.
   Worst case: type "clear all" -- this will unload the plugins.
   
   Our plugins attempt to detect when a codecs may have done a bad thing 
   like produce rouge threads, segmentation faults, or other crashes.  If we
   think an unrecoverable error has occurred, all open video files may be 
   closed.  Typically, we are able to detect a problem and cleanly unload
   the affected plugin.  In such cases, videoWriter objects are properly 
   destructed so that valid video files are created.  Doing the unloading 
   unfortunately invalidates all open video handles within the same plugin.
   Our library tries hard to avoid these situations and avoid unrecoverable
   errors as much as possible.