;+
; NAME:
;    AVAILABLE_VIDEOFRAME
;
; PURPOSE:
;    Determine whether a video frame is available on the video stream
;    opened with OPEN_VIDEOFILE.
;
; CATEGORY:
;    Image acquisition, Image analysis
;
; CALLING SEQUENCE:
;    res = available_videoframe(s)
;
; INPUTS:
;    s: structure describing the video stream that is obtained
;       by running OPEN_VIDEOFILE.
;
; OUTPUTS:
;    res: TRUE if a video frame is available.
;
; RESTRICTIONS:
;    Can read any video format that is supported by the underlying
;    OpenCV codec.  On linux systems, this is provided by FFMPEG.
;
; PROCEDURE:
;    Uses CALL_EXTERNAL to access commands from idlvideo.so,
;    which in turn is based on the OpenCV project.
;
; EXAMPLE:
;    IDL> s = open_videofile("myfile.avi")
;    IDL> if available_videoframe(s) then a = read_videoframe(s)
;    IDL> close_video, s
;
; MODIFICATION HISTORY:
; 01/22/2010: Written by David G. Grier, New York University
; 03/02/2010: DGG debug should be long
; 01/01/2011: DGG CDECL calling convention.
;
; Copyright (c) 2010-2011 David G. Grier
;
;
; UPDATES:
;    The most recent version of this program may be obtained from
;    http://physics.nyu.edu/grierlab/software.html
; 
; LICENSE:
;    This program is free software; you can redistribute it and/or
;    modify it under the terms of the GNU General Public License as
;    published by the Free Software Foundation; either version 2 of the
;    License, or (at your option) any later version.
;
;    This program is distributed in the hope that it will be useful,
;    but WITHOUT ANY WARRANTY; without even the implied warranty of
;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;    General Public License for more details.
;
;    You should have received a copy of the GNU General Public License
;    along with this program; if not, write to the Free Software
;    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
;    02111-1307 USA
;
;    If the Internet and WWW are still functional when you are using
;    this, you should be able to access the GPL here: 
;    http://www.gnu.org/copyleft/gpl.html
;-

function available_videoframe, s, debug=debug

debug = long(keyword_set(debug))

if ~is_videostream(s) then return, 0

return, call_external('idlvideo.so', 'video_frameready', /cdecl, $
                      s.stream, $
                      debug)
end