00001 /** \file 00002 * \brief Video Capture 00003 * 00004 * See Copyright Notice in im.h 00005 */ 00006 00007 #ifndef __IM_CAPTURE_H 00008 #define __IM_CAPTURE_H 00009 00010 #if defined(__cplusplus) 00011 extern "C" { 00012 #endif 00013 00014 /* declarations to create an export library for Watcom. */ 00015 #if ! defined (IM_DECL) 00016 #if defined (__WATCOMC__) 00017 #define IM_DECL __cdecl 00018 #elif defined(__WATCOM_CPLUSPLUS__) 00019 #define IM_DECL __cdecl 00020 #else 00021 #define IM_DECL 00022 #endif 00023 #endif 00024 00025 /** \defgroup capture Image Capture 00026 * \par 00027 * Functions to capture images from live video devices. 00028 * \par 00029 * See \ref im_capture.h 00030 */ 00031 00032 typedef struct _imVideoCapture imVideoCapture; 00033 00034 /** Returns the number of available devices. 00035 * 00036 * \verbatim im.VideoCaptureDeviceCount() -> count: number [in Lua 5] \endverbatim 00037 * \ingroup capture */ 00038 int IM_DECL imVideoCaptureDeviceCount(void); 00039 00040 /** Returns the device description. Returns NULL only if it is an invalid device. 00041 * 00042 * \verbatim im.VideoCaptureDeviceDesc(device: number) -> desc: string [in Lua 5] \endverbatim 00043 * \ingroup capture */ 00044 const char* IM_DECL imVideoCaptureDeviceDesc(int device); 00045 00046 /** Returns the extendend device description. May return NULL. 00047 * 00048 * \verbatim im.VideoCaptureDeviceExDesc(device: number) -> desc: string [in Lua 5] \endverbatim 00049 * \ingroup capture */ 00050 const char* IM_DECL imVideoCaptureDeviceExDesc(int device); 00051 00052 /** Returns the device path configuration. This is a unique string. 00053 * 00054 * \verbatim im.VideoCaptureDevicePath(device: number) -> desc: string [in Lua 5] \endverbatim 00055 * \ingroup capture */ 00056 const char* IM_DECL imVideoCaptureDevicePath(int device); 00057 00058 /** Returns the vendor information. May return NULL. 00059 * 00060 * \verbatim im.VideoCaptureDeviceVendorInfo(device: number) -> desc: string [in Lua 5] \endverbatim 00061 * \ingroup capture */ 00062 const char* IM_DECL imVideoCaptureDeviceVendorInfo(int device); 00063 00064 /** Reload the device list. The devices can be dynamically removed or added to the system. 00065 * Returns the number of available devices. 00066 * 00067 * \verbatim im.imVideoCaptureReloadDevices() -> count: number [in Lua 5] \endverbatim 00068 * \ingroup capture */ 00069 int IM_DECL imVideoCaptureReloadDevices(void); 00070 00071 /** Creates a new imVideoCapture object. \n 00072 * Returns NULL if there is no capture device available. \n 00073 * In Windows returns NULL if DirectX version is older than 8. \n 00074 * In Lua the IM videocapture metatable name is "imVideoCapture". 00075 * When converted to a string will return "imVideoCapture(%p)" where %p is replaced by the userdata address. 00076 * If the videocapture is already destroyed by im.VideoCaptureDestroy, then it will return also the suffix "-destroyed". 00077 * 00078 * \verbatim im.VideoCaptureCreate() -> vc: imVideoCapture [in Lua 5] \endverbatim 00079 * \ingroup capture */ 00080 imVideoCapture* IM_DECL imVideoCaptureCreate(void); 00081 00082 /** Destroys a imVideoCapture object. \n 00083 * In Lua if this function is not called, the videocapture is destroyed by the garbage collector. 00084 * 00085 * \verbatim im.VideoCaptureDestroy(vc: imVideoCapture) [in Lua 5] \endverbatim 00086 * \verbatim vc:Destroy() [in Lua 5] \endverbatim 00087 * \ingroup capture */ 00088 void IM_DECL imVideoCaptureDestroy(imVideoCapture* vc); 00089 00090 /** Connects to a capture device. 00091 * More than one imVideoCapture object can be created 00092 * but they must be connected to different devices. \n 00093 * If the object is conected it will disconnect first. \n 00094 * Use -1 to return the current connected device, 00095 * in this case returns -1 if not connected. \n 00096 * Returns zero if failed. 00097 * 00098 * \verbatim vc:Connect([device: number]) -> ret: number [in Lua 5] \endverbatim 00099 * \ingroup capture */ 00100 int IM_DECL imVideoCaptureConnect(imVideoCapture* vc, int device); 00101 00102 /** Disconnect from a capture device. 00103 * 00104 * \verbatim vc:Disconnect() [in Lua 5] \endverbatim 00105 * \ingroup capture */ 00106 void IM_DECL imVideoCaptureDisconnect(imVideoCapture* vc); 00107 00108 /** Returns the number of available configuration dialogs. 00109 * 00110 * \verbatim vc:DialogCount() -> count: number [in Lua 5] \endverbatim 00111 * \ingroup capture */ 00112 int IM_DECL imVideoCaptureDialogCount(imVideoCapture* vc); 00113 00114 /** Displays a configuration modal dialog of the connected device. \n 00115 * In Windows, the capturing will be stopped in some cases. \n 00116 * In Windows parent is a HWND of a parent window, it can be NULL. \n 00117 * dialog can be from 0 to \ref imVideoCaptureDialogCount. \n 00118 * Returns zero if failed. 00119 * 00120 * \verbatim vc:ShowDialog(dialog: number, parent: userdata) -> error: boolean [in Lua 5] \endverbatim 00121 * \ingroup capture */ 00122 int IM_DECL imVideoCaptureShowDialog(imVideoCapture* vc, int dialog, void* parent); 00123 00124 /** Allows to control the input and output of devices that have multiple input and outputs. 00125 * The cross index controls in which stage the input/output will be set. Usually use 1, but some capture boards 00126 * has a second stage. In Direct X it controls the crossbars. 00127 * 00128 * \verbatim vc:SetInOut(input, output, cross: number) -> error: boolean [in Lua 5] \endverbatim 00129 * \ingroup capture */ 00130 int IM_DECL imVideoCaptureSetInOut(imVideoCapture* vc, int input, int output, int cross); 00131 00132 /** Returns the description of a configuration dialog. 00133 * dialog can be from 0 to \ref imVideoCaptureDialogCount. \n 00134 * 00135 * \verbatim vc:DialogDesc(dialog: number) -> desc: string [in Lua 5] \endverbatim 00136 * \ingroup capture */ 00137 const char* IM_DECL imVideoCaptureDialogDesc(imVideoCapture* vc, int dialog); 00138 00139 /** Returns the number of available video formats. \n 00140 * Returns zero if failed. 00141 * 00142 * \verbatim vc:FormatCount() -> count: number [in Lua 5] \endverbatim 00143 * \ingroup capture */ 00144 int IM_DECL imVideoCaptureFormatCount(imVideoCapture* vc); 00145 00146 /** Returns information about the video format. \n 00147 * format can be from 0 to \ref imVideoCaptureFormatCount. \n 00148 * desc should be of size 10. \n 00149 * The image size is usually the maximum size for that format. 00150 * Other sizes can be available using \ref imVideoCaptureSetImageSize. \n 00151 * Returns zero if failed. 00152 * 00153 * \verbatim vc:GetFormat(format: number) -> error: boolean, width: number, height: number, desc: string [in Lua 5] \endverbatim 00154 * \ingroup capture */ 00155 int IM_DECL imVideoCaptureGetFormat(imVideoCapture* vc, int format, int *width, int *height, char* desc); 00156 00157 /** Changes the video format of the connected device. \n 00158 * Should NOT work for DV devices. Use \ref imVideoCaptureSetImageSize only. \n 00159 * Use -1 to return the current format, in this case returns -1 if failed. \n 00160 * When the format is changed in the dialog, for some formats 00161 * the returned format is the preferred format, not the current format. \n 00162 * This will not affect color_mode of the capture image. \n 00163 * Returns zero if failed. 00164 * 00165 * \verbatim vc:SetFormat([format: number]) -> error: boolean | format: number [in Lua 5] \endverbatim 00166 * \ingroup capture */ 00167 int IM_DECL imVideoCaptureSetFormat(imVideoCapture* vc, int format); 00168 00169 /** Returns the current image size of the connected device. \n 00170 * width and height returns 0 if not connected. 00171 * 00172 * \verbatim vc:GetImageSize() -> width: number, height: number [in Lua 5] \endverbatim 00173 * \ingroup capture */ 00174 void IM_DECL imVideoCaptureGetImageSize(imVideoCapture* vc, int *width, int *height); 00175 00176 /** Changes the image size of the connected device. \n 00177 * Similar to \ref imVideoCaptureSetFormat, but changes only the size. \n 00178 * Valid sizes can be obtained with \ref imVideoCaptureGetFormat. \n 00179 * Returns zero if failed. 00180 * 00181 * \verbatim vc:SetImageSize(width: number, height: number) -> error: boolean [in Lua 5] \endverbatim 00182 * \ingroup capture */ 00183 int IM_DECL imVideoCaptureSetImageSize(imVideoCapture* vc, int width, int height); 00184 00185 /** Returns a new captured frame. Use -1 for infinite timeout. \n 00186 * Color space can be IM_RGB or IM_GRAY, and mode can be packed (IM_PACKED) or not. \n 00187 * Data type is always IM_BYTE. \n 00188 * It can not have an alpha channel and orientation is always bottom up. \n 00189 * Returns zero if failed or timeout expired, the buffer is not changed. 00190 * 00191 * \verbatim vc:Frame(image: imImage, timeout: number) -> error: boolean [in Lua 5] \endverbatim 00192 * \ingroup capture */ 00193 int IM_DECL imVideoCaptureFrame(imVideoCapture* vc, unsigned char* data, int color_mode, int timeout); 00194 00195 /** Start capturing, returns the new captured frame and stop capturing. \n 00196 * This is more usefull if you are switching between devices. \n 00197 * Data format is the same as imVideoCaptureFrame. \n 00198 * Returns zero if failed. 00199 * 00200 * \verbatim vc:OneFrame(image: imImage) -> error: boolean [in Lua 5] \endverbatim 00201 * \ingroup capture */ 00202 int IM_DECL imVideoCaptureOneFrame(imVideoCapture* vc, unsigned char* data, int color_mode); 00203 00204 /** Start capturing. \n 00205 * Use -1 to return the current state. \n 00206 * Returns zero if failed. 00207 * 00208 * \verbatim vc:Live([live: number]) -> error: boolean | live: number [in Lua 5] \endverbatim 00209 * \ingroup capture */ 00210 int IM_DECL imVideoCaptureLive(imVideoCapture* vc, int live); 00211 00212 /** Resets a camera or video attribute to the default value or 00213 * to the automatic setting. \n 00214 * Not all attributes support automatic modes. \n 00215 * Returns zero if failed. 00216 * 00217 * \verbatim vc:ResetAttribute(attrib: string, fauto: boolean) -> error: boolean [in Lua 5] \endverbatim 00218 * \ingroup capture */ 00219 int IM_DECL imVideoCaptureResetAttribute(imVideoCapture* vc, const char* attrib, int fauto); 00220 00221 /** Returns a camera or video attribute in percentage of the valid range value. \n 00222 * Returns zero if failed or attribute not supported. 00223 * 00224 * \verbatim vc:GetAttribute(attrib: string) -> error: boolean, percent: number [in Lua 5] \endverbatim 00225 * \ingroup capture */ 00226 int IM_DECL imVideoCaptureGetAttribute(imVideoCapture* vc, const char* attrib, float *percent); 00227 00228 /** Changes a camera or video attribute in percentage of the valid range value. \n 00229 * Returns zero if failed or attribute not supported. 00230 * 00231 * \verbatim vc:SetAttribute(attrib: string, percent: number) -> error: boolean [in Lua 5] \endverbatim 00232 * \ingroup capture */ 00233 int IM_DECL imVideoCaptureSetAttribute(imVideoCapture* vc, const char* attrib, float percent); 00234 00235 /** Returns a list of the description of the valid attributes for the device class. \n 00236 * But each device may still not support some of the returned attributes. \n 00237 * Use the return value of \ref imVideoCaptureGetAttribute to check if the attribute is supported. 00238 * 00239 * \verbatim vc:GetAttributeList() -> attrib_list: table of strings [in Lua 5] \endverbatim 00240 * \ingroup capture */ 00241 const char** IM_DECL imVideoCaptureGetAttributeList(imVideoCapture* vc, int *num_attrib); 00242 00243 00244 /** \defgroup winattrib Windows Attributes Names 00245 * Not all attributes are supported by each device. 00246 * Use the return value of \ref imVideoCaptureGetAttribute to check if the attribute is supported. 00247 \verbatim 00248 VideoBrightness - Specifies the brightness, also called the black level. 00249 VideoContrast - Specifies the contrast, expressed as gain factor. 00250 VideoHue - Specifies the hue angle. 00251 VideoSaturation - Specifies the saturation. 00252 VideoSharpness - Specifies the sharpness. 00253 VideoGamma - Specifies the gamma. 00254 VideoColorEnable - Specifies the color enable setting. (0/100) 00255 VideoWhiteBalance - Specifies the white balance, as a color temperature in degrees Kelvin. 00256 VideoBacklightCompensation - Specifies the backlight compensation setting. (0/100) 00257 VideoGain - Specifies the gain adjustment. 00258 CameraPanAngle - Specifies the camera's pan angle. To 100 rotate right, To 0 rotate left (view from above). 00259 CameraTiltAngle - Specifies the camera's tilt angle. To 100 rotate up, To 0 rotate down. 00260 CameraRollAngle - Specifies the camera's roll angle. To 100 rotate right, To 0 rotate left. 00261 CameraLensZoom - Specifies the camera's zoom setting. 00262 CameraExposure - Specifies the exposure setting. 00263 CameraIris - Specifies the camera's iris setting. 00264 CameraFocus - Specifies the camera's focus setting, as the distance to the optimally focused target. 00265 FlipHorizontal - Specifies the video will be flipped in the horizontal direction. 00266 FlipVertical - Specifies the video will be flipped in the vertical direction. 00267 AnalogFormat - Specifies the video format standard NTSC, PAL, etc. Valid values: 00268 NTSC_M = 0 00269 NTSC_M_J = 1 00270 NTSC_433 = 2 00271 PAL_B = 3 00272 PAL_D = 4 00273 PAL_H = 5 00274 PAL_I = 6 00275 PAL_M = 7 00276 PAL_N = 8 00277 PAL_60 = 9 00278 SECAM_B = 10 00279 SECAM_D = 11 00280 SECAM_G = 12 00281 SECAM_H = 13 00282 SECAM_K = 14 00283 SECAM_K1 = 15 00284 SECAM_L = 16 00285 SECAM_L1 = 17 00286 PAL_N_COMBO = 18 00287 \endverbatim 00288 * \ingroup capture */ 00289 00290 00291 #if defined(__cplusplus) 00292 } 00293 00294 /** A C++ Wrapper for the imVideoCapture structure functions. 00295 * \ingroup capture */ 00296 class imCapture 00297 { 00298 public: 00299 imCapture() 00300 { vc = imVideoCaptureCreate(); } 00301 00302 ~imCapture() 00303 { if (vc) imVideoCaptureDestroy(vc); } 00304 00305 int Failed() 00306 { if (!vc) return 0; else return 1; } 00307 00308 int Connect(int device) 00309 { return imVideoCaptureConnect(vc, device); } 00310 00311 void Disconnect() 00312 { imVideoCaptureDisconnect(vc); } 00313 00314 int DialogCount() 00315 { return imVideoCaptureDialogCount(vc); } 00316 00317 int ShowDialog(int dialog, void* parent) 00318 { return imVideoCaptureShowDialog(vc, dialog, parent); } 00319 00320 const char* DialogDescription(int dialog) 00321 { return imVideoCaptureDialogDesc(vc, dialog); } 00322 00323 int FormatCount() 00324 { return imVideoCaptureFormatCount(vc); } 00325 00326 int GetFormat(int format, int *width, int *height, char* desc) 00327 { return imVideoCaptureGetFormat(vc, format, width, height, desc); } 00328 00329 int SetFormat(int format) 00330 { return imVideoCaptureSetFormat(vc, format); } 00331 00332 void GetImageSize(int *width, int *height) 00333 { imVideoCaptureGetImageSize(vc, width, height); } 00334 00335 int SetImageSize(int width, int height) 00336 { return imVideoCaptureSetImageSize(vc, width, height); } 00337 00338 int GetFrame(unsigned char* data, int color_mode, int timeout) 00339 { return imVideoCaptureFrame(vc, data, color_mode, timeout); } 00340 00341 int GetOneFrame(unsigned char* data, int color_mode) 00342 { return imVideoCaptureOneFrame(vc, data, color_mode); } 00343 00344 int Live(int live) 00345 { return imVideoCaptureLive(vc, live); } 00346 00347 int ResetAttribute(const char* attrib, int fauto) 00348 { return imVideoCaptureResetAttribute(vc, attrib, fauto); } 00349 00350 int GetAttribute(const char* attrib, float *percent) 00351 { return imVideoCaptureGetAttribute(vc, attrib, percent); } 00352 00353 int SetAttribute(const char* attrib, float percent) 00354 { return imVideoCaptureSetAttribute(vc, attrib, percent); } 00355 00356 const char** GetAttributeList(int *num_attrib) 00357 { return imVideoCaptureGetAttributeList(vc, num_attrib); } 00358 00359 protected: 00360 imVideoCapture* vc; 00361 }; 00362 00363 #endif 00364 00365 #endif