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