;+
; NAME:
;    OPEN_VIDEOCAMERA
;
; PURPOSE:
;    Opens an OpenCV-compatible video camera for subsequent
;    frame acquisition.
;
; CATEGORY:
;    Image acquisition, Image analysis
;
; CALLING SEQUENCE:
;    s = open_videocamera([number])
;
; OPTIONAL INPUT:
;    number: integer specifying camera number.
;        Default: use first available video camera.
;
; KEYWORDS:
;    geometry: [width,height] to rescale frames
;
; KEYWORD FLAGS:
;    grayscale: if set, convert color images to grayscale
;
; OUTPUTS:
;    s: structure describing the video stream.
;    s.filename: input filename
;    s.stream:   video stream index
;    s.width:    width of image in pixels
;    s.height:   height of image in pixels
;    s.channels: number of color channels
;    s.geometry: geometry to rescale image
;    s.grayscale: flag to convert color images into grayscale
;
; PROCEDURE:
;    Uses CALL_EXTERNAL to access commands from idlvideo.so,
;    which in turn is based on the OpenCV project.
;
; EXAMPLE:
;    IDL> s = open_videocamera(/gray,geometry=[640,480])
;    IDL> if available_videoframe(s) then a = read_videoframe(s)
;    IDL> close_video, s
;
; RESTRICTIONS:
;    Updating frame index does not work because of OpenCV bugs.
;
; MODIFICATION HISTORY:
; 04/26/2010: Written by David G. Grier, New York University
; 06/10/2010: DGG. Corrected error condition handling.  Added COMPILE_OPT.
; 12/29/2010: DGG. Geometry set to [width,height] if not specified.
; 01/01/2011: DGG. Use CDECL call.  Geometry now is set, if specified.
;
; 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 open_videocamera, number, $
                         grayscale = grayscale, $
                         geometry = geometry, $
                         debug = debug

COMPILE_OPT IDL2

if n_params() eq 0 then number = -1L
stream = 0L
width = 0L
height = 0L
channels = 0L
debug = long(keyword_set(debug))

if n_elements(geometry) eq 2 then begin
   width = long(geometry[0])
   height = long(geometry[1])
endif

error = call_external('idlvideo.so', 'video_queryvideocamera', /cdecl, $
                      number, $
                      stream, width, height, channels, $
                      debug)

if error ne 0 then begin
   if debug then $
      message, "Could not acquire an image", /inf
   return, -1
endif

if n_elements(geometry) ne 2 then $
   geometry = [width, height]

grayscale = long(keyword_set(grayscale))

s = {videostream, $
     filename:  'Camera: '+strtrim(number, 2), $
     stream:    stream, $
     width:     width, $
     height:    height, $
     channels:  channels, $
     geometry:  long(geometry), $
     grayscale: grayscale}

return, s

end