00001 /** \file
00002 * \brief Video Capture
00003 *
00004 * See Copyright Notice in im.h
00005 * $Id: im_capture.h,v 1.2 2005/04/14 19:40:23 scuri Exp $
00006 */
00007
00008 #ifndef __IM_CAPTURE_H
00009 #define __IM_CAPTURE_H
00010
00011 #if defined(__cplusplus)
00012 extern "C" {
00013 #endif
00014
00015 /** \defgroup capture Image Capture
00016 * \par
00017 * Functions to capture images from live video devices.
00018 * \par
00019 * See \ref im_capture.h
00020 */
00021
00022 typedef struct _imVideoCapture imVideoCapture;
00023
00024 /** Returns the number of available devices.
00025 * \ingroup capture */
00026 int imVideoCaptureDeviceCount(void);
00027
00028 /** Returns the device description. Returns NULL in the last device.
00029 * \ingroup capture */
00030 const char* imVideoCaptureDeviceDesc(int device);
00031
00032 /** Reload the device list. The devices can be dynamically removed or added to the system.
00033 * \ingroup capture */
00034 int imVideoCaptureReloadDevices(void);
00035
00036 /** Creates a new imVideoCapture object. \n
00037 * Returns NULL if there is no capture device available. \n
00038 * In Windows returns NULL if DirectX version is older than 8.
00039 * \ingroup capture */
00040 imVideoCapture* imVideoCaptureCreate(void);
00041
00042 /** Destroys a imVideoCapture object.
00043 * \ingroup capture */
00044 void imVideoCaptureDestroy(imVideoCapture* vc);
00045
00046 /** Connects to a capture device.
00047 * More than one imVideoCapture object can be created
00048 * but they must be connected to different devices. \n
00049 * If the object is conected it will disconnect first. \n
00050 * Use -1 to return the current connected device,
00051 * in this case returns -1 if not connected. \n
00052 * Returns zero if failed.
00053 * \ingroup capture */
00054 int imVideoCaptureConnect(imVideoCapture* vc, int device);
00055
00056 /** Disconnect from a capture device.
00057 * \ingroup capture */
00058 void imVideoCaptureDisconnect(imVideoCapture* vc);
00059
00060 /** Returns the number of available configuration dialogs.
00061 * \ingroup capture */
00062 int imVideoCaptureDialogCount(imVideoCapture* vc);
00063
00064 /** Displays a configuration modal dialog of the connected device. \n
00065 * In Windows, the capturing will be stopped in some cases. \n
00066 * In Windows parent is a HWND of a parent window, it can be NULL. \n
00067 * dialog can be from 0 to \ref imVideoCaptureDialogCount. \n
00068 * Returns zero if failed.
00069 * \ingroup capture */
00070 int imVideoCaptureShowDialog(imVideoCapture* vc, int dialog, void* parent);
00071
00072 /** Returns the description of a configuration dialog.
00073 * dialog can be from 0 to \ref imVideoCaptureDialogCount. \n
00074 * \ingroup capture */
00075 const char* imVideoCaptureDialogDesc(imVideoCapture* vc, int dialog);
00076
00077 /** Returns the number of available video formats. \n
00078 * Returns zero if failed.
00079 * \ingroup capture */
00080 int imVideoCaptureFormatCount(imVideoCapture* vc);
00081
00082 /** Returns information about the video format. \n
00083 * format can be from 0 to \ref imVideoCaptureFormatCount. \n
00084 * desc should be of size 10. \n
00085 * The image size is usually the maximum size for that format.
00086 * Other sizes can be available using \ref imVideoCaptureSetImageSize. \n
00087 * Returns zero if failed.
00088 * \ingroup capture */
00089 int imVideoCaptureGetFormat(imVideoCapture* vc, int format, int *width, int *height, char* desc);
00090
00091 /** Changes the video format of the connected device. \n
00092 * Should NOT work for DV devices. Use \ref imVideoCaptureSetImageSize only. \n
00093 * Use -1 to return the current format, in this case returns -1 if failed. \n
00094 * When the format is changed in the dialog, for some formats
00095 * the returned format is the preferred format, not the current format. \n
00096 * This will not affect color_mode of the capture image. \n
00097 * Returns zero if failed.
00098 * \ingroup capture */
00099 int imVideoCaptureSetFormat(imVideoCapture* vc, int format);
00100
00101 /** Returns the current image size of the connected device. \n
00102 * width and height returns 0 if not connected.
00103 * \ingroup capture */
00104 void imVideoCaptureGetImageSize(imVideoCapture* vc, int *width, int *height);
00105
00106 /** Changes the image size of the connected device. \n
00107 * Similar to \ref imVideoCaptureSetFormat, but changes only the size. \n
00108 * Valid sizes can be obtained with \ref imVideoCaptureGetFormat. \n
00109 * Returns zero if failed.
00110 * \ingroup capture */
00111 int imVideoCaptureSetImageSize(imVideoCapture* vc, int width, int height);
00112
00113 /** Returns a new captured frame. Use -1 for infinite timeout. \n
00114 * Color space can be IM_RGB or IM_GRAY, and mode can be packed (IM_PACKED) or not. \n
00115 * It can not have an alpha channel and orientation is always bottom up. \n
00116 * Returns zero if failed or timeout expired, the buffer is not changed.
00117 * \ingroup capture */
00118 int imVideoCaptureFrame(imVideoCapture* vc, unsigned char* data, int color_mode, int timeout);
00119
00120 /** Start capturing, returns the new captured frame and stop capturing. \n
00121 * This is more usefull if you are switching between devices. \n
00122 * Data format is the same as imVideoCaptureFrame. \n
00123 * Returns zero if failed.
00124 * \ingroup capture */
00125 int imVideoCaptureOneFrame(imVideoCapture* vc, unsigned char* data, int color_mode);
00126
00127 /** Start capturing. \n
00128 * Use -1 to return the current state. \n
00129 * Returns zero if failed.
00130 * \ingroup capture */
00131 int imVideoCaptureLive(imVideoCapture* vc, int live);
00132
00133 /** Resets a camera or video attribute to the default value or
00134 * to the automatic setting. \n
00135 * Not all attributes support automatic modes. \n
00136 * Returns zero if failed.
00137 * \ingroup capture */
00138 int imVideoCaptureResetAttribute(imVideoCapture* vc, const char* attrib, int fauto);
00139
00140 /** Returns a camera or video attribute in percentage of the valid range value. \n
00141 * Returns zero if failed.
00142 * \ingroup capture */
00143 int imVideoCaptureGetAttribute(imVideoCapture* vc, const char* attrib, float *percent);
00144
00145 /** Changes a camera or video attribute in percentage of the valid range value. \n
00146 * Returns zero if failed.
00147 * \ingroup capture */
00148 int imVideoCaptureSetAttribute(imVideoCapture* vc, const char* attrib, float percent);
00149
00150 /** Returns a list of the description of the valid attributes.
00151 * \ingroup capture */
00152 const char** imVideoCaptureGetAttributeList(imVideoCapture* vc, int *num_attrib);
00153
00154
00155 /** \defgroup winattrib Windows Attributes Names
00156 \verbatim
00157 VideoBrightness - Specifies the brightness, also called the black level.
00158 VideoContrast - Specifies the contrast, expressed as gain factor.
00159 VideoHue - Specifies the hue angle.
00160 VideoSaturation - Specifies the saturation.
00161 VideoSharpness - Specifies the sharpness.
00162 VideoGamma - Specifies the gamma.
00163 VideoColorEnable - Specifies the color enable setting. (0/100)
00164 VideoWhiteBalance - Specifies the white balance, as a color temperature in degrees Kelvin.
00165 VideoBacklightCompensation - Specifies the backlight compensation setting. (0/100)
00166 VideoGain - Specifies the gain adjustment.
00167 CameraPanAngle - Specifies the camera's pan angle. To 100 rotate right, To 0 rotate left (view from above).
00168 CameraTiltAngle - Specifies the camera's tilt angle. To 100 rotate up, To 0 rotate down.
00169 CameraRollAngle - Specifies the camera's roll angle. To 100 rotate right, To 0 rotate left.
00170 CameraLensZoom - Specifies the camera's zoom setting.
00171 CameraExposure - Specifies the exposure setting.
00172 CameraIris - Specifies the camera's iris setting.
00173 CameraFocus - Specifies the camera's focus setting, as the distance to the optimally focused target.
00174 FlipHorizontal - Specifies the video will be flipped in the horizontal direction.
00175 FlipVertical - Specifies the video will be flipped in the vertical direction.
00176 AnalogFormat - Specifies the video format standard NTSC, PAL, etc. Valid values:
00177 NTSC_M = 0
00178 NTSC_M_J = 1
00179 NTSC_433 = 2
00180 PAL_B = 3
00181 PAL_D = 4
00182 PAL_H = 5
00183 PAL_I = 6
00184 PAL_M = 7
00185 PAL_N = 8
00186 PAL_60 = 9
00187 SECAM_B = 10
00188 SECAM_D = 11
00189 SECAM_G = 12
00190 SECAM_H = 13
00191 SECAM_K = 14
00192 SECAM_K1 = 15
00193 SECAM_L = 16
00194 SECAM_L1 = 17
00195 PAL_N_COMBO = 18
00196 \endverbatim
00197 * \ingroup capture */
00198
00199
00200 #if defined(__cplusplus)
00201 }
00202
00203 /** A C++ Wrapper for the imVideoCapture structure functions.
00204 * \ingroup capture */
00205 class imCapture
00206 {
00207 public:
00208 imCapture()
00209 { vc = imVideoCaptureCreate(); }
00210
00211 ~imCapture()
00212 { if (vc) imVideoCaptureDestroy(vc); }
00213
00214 int Failed()
00215 { if (!vc) return 0; else return 1; }
00216
00217 int Connect(int device)
00218 { return imVideoCaptureConnect(vc, device); }
00219
00220 void Disconnect()
00221 { imVideoCaptureDisconnect(vc); }
00222
00223 int DialogCount()
00224 { return imVideoCaptureDialogCount(vc); }
00225
00226 int ShowDialog(int dialog, void* parent)
00227 { return imVideoCaptureShowDialog(vc, dialog, parent); }
00228
00229 const char* DialogDescription(int dialog)
00230 { return imVideoCaptureDialogDesc(vc, dialog); }
00231
00232 int FormatCount()
00233 { return imVideoCaptureFormatCount(vc); }
00234
00235 int GetFormat(int format, int *width, int *height, char* desc)
00236 { return imVideoCaptureGetFormat(vc, format, width, height, desc); }
00237
00238 int SetFormat(int format)
00239 { return imVideoCaptureSetFormat(vc, format); }
00240
00241 void GetImageSize(int *width, int *height)
00242 { imVideoCaptureGetImageSize(vc, width, height); }
00243
00244 int SetImageSize(int width, int height)
00245 { return imVideoCaptureSetImageSize(vc, width, height); }
00246
00247 int GetFrame(unsigned char* data, int color_mode, int timeout)
00248 { return imVideoCaptureFrame(vc, data, color_mode, timeout); }
00249
00250 int GetOneFrame(unsigned char* data, int color_mode)
00251 { return imVideoCaptureOneFrame(vc, data, color_mode); }
00252
00253 int Live(int live)
00254 { return imVideoCaptureLive(vc, live); }
00255
00256 int ResetAttribute(const char* attrib, int fauto)
00257 { return imVideoCaptureResetAttribute(vc, attrib, fauto); }
00258
00259 int GetAttribute(const char* attrib, float *percent)
00260 { return imVideoCaptureGetAttribute(vc, attrib, percent); }
00261
00262 int SetAttribute(const char* attrib, float percent)
00263 { return imVideoCaptureSetAttribute(vc, attrib, percent); }
00264
00265 const char** GetAttributeList(int *num_attrib)
00266 { return imVideoCaptureGetAttributeList(vc, num_attrib); }
00267
00268 protected:
00269 imVideoCapture* vc;
00270 };
00271
00272 #endif
00273
00274 #endif