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* 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* 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* 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: number [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 * cross 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: number [in Lua 5] \endverbatim
00129 * \ingroup capture */
00130 int 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() -> error: 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: number, 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: 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: number [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 * It can not have an alpha channel and orientation is always bottom up. \n
00188 * Returns zero if failed or timeout expired, the buffer is not changed.
00189 *
00190 * \verbatim vc:Frame(image: imImage, timeout: number) -> error: number [in Lua 5] \endverbatim
00191 * \ingroup capture */
00192 int IM_DECL imVideoCaptureFrame(imVideoCapture* vc, unsigned char* data, int color_mode, int timeout);
00193
00194 /** Start capturing, returns the new captured frame and stop capturing. \n
00195 * This is more usefull if you are switching between devices. \n
00196 * Data format is the same as imVideoCaptureFrame. \n
00197 * Returns zero if failed.
00198 *
00199 * \verbatim vc:OneFrame(image: imImage) -> error: number [in Lua 5] \endverbatim
00200 * \ingroup capture */
00201 int IM_DECL imVideoCaptureOneFrame(imVideoCapture* vc, unsigned char* data, int color_mode);
00202
00203 /** Start capturing. \n
00204 * Use -1 to return the current state. \n
00205 * Returns zero if failed.
00206 *
00207 * \verbatim vc:Live(live: number) -> error: number [in Lua 5] \endverbatim
00208 * \ingroup capture */
00209 int IM_DECL imVideoCaptureLive(imVideoCapture* vc, int live);
00210
00211 /** Resets a camera or video attribute to the default value or
00212 * to the automatic setting. \n
00213 * Not all attributes support automatic modes. \n
00214 * Returns zero if failed.
00215 *
00216 * \verbatim vc:ResetAttribute(attrib: string, fauto: number) -> error: number [in Lua 5] \endverbatim
00217 * \ingroup capture */
00218 int IM_DECL imVideoCaptureResetAttribute(imVideoCapture* vc, const char* attrib, int fauto);
00219
00220 /** Returns a camera or video attribute in percentage of the valid range value. \n
00221 * Returns zero if failed or attribute not supported.
00222 *
00223 * \verbatim vc:GetAttribute(attrib: string) -> error: number, percent: number [in Lua 5] \endverbatim
00224 * \ingroup capture */
00225 int IM_DECL imVideoCaptureGetAttribute(imVideoCapture* vc, const char* attrib, float *percent);
00226
00227 /** Changes a camera or video attribute in percentage of the valid range value. \n
00228 * Returns zero if failed or attribute not supported.
00229 *
00230 * \verbatim vc:SetAttribute(attrib: string, percent: number) -> error: number [in Lua 5] \endverbatim
00231 * \ingroup capture */
00232 int IM_DECL imVideoCaptureSetAttribute(imVideoCapture* vc, const char* attrib, float percent);
00233
00234 /** Returns a list of the description of the valid attributes for the device class. \n
00235 * But each device may still not support some of the returned attributes. \n
00236 * Use the return value of \ref imVideoCaptureGetAttribute to check if the attribute is supported.
00237 *
00238 * \verbatim vc:GetAttributeList() -> attrib_list: table of strings [in Lua 5] \endverbatim
00239 * \ingroup capture */
00240 const char** IM_DECL imVideoCaptureGetAttributeList(imVideoCapture* vc, int *num_attrib);
00241
00242
00243 /** \defgroup winattrib Windows Attributes Names
00244 * Not all attributes are supported by each device.
00245 * Use the return value of \ref imVideoCaptureGetAttribute to check if the attribute is supported.
00246 \verbatim
00247 VideoBrightness - Specifies the brightness, also called the black level.
00248 VideoContrast - Specifies the contrast, expressed as gain factor.
00249 VideoHue - Specifies the hue angle.
00250 VideoSaturation - Specifies the saturation.
00251 VideoSharpness - Specifies the sharpness.
00252 VideoGamma - Specifies the gamma.
00253 VideoColorEnable - Specifies the color enable setting. (0/100)
00254 VideoWhiteBalance - Specifies the white balance, as a color temperature in degrees Kelvin.
00255 VideoBacklightCompensation - Specifies the backlight compensation setting. (0/100)
00256 VideoGain - Specifies the gain adjustment.
00257 CameraPanAngle - Specifies the camera's pan angle. To 100 rotate right, To 0 rotate left (view from above).
00258 CameraTiltAngle - Specifies the camera's tilt angle. To 100 rotate up, To 0 rotate down.
00259 CameraRollAngle - Specifies the camera's roll angle. To 100 rotate right, To 0 rotate left.
00260 CameraLensZoom - Specifies the camera's zoom setting.
00261 CameraExposure - Specifies the exposure setting.
00262 CameraIris - Specifies the camera's iris setting.
00263 CameraFocus - Specifies the camera's focus setting, as the distance to the optimally focused target.
00264 FlipHorizontal - Specifies the video will be flipped in the horizontal direction.
00265 FlipVertical - Specifies the video will be flipped in the vertical direction.
00266 AnalogFormat - Specifies the video format standard NTSC, PAL, etc. Valid values:
00267 NTSC_M = 0
00268 NTSC_M_J = 1
00269 NTSC_433 = 2
00270 PAL_B = 3
00271 PAL_D = 4
00272 PAL_H = 5
00273 PAL_I = 6
00274 PAL_M = 7
00275 PAL_N = 8
00276 PAL_60 = 9
00277 SECAM_B = 10
00278 SECAM_D = 11
00279 SECAM_G = 12
00280 SECAM_H = 13
00281 SECAM_K = 14
00282 SECAM_K1 = 15
00283 SECAM_L = 16
00284 SECAM_L1 = 17
00285 PAL_N_COMBO = 18
00286 \endverbatim
00287 * \ingroup capture */
00288
00289
00290 #if defined(__cplusplus)
00291 }
00292
00293 /** A C++ Wrapper for the imVideoCapture structure functions.
00294 * \ingroup capture */
00295 class imCapture
00296 {
00297 public:
00298 imCapture()
00299 { vc = imVideoCaptureCreate(); }
00300
00301 ~imCapture()
00302 { if (vc) imVideoCaptureDestroy(vc); }
00303
00304 int Failed()
00305 { if (!vc) return 0; else return 1; }
00306
00307 int Connect(int device)
00308 { return imVideoCaptureConnect(vc, device); }
00309
00310 void Disconnect()
00311 { imVideoCaptureDisconnect(vc); }
00312
00313 int DialogCount()
00314 { return imVideoCaptureDialogCount(vc); }
00315
00316 int ShowDialog(int dialog, void* parent)
00317 { return imVideoCaptureShowDialog(vc, dialog, parent); }
00318
00319 const char* DialogDescription(int dialog)
00320 { return imVideoCaptureDialogDesc(vc, dialog); }
00321
00322 int FormatCount()
00323 { return imVideoCaptureFormatCount(vc); }
00324
00325 int GetFormat(int format, int *width, int *height, char* desc)
00326 { return imVideoCaptureGetFormat(vc, format, width, height, desc); }
00327
00328 int SetFormat(int format)
00329 { return imVideoCaptureSetFormat(vc, format); }
00330
00331 void GetImageSize(int *width, int *height)
00332 { imVideoCaptureGetImageSize(vc, width, height); }
00333
00334 int SetImageSize(int width, int height)
00335 { return imVideoCaptureSetImageSize(vc, width, height); }
00336
00337 int GetFrame(unsigned char* data, int color_mode, int timeout)
00338 { return imVideoCaptureFrame(vc, data, color_mode, timeout); }
00339
00340 int GetOneFrame(unsigned char* data, int color_mode)
00341 { return imVideoCaptureOneFrame(vc, data, color_mode); }
00342
00343 int Live(int live)
00344 { return imVideoCaptureLive(vc, live); }
00345
00346 int ResetAttribute(const char* attrib, int fauto)
00347 { return imVideoCaptureResetAttribute(vc, attrib, fauto); }
00348
00349 int GetAttribute(const char* attrib, float *percent)
00350 { return imVideoCaptureGetAttribute(vc, attrib, percent); }
00351
00352 int SetAttribute(const char* attrib, float percent)
00353 { return imVideoCaptureSetAttribute(vc, attrib, percent); }
00354
00355 const char** GetAttributeList(int *num_attrib)
00356 { return imVideoCaptureGetAttributeList(vc, num_attrib); }
00357
00358 protected:
00359 imVideoCapture* vc;
00360 };
00361
00362 #endif
00363
00364 #endif