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