/** \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 number of available devices. */
int imVideoCaptureDeviceCount(void);

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

/** Reload the device list. The devices can be dynamically removed or added to the system. */
int imVideoCaptureReloadDevices(void);

/** 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 a configuration modal dialog of the connected device.
 * In Windows, the capturing will be stopped in some cases.
 * In Windows parent is a HWND of a parent window, it can be NULL.
 * Returns zero if failed. */
int imVideoCaptureShowDialog(imVideoCapture* vc, int dialog, void* parent);

/** Returns the number of available configuration dialogs. */
int imVideoCaptureDialogCount(imVideoCapture* vc);

/** Returns the description of a configuration dialog. */
const char* imVideoCaptureDialogDesc(imVideoCapture* vc, int dialog);

/** 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);

/** Returns a list of the description of the valid attributes */
const char** imVideoCaptureGetAttributeList(imVideoCapture* vc, int *num_attrib);

/** 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.
AnalogFormat - Specifies the video format standard NTSC, PAL, etc
    NTSC_M     = 0 
    NTSC_M_J   = 1  
    NTSC_433   = 2
    PAL_B      = 3
    PAL_D      = 4
    PAL_H      = 5
    PAL_I      = 6
    PAL_M      = 7
    PAL_N      = 8
    PAL_60     = 9
    SECAM_B    = 10
    SECAM_D    = 11
    SECAM_G    = 12
    SECAM_H    = 13
    SECAM_K    = 14
    SECAM_K1   = 15
    SECAM_L    = 16
    SECAM_L1   = 17
    PAL_N_COMBO = 18
*/

#if defined(__cplusplus)
}
#endif

#endif
