videoreader.m

Video IO toolbox for matlab. 用directshow做的

function vr = videoReader(url, varargin)
% videoReader class constructor
%   Creates a object that reads video streams.  We use a plugin 
%   architecture in the backend to do the actual reading.  For example, 
%   on Windows, DirectShow will typically be used and on Linux, the 
%   ffmpeg library is often used.
%
%   vr = videoReader(url)
%     Opens the given video file for reading using the default plugin.
%     On Windows, 'DirectShow' is used by default and on Linux,
%     'ffmpegPopen2' is used by default.  For most plugins, the url will 
%     really be a filename.
%
%   vr = videoReader(url, ..., 'plugin',pluginName, ...)
%   vr = videoReader(url,pluginName, ...)
%     Opens the file using the manually specified plugin implementation.  
%     Available plugins include:
%
%     'DirectShow': preferred method on Windows
%       - Only available on Windows
%       - See INSTALL.dshow.txt for installation instructions
%       - Can load virtually any video file that can be played in
%         Microsoft's Windows Media Player.  Note that the correct codec
%         must be installed to read a file.  For example, to read 
%         'tests/numbers.3ivx.avi' in videoIODir, the user must have
%         installed an MPEG4 codec such as 3ivx (www.3ivx.com), DivX
%         (www.divx.com), or XviD (www.xvid.org). 
%       - The URL parameter should be a filename.
%         - As a convenience, all forward slashes ('/') are automatically  
%           converted to backslashes ('\')
%
%     'ffmpegPopen2': safe method on Linux
%       - Only supported on GNU/Linux (it might work on BSD systems too 
%         like Mac OS X, but this is untested)
%       - See INSTALL.ffmpeg.txt for installation instructions
%       - Creates a separate server process to communicate with the
%         ffmpeg libraries.  
%         - Works when the system's version of GCC is very different from
%           the one that MathWorks used to compile Matlab.
%         - Isolates ffmpeg errors so they typically cannot crash
%           Matlab.  
%         - May allow for more flexible distribution terms for your code 
%           when it uses videoIO (ffmpeg may be compiled with either 
%           the LGPL or GPL license).
%
%     'ffmpegDirect': low-overhead method on Linux
%       - same as ffmpegPopen2, but the ffmpeg libraries are loaded
%         directly by the MEX file.
%         - May not work if MathWorks' and your version of GCC are
%           incompatible. 
%         - Slightly faster than ffmpegPopen2 since there is no
%           interprocess communication overhead.
%         - Unless ffmpeg generates a hard crash, better error messages
%           are often available.
%
%     'imread': read frames from individual image files
%       - Implemented as a .m file (no mex compilation required).
%       - Uses Matlab's IMREAD function to read frames.
%       - The URL parameter should be a file mask.  
%         - Wildcards (e.g. 'tests/*.png') or sprintf-style strings (e.g.
%           'tests/%04d.png') are supported. 
%         - Only one wildcard or sprintf-style string is allowed and it
%           must be in the filename portion, not the directory-name
%           portion of the pathname (e.g. 'foo/*/frame.png',
%           'foo/%04d/frame.png', and 'foo/*/*.png' are not supported at
%           this time).
%         - For wildcard strings, the alphabetically-first frame is
%           considered frame 0.
%         - For sprintf-style strings the sscanf is used to extract the
%           frame number.  Only non-negative frame numbers are supported
%           at this time.
%         - As a convenience, forward slashes ('/') and backward slashes
%           ('\') are both treated as directory separators.
%
%     'load': read frames (or other data) from individual .mat files
%       - Same as 'imread', but uses Matlab's LOAD function to load frames
%         from .mat files instead of IMREAD from image files.
%       - Can actually load an arbitrary single variable from a .mat file, 
%         not just images.
%
%   vr = videoReader(url, ..., param,arg,...)
%     Allows the user to pass extra configuration arguments to plugin.
%
%     The following parameters are supported by current plugins.  In the
%     "Plugins Supported" column, 'f' refers to the 'ffmpegDirect' and
%     'ffmpegPopen2' plugins, 'd' to 'DirectShow', 'i' to 'imread', and 'l'
%     to 'load'.
%
%                     Plugins 
%     Parameter      Supported  Implementation Notes
%     ---------      ---------  -----------------------------
%     preciseFrames    fd       For forward seeks smaller or equal to this
%                               amount, the seek is guaranteed to  be
%                               precise.  For these seeks, we override the
%                               codec's default behavior to ensure
%                               preciseness.  Choosing a small value
%                               for 'preciseFrames' can result in much
%                               faster seeks (often O(1) for imprecise
%                               versus O(n) for precise, where n is the
%                               seek distance) with the risk of not going
%                               to  exactly the requested frame.  If the
%                               value is negative, precise seeks are always
%                               guaranteed.  Note that for many codecs,
%                               "imprecise" seeks will actually be precise.
%
%                               The 'imread' and 'load' plugins are always
%                               precise, so they do not support this
%                               option.  As of 14 Jan 2008, the
%                               'ffmpegPoepn2' and 'ffmpegDirect' plugins
%                               always do precise seeks as well, but in
%                               the future imprecise seeks may be supported.
%
%                               Example: if 'preciseFrames' is 10 and the
%                               user calls seek(vr,10) successfully, the
%                               reader is guaranteed to be exactly 10
%                               frames past its previous position (as a
%                               naive user would expect it to be).  On the
%                               other hand, seek(vr,-1) or seek(vr,11) are
%                               only required to try to go back
%                               *approximately* one frame or forward   
%                               11, respectively.   
%
%     frameTimeoutMS    d       When interfacing with DirectShow, we 
%                               schedule requests that are fulfilled in 
%                               a collection of DirectShow-controlled
%                               threads.  If it takes more than
%                               frameTimeoutMS milliseconds per frame to
%                               fulfill a request, we assume the request
%                               will never be fulfilled and we return with
%                               an error from methods such as next and
%                               getframe.  Use -1 for an infinite timeout
%                               period.
%
%     varName             l     Specifies the variable name to load from
%                               the .mat files.  If 'varName' is blank or
%                               unspecified, the 'load' plugin attempts to
%                               guess which variable to load, picking what
%                               it thinks is the largest data object that
%                               looks like an image.
% 
% Once you have created a videoReader object, you must next call NEXT,
% SEEK, or STEP at least once so that it will read some frame from disk.  
% *After* calling one of these methods, you may call GETFRAME as many 
% times as you would like and it will decode and return the current frame 
% (without advancing to a different frame).  GETINFO may be called at any 
% time (even before NEXT, SEEK, or STEP).  It returns basic information 
% about the video stream.  Once you are done using the videoReader, make 
% sure you call CLOSE so that any system resources allocated by the plugin 
% may be released.  Here's a simple example of how you might use
% videoReader...
%
% Example:
%   % take us to the videoReader directory since we know there's a video
%   % file there.  
%   chdir(fileparts(which('videoReaderWrapper.cpp')));
%
%   % Construct a videoReader object
%   vr = videoReader(fullfile(videoIODir, 'tests/numbers.uncompressed.avi'));
%
%   % Do some processing on the video and display the results
%   avgIntensity = [];
%   i = 1;
%   figure;
%   while (next(vr))
%     img = getframe(vr);  
%     avgIntensity(i) = mean(img(:));
%     subplot(121); imshow(img);        title('current frame');
%     subplot(122); plot(avgIntensity); title('avg. intensity vs. frame');
%     drawnow;      pause(0.1);         i = i+1;
%   end
%   vr = close(vr);
%
% SEE ALSO:
%   buildVideoIO
%   videoIODir
%   videoReader/close
%   videoReader/getframe
%   videoReader/getinfo
%   videoReader/getnext
%   videoReader/next
%   videoReader/seek
%   videoReader/step
%   videoread
%   videoWriter
%
%Copyright (c) 2006 Gerald Dalley
%See "MIT.txt" in the installation directory for licensing details (especially
%when using this library on GNU/Linux). 

% parse the function arguments
if (mod(length(varargin),2) == 0)
  plugin     = defaultVideoIOPlugin(mfilename);
  pluginArgs = varargin;
else
  plugin     = varargin{1};
  pluginArgs = {varargin{2:end}};
end
[plugin,pluginArgs] = pvtVideoIO_parsePlugin(plugin, pluginArgs);

% create the base object with the correct plugin
vr = struct('plugin',pvtVideoIO_mexName(mfilename, plugin), ...
            'handle',int32(-1));
vr = class(vr, mfilename);

% Pull apart the URL.  Right now this isn't really necessary AFAIK, but if
% we want to automatically choose plugins based on extension or do other
% smarter url handling in the future, this would be useful.
[pathstr, name, ext, versn] = fileparts(url);

% Convert arguments to strings to pass to the plugin.  Doing this string
% conversion makes the plugin implementation much easier.
strArgs = cell(size(pluginArgs));
for i=1:numel(pluginArgs), strArgs{i} = num2str(pluginArgs{i}); end

% Actually instantiate the reader in the plugin.
vr.handle = feval(vr.plugin, 'open', vr.handle, ...
  fullfile(pathstr,[name ext versn]), strArgs{:});