/** \file
 * \brief Video Capture
 *
 * See Copyright Notice in im.h
 * $Id: Exp $
 */

#ifndef __IMVIDEOCAPTURE_H
#define __IMVIDEOCAPTURE_H

#if	defined(__cplusplus)
extern "C" {
#endif

#define IMVC_QUERY -1

typedef struct _imVideoCapture imVideoCapture;

/** Returns the device description. Returns NULL in the last device. */
char* imVideoCaptureDeviceDesc(int device);

/** Creates a new imVideoCapture object. 
 * Returns NULL if there is no capture device available.
 * In Windows returns NULL if DirectX version is older than 8. */ 
imVideoCapture* imVideoCaptureCreate(void);

/** Destroys a imVideoCapture object. */
void imVideoCaptureDestroy(imVideoCapture* vc);

/** Connects to a capture device. More than one imVideoCapture object can be created 
 * but they must be connected to different devices. If the object is conected it will disconnect first.
 * Use IMVC_QUERY to return the current connected device, in this case returns -1 if not connected.
 * Returns zero if failed. */
int imVideoCaptureConnect(imVideoCapture* vc, int device);

/** Disconnect from a capture device. */
void imVideoCaptureDisconnect(imVideoCapture* vc);

/** Displays the format modal dialog of the connected device.
 * In Windows, the capturing will be stopped.
 * In Windows parent is a HWND of a parent window, can be NULL.
 * Returns zero if failed. */
int imVideoCaptureShowFormatDialog(imVideoCapture* vc, void* parent);

/** Displays the source modal dialog of the connected device.
 * In Windows, if it is a VFW device the capturing will be stopped.
 * In Windows parent is a HWND of a parent window, can be NULL.
 * Returns zero if failed. */
int imVideoCaptureShowSourceDialog(imVideoCapture* vc, void* parent);

/** Returns the current image size of the connected device. 
 *  width and height returns 0 if not connected. */
void imVideoCaptureGetImageSize(imVideoCapture* vc, int *width, int *height);

/** Changes the image size of the connected device. 
 * Returns zero if failed. */
int imVideoCaptureSetImageSize(imVideoCapture* vc, int width, int height);

/** Returns the captured frame. Use -1 for infinite timeout.
 * Data format is in IM_BGR format in Windows. Bpp is always 24bpp.
 * Returns zero if failed or timeout expired. */
int imVideoCaptureFrame(imVideoCapture* vc, unsigned char* data, int timeout);

/** Start capturing, returns the captured frame and stop capturing. 
 * This is more usefull if you are switching between devices.
 * Data format is in IM_BGR format in Windows. Bpp is always 24bpp.
 * Returns zero if failed. */
int imVideoCaptureOneFrame(imVideoCapture* vc, unsigned char* data);

/** Start capturing.
 * Use IMVC_QUERY to return the current state.
 * Returns zero if failed. */
int imVideoCaptureLive(imVideoCapture* vc, int live);

/** Resets a camera or video attribute to the default value or to the automatic setting.
 * Not all attributes support automatic modes.
 * Returns zero if failed. */
int imVideoCaptureResetAttribute(imVideoCapture* vc, const char* attrib, int fauto);

/** Returns a camera or video attribute in percentage of the valid range value.
 * Returns zero if failed. */
int imVideoCaptureGetAttribute(imVideoCapture* vc, const char* attrib, double *percent);

/** Changes a camera or video attribute in percentage of the valid range value.
 * Returns zero if failed. */
int imVideoCaptureSetAttribute(imVideoCapture* vc, const char* attrib, double percent);

/** Windows Attributes:
VideoBrightness - Specifies the brightness, also called the black level. 
VideoContrast - Specifies the contrast, expressed as gain factor. 
VideoHue - Specifies the hue angle. 
VideoSaturation - Specifies the saturation.
VideoSharpness - Specifies the sharpness. 
VideoGamma - Specifies the gamma. 
VideoColorEnable - Specifies the color enable setting. (0/100)
VideoWhiteBalance - Specifies the white balance, as a color temperature in degrees Kelvin. 
VideoBacklightCompensation - Specifies the backlight compensation setting. (0/100)
VideoGain - Specifies the gain adjustment.
CameraPanAngle - Specifies the camera's pan angle. To 100 rotate right, To 0 rotate left (view from above).
CameraTiltAngle - Specifies the camera's tilt angle.  To 100 rotate up, To 0 rotate down.
CameraRollAngle - Specifies the camera's roll angle. To 100 rotate right, To 0 rotate left.
CameraLensZoom - Specifies the camera's zoom setting. 
CameraExposure - Specifies the exposure setting. 
CameraIris - Specifies the camera's iris setting. 
CameraFocus - Specifies the camera's focus setting, as the distance to the optimally focused target. 
FlipHorizontal - Specifies the video will be flipped in the horizontal direction.
FlipVertical - Specifies the video will be flipped in the vertical direction.
*/

#if defined(__cplusplus)
}
#endif

#endif