-
Notifications
You must be signed in to change notification settings - Fork 14
/
Copy pathdocs.html
executable file
·811 lines (807 loc) · 39.4 KB
/
docs.html
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=windows-1252" /><title>ToupCam API Manual</title></head><body><h1 align="center">ToupCam API Manual</h1><hr /><h1><font color="#0000FF">1. Version</font></h1><hr /><blockquote> <p>1.1.4615.20141230</p></blockquote><hr /><h1><font color="#0000FF">2. Introduction</font></h1><hr /><p>ToupCam cameras (model series: UCMOS, WCMOS, LCMOS, U3CMOS, L3CMOS, ICMOS, GCMOS, UHCCD, EXCCD, SCCCD) support various kinds of APIs (Application Program Interface), namely Native C/C++, .NET/C#/VB.NET, <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/dd375454(v=vs.85).aspx">DirectShow</a>, <a href="http://twain.org/">Twain</a>, LabView and so on. Compared with other APIs, Native C/C++ API, as a low level API, don't depend any other runtime libraries. Besides, this interface is simple, flexible and easy to be integrated into the customized applications. The SDK zip file contains all of the necessary resources and information:</p><ul> <li>inc</li></ul><blockquote> <p align="left">toupcam.h, C/C++ head file<br /> toupcam.cs, for C#. The toupcam.cs use P/Invoke to call into toupcam.dll. Please copy toupcam.cs to your C# project to use it.<br /> toupcam.vb, for VB.NET. The toupcam.vb use P/Invoke to call into toupcam.dll. Please copy toupcam.vb to your VB.NET project to use it.<br /></blockquote><ul> <li>win: For Microsoft Windows <ul> <li>x86 </li> <blockquote> <p align="left">toupcam.lib, lib file for x86.<br /> toupcam.dll, dll file for x86.<br /> toupcamdemocpp.exe, x86 C++ demo exe file.</p> </blockquote> <li>x64 </li> </ul> <ul> <blockquote> <p align="left">toupcam.lib, lib file for x64.<br /> toupcam.dll, dll file for x64.<br /> toupcamdemocpp.exe, x64 C++ demo exe file.</p> </blockquote> <li>drivers <blockquote> <p align="left">x86 folder contains the kernel mode drivers for x86, including toupcam.cat, toupcam.inf and toupcam.sys.<br /> x64 folder contains the kennel mode driver for x64, including toupcam.cat, toupcam.inf and toupcam.sys.</p> </blockquote> </li> <li>samples <blockquote> <p>a). toupcamdemocpp, C++ sample. It demonstrates to enumerate device, open device, video preview, image capture, set the preview resolution, multi-format image saving (.bmp, .jpg, .png, etc), wmv format video recording and so on. This sample use Pull Mode. To keep the code clean, this sample uses the WTL library which can be downloaded from <a href="http://sourceforge.net/projects/wtl/">http://sourceforge.net/projects/wtl</a></p> <p>b). toupcamdemomfc, a simple C++ sample. It use MFC as the GUI library. It demonstrates to open device, video preview, image capture, set the preview resolution, multi-format image saving (.bmp, .jpg, .png, etc). This sample use Pull Mode.</p> <p>c). toupcamdemowinformcs1, C# winform sample. This sample use Pull Mode, StartPullModeWithWndMsg.</p> <p>d). toupcamdemowinformcs2, C# winform sample. This sample use Pull Mode, StartPullModeWithCallback.</p> <p>e). toupcamdemowinformvb, VB.NET winform sample. This sample use Pull Mode.</p> </blockquote> </li> <li>extras <blockquote> <p align="left">a). directshow directory contains the DirectShow SDK and demo.<br /> b). twain directory contains the TWAIN SDK and demo.<br /> c). labview directory contains the Labview SDK and demo.</p> </blockquote> </li> </ul></li></ul> <ul><li>linux: For Linux.</li></ul> <ul><li>osx: For MAC OSX.</li></ul> <ul><li>doc: User manuals in English and Chinese.</li></ul><hr /><h1><font color="#0000FF">3. Modes for accessing image data: "Pull Mode" vs "Push Mode"</font></h1><hr /><p>Toupcam offers two modes to obtain image data: Pull Mode and Push Mode. The former is recommended since it's simpler and the application seldom gets stuck in multithreading conditions, especially when using windows message to notify the events.</p><ul> <li>In Pull Mode, toupcam plays a passive role and the application 'PULL' image data from toupcam. The internal thread of toupcam obtains image data from the camera hardware and saves them to the internal buffers, then notify the application (see below). The application then call functions Toupcam_PullImage and Toupcam_PullStillImage to access image data.</li></ul><blockquote> <p>There are to ways to notify applications:</p></blockquote><ol> <ol type="a"> <li>Use Windows message: Start pull mode by using the function Toupcam_StartPullModeWithWndMsg. When event occurs, toupcam will post message (PostMessage) to the specified window. Parameter WPARAM is the event type, refer to the definition of TOUPCAM_EVENT_xxxx. This model avoids the multithreading issues, so it's the most simple way. ( <span id="ouHighlight__0_1TO0_8" abp="328" paragraphname="paragraph0" srcinfo="0:1" dstinfo="0:8">Obviously</span><span id="noHighlight_0.3604163754541626" abp="329">,</span><span id="noHighlight_0.4641191291796428" abp="330"> </span><span id="ouHighlight__3_4TO11_14" abp="331" paragraphname="paragraph0" srcinfo="3:4" dstinfo="11:14">this</span><span id="noHighlight_0.02012400177838297" abp="332"> is </span><span id="ouHighlight__7_7TO16_19" abp="333" paragraphname="paragraph0" srcinfo="7:7" dstinfo="16:19">only</span><span id="noHighlight_0.2751875034297989" abp="334"> </span><span id="ouHighlight__8_9TO21_28" abp="335" paragraphname="paragraph0" srcinfo="8:9" dstinfo="21:28">supported</span><span id="noHighlight_0.3400843924475497" abp="336"> in </span><span id="ouHighlight__10_16TO30_37" abp="337" paragraphname="paragraph0" srcinfo="10:16" dstinfo="30:37">Windows </span><span id="ouHighlight__17_18TO38_44" abp="338" paragraphname="paragraph0" srcinfo="17:18" dstinfo="38:44">systems</span><span id="noHighlight_0.38054847537407715" abp="339">,</span><span id="noHighlight_0.5308658947211726" abp="340"> </span><span id="ouHighlight__23_27TO47_52" abp="341" paragraphname="paragraph0" srcinfo="23:27" dstinfo="47:52">and not supported in Linux </span><span id="ouHighlight__28_28TO53_55" abp="342" paragraphname="paragraph0" srcinfo="28:28" dstinfo="53:55">and</span><span id="noHighlight_0.7539774307626169" abp="343"> </span><span id="ouHighlight__29_33TO57_62" abp="344" paragraphname="paragraph0" srcinfo="29:33" dstinfo="57:62">MacOS</span><span id="noHighlight_0.3230648083041762" abp="349">.</span>) </li> <li>Use Callback function: Start pull mode by using the function Toupcam_StartPullModeWithCallback. When event occurs, toupcam will callback the function PTOUPCAM_EVENT_CALLBACK.</li> </ol></ol><blockquote> <p>In Pull Mode, the SDK could not only notify the application that the image data or still image are available for 'PULL', but also inform you of the other events, such as:</p></blockquote><div align="center"><table width="80%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0"> <tr> <td width="27%" valign="top">TOUPCAM_EVENT_EXPOSURE</td> <td width="73%" valign="top">exposure time changes</td> </tr> <tr> <td width="27%" valign="top">TOUPCAM_EVENT_TEMPTINT</td> <td width="73%" valign="top">white balance parameters changes</td> </tr> <tr> <td width="27%" valign="top">TOUPCAM_EVENT_IMAGE</td> <td width="73%" valign="top">Video image data arrives. Use Toupcam_PullImage to 'pull' the image data</td> </tr> <tr> <td width="27%" valign="top">TOUPCAM_EVENT_STILLIMAGE</td> <td width="73%" valign="top">Still image which is triggered by function Toupcam_Snap arrives. Use Toupcam_PullStillImage to 'pull' the image data</td> </tr> <tr> <td width="27%" valign="top">TOUPCAM_EVENT_ERROR</td> <td width="73%" valign="top">Error occurs, data acquisition cannot continue</td> </tr> <tr> <td width="27%" valign="top">TOUPCAM_EVENT_DISCONNECTED</td> <td width="73%" valign="top">Camera disconnected, maybe has been pulled out</td> </tr></table></div><ul> <li>In Push Mode, toupcam plays an active role. Once the video data is obtained from camera by internal thread, toupcam will 'PUSH' the image data to the application through PTOUPCAM_DATA_CALLBACK. Call the function Toupcam_StartPushMode to start push mode. Push mode is more complex. There are some special precautions, such as multithread issues, being impossible to call Toupcam_Close and Toupcam_Stop in callback function PTOUPCAM_DATA_CALLBACK, etc.</li></ul><hr /><h1><font color="#0000FF">4. Functions</font></h1><hr /><ul> <li> <h2>Toupcam_Enum</h2> </li></ul><blockquote> <p>Return Value: non-negative integer, enumerated camera number</p> <p>Parameters: ToupcamInst buffer</p> <p>Remarks: <blockquote> call this function to enumerate ToupCam cameras that are currently connected to computer and when it is returned, ToupcamInst buffer contains the information of each camera instance enumerated.<strong>If we don't care about that multiple cameras connect to the computer simultaneously, it's optional to call this function to enumerate the camera instances</strong>.</p> <p>The code snippet shows as below:<br /></p><table width="100%" border="0" bgcolor="#B0D0B0"> <tr> <td>ToupcamInst arr[TOUPCAM_MAX];<br />unsigned cnt = Toupcam_Enum(arr);<br />for (unsigned i = 0; i < cnt; ++i)<br /> ......</td> </tr></table> <p> </p><table width="100%" border="0" bgcolor="#B0D0B0"> <tr> <td>typedef struct{<br /> #ifdef _WIN32<br /> const wchar_t* name; /* model name */<br /> #else<br /> const char* name;<br /> #endif<br /> unsigned flag; /* TOUPCAM_FLAG_xxx */<br /> unsigned maxspeed; /* number of speed level, Toupcam_get_MaxSpeed, the speed range = [0, max], closed interval */<br /> unsigned preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */<br /> unsigned still; /* number of still resolution, Toupcam_get_StillResolutionNumber */<br /> ToupcamResolution res[TOUPCAM_MAX];<br />}ToupcamModel;</td> </tr></table></blockquote></blockquote><ul> <li> <h2>Toupcam_Open</h2> </li> <p>Return Value: HToupCam handle. Return NULL when fails (Such as the device has been pulled out).</p> <p>Parameters: ToupCam camera instance, enumerated by Toupcam_Enum. <strong>If id is NULL, Toupcam_Open will open the first camera which connects to the computer. So, if we don't care about that multiple cameras connect to the computer simultaneously, Toupcam_Enum is optional, we can simply use NULL as the parameter.</strong></p> <p>Remarks: open the camera instance.</p></ul><ul> <li> <h2>Toupcam_HotPlug</h2> </li> <p>Return Value: NA</p> <p>Parameters:</p> <blockquote> <p>PTOUPCAM_HOTPLUG pHotPlugCallback: callback function</p> <blockquote> <table width="100%" border="0" bgcolor="#B0D0B0"> <tr> <td><div align="center">typedef void (*PTOUPCAM_HOTPLUG)(void* pCallbackCtx);</div></td> </tr> </table> </blockquote> <p>void* pCallbackCtx: callback context</p> </blockquote> <p>Remarks: </p><blockquote> <p>This function only exists on OSX and Linux, it's unnecessary on Windows.</p> <p>To process the device plug in / pull out in Windows, please refer to the MSDN(<a href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa363224(v=vs.85).aspx">Device Management</a>, <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa363215(v=vs.85).aspx">Detecting Media Insertion or Removal</a>).</p> <p>To process the device plug in / pull out in Linux / OSX, please call this function to register the callback function. When the device is inserted or pulled out, you will be notified by the callback funcion, and then call Toupcam_Enum(...) again to enum the cameras.</p></blockquote></ul><ul> <li> <h2>Toupcam_Close</h2> <p>Return Value: void</p> <p>Parameters: HToupCam handle</p> <p>Remarks: close the camera instance. After it is closed, never use the HToupCam handle any more. <strong>Do not call Toupcam_Close in the PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK callback function, otherwise, deadlock occurs.</strong></p> </li> <li> <h2>Toupcam_StartPullModeWithWndMsg and Toupcam_StartPullModeWithCallback</h2> <p>Return Value: HRESULT type means "success/ failure"</p> <p>Parameters: </p> <ul> <li>HToupCam h: instance handle opened by Toupcam_Open</li> <li>HWND hWnd: event occurs, message will be posted in this window</li> <li>UINT nMsg: Windows custom message type. Its WPARAM parameter means event type TOUPCAM_EVENT_xxxx, LPARAM is useless (always zero)</li> <li>PTOUPCAM_EVENT_CALLBACK pEventCallback, void* pCallbackContext: callback function specified by user's application and callback context parameter. This callback function is called back from the internal thread in toupcam.dll, so great attention should be paid to multithread issue. Do not call Toupcam_Stop and Toupcam_Close in this callback function, otherwise, deadlock occurs.</li> <blockquote> <table width="100%" border="0"> <tr> <td bgcolor="#B0D0B0"><div align="center">typedef void (__stdcall* PTOUPCAM_EVENT_CALLBACK)(unsigned nEvent, void* pCallbackCtx);</div></td> </tr> </table> </blockquote> </ul> <p>Remarks: Obviously, Toupcam_StartPullModeWithWndMsg is only supported in Windows OS.</p> <li> <h2>Toupcam_PullImage and Toupcam_PullStillImage</h2> <p>Return Value: HRESULT type means "success/ failure"</p> <p>Parameters:</p> </li></ul><ul> <ul> <li>HToupCam h: instance handle opened by Toupcam_Open</li> <li>void* pImageData: Data buffer. Users have to make sure that the data buffer capacity is enough to save the image data.</li> <li>int bits: 24, 32 or 8, means RGB24, RGB32 or 8 bits grey images. This parameter is ignored in RAW mode.</li> <li>unsigned* pnWidth, unsigned* pnHeight: width and height of image.</li> </ul></ul><blockquote> <p>Remarks: when pImageData is NULL, while pnWidth and pnHeight are not NULL, you can peek the width and height of images.</p></blockquote><ul> <li> <h2>Toupcam_StartPushMode</h2> <p>Return Value: HRESULT type means "success / failure"</p> <p>Parameters: </p> <ul> <li>HToupCam h: instance handle opened by Toupcam.</li> <li>Open PTOUPCAM_DATA_CALLBACK pDataCallback, void* pCallbackCtx: the callback function and callback context parameters that are specified by the user's program. Toupcam.dll gets image data from the camera, then calls back this function.</li> </ul> </li> <blockquote> <table width="100%" border="0" bgcolor="#B0D0B0"> <tr> <td><div align="center">typedef void (*PTOUPCAM_DATA_CALLBACK)(const void* pData, const BITMAPINFOHEADER* pHeader, BOOL bSnap, void* pCallbackCtx);</div></td> </tr> </table> </blockquote> <blockquote> <p align="left">when calls back, if Parameter pData == NULL, then internal error occurs (eg: the camera pulled out suddenly).<br /> For parameter BOOL bSnap, TRUE means still image snap by Toupcam_Snap function, FALSE means ordinary previewed pictures/ videos.<br /> Attention: this callback function is called back from the internal thread in toupcam.dll, so great attention should be paid to multithread issue. Do not call Toupcam_Stop and Toupcam_Close in this callback function, otherwise, deadlock occurs.</p> </blockquote></ul><blockquote> <p>Remarks: start camera instance.</p></blockquote><ul> <li> <h2>Toupcam_Stop</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam handle</p> <p>Remarks: stop the camera instance. Do not call Toupcam_Stop in the PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK callback function, otherwise, deadlock occurs. After stopped, it can be restart again. For example, switching the video resolution: </p> <ul> <li>Step 1: call Toupcam_Stop to stop</li> <li>Step 2: call Toupcam_put_Size or Toupcam_put_eSize to set the new resolution</li> <li>Step 3: call Toupcam_Startxxxx to restart</li> </ul> </li> <li> <h2>Toupcam_Pause</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam handle</p> <p>Remarks: pause/continue camera instance.</p> </li> <li> <h2>Toupcam_Snap</h2> </li></ul><blockquote> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p></blockquote><ol> <ul> <li>HToupCam h: camera instance handle</li> <li>ULONG nResolutionIndex: resolution index wanted.</li> </ul></ol><blockquote> <p>Remarks: snap 'still' image. When snap successfully:</p> <blockquote> <p>a) If we use Pull Mode, it will be notified by TOUPCAM_EVENT_STILLIMAGE.</p> <p>b) If we use Push Mode, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK with the parameter BOOL bSnap is TRUE. </p></blockquote></blockquote><ul> <p align="left">Most cameras can snap still image with different resolutions under continuous preview. For example, UCMOS03100KPA's previewed resolution is 1024*768, if we call Toupcam_Snap(h, 0), we get so called "still image" with 2048*1536 resolution.<br /> Some cameras hasn't this ability, so nResolutionIndex must be equal the preview resolution which is set by Toupcam_put_Size, or Toupcam_put_eSize.<br /> Whether it supports "still snap" or not, see "still" domain in ToupcamModel.</p> <li> <h2>Toupcam_put_Size, Toupcam_get_Size, Toupcam_put_eSize, Toupcam_get_eSize</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>ULONG nResolutionIndex: current/present resolution index</li> <li>LONG nWidth, LONG nHeight: width and height of current resolution index</li> </ul> </li></ul><blockquote> <p>Remarks: set/get current resolution </p></blockquote><ul> <blockquote> <p align="left">Set resolution before running ToupCam_Startxxxx <br /> There are two ways to set current resolution: one is by resolution index, the other by width/height. Both ways are equivalent. For example, UCMOS03100KPA supports the following three kinds of resolution: <br /> Index 0: 2048, 1536<br /> Index 1: 1024, 768<br /> Index 2: 680, 510<br /> So Toupcam_put_Size(h, 1024, 768) is as effective as Toupcam_put_eSize(h, 1)</p> </blockquote> <li> <h2>Toupcam_get_ResolutionNumber, Toupcam_get_Resolution</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>ULONG nIndex: resolution index</li> <li>LONG* pWidth, LONG* pHeight: width/height</li> </ul> <p>Remarks: Toupcam_get_ResolutionNumber means the number of resolution supported. Take UCMOS03100KPA as an example, if we call the function Toupcam_get_ResolutionNumber and get "3", which means it can support three kinds of resolution. Toupcam_get_Resolution obtains the width/height of each kind of resolution.</p> </li> <blockquote> <p align="left">These parameters have also been contained in ToupcamModel.</p> </blockquote> <li> <h2>Toupcam_get_RawFormat</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <blockquote> <p>HToupCam h: camera instance handle</p> <p>unsigned* nFourCC: raw format, see the table</p> <p>unsigned* bitts: Bits Count, such as 8, 12, 14, 16</p> <div align="center"> <table width="60%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0"> <tr> <td width="40%" valign="top">MAKEFOURCC('G', 'B', 'R', 'G')</td> <td width="60%" valign="top">GBGBGB...</br>RGRGRG...</br>GBGBGB...</br>RGRGRG...</br>...</br></td> </tr> <tr> <td width="40%" valign="top">MAKEFOURCC('R', 'G', 'G', 'B')</td> <td width="60%" valign="top">RGRGRG...</br>GBGBGB...</br>RGRGRG...</br>GBGBGB...</br>...</br></td> </tr> <tr> <td width="40%" valign="top">MAKEFOURCC('B', 'G', 'B', 'R')</td> <td width="60%" valign="top">BGBGBG...</br>BRBRBR...</br>BGBGBG...</br>BRBRBR...</br>...</br></td> </tr> <tr> <td width="40%" valign="top">MAKEFOURCC('G', 'R', 'B', 'G')</td> <td width="60%" valign="top">GRGRGR...</br>BGBGBG...</br>GRGRGR...</br>BGBGBG...</br>...</br></td> </tr> <tr> <td width="40%" valign="top">MAKEFOURCC('Y', 'V', 'Y', 'U')</td> <td width="60%" valign="top">YUV4:2:2, please see: <a href="http://www.fourcc.org">http://www.fourcc.org</a></td> </tr> </table> </div> </blockquote> <li> <h2>Toupcam_put_Option, Toupcam_get_Option</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <blockquote> <p>HToupCam h: camera instance handle</p> <p>unsigned iOption: Option</p> <p>unsigned iValue: see the table</p> <div align="center"> <table width="80%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0"> <tr> <td width="28%" valign="top">TOUPCAM_OPTION_NOFRAME_TIMEOUT</td> <td width="72%" valign="top">Report error if cannot grab frame in a certain time.</br>1 = enable this feature; 0 = disable this feature. default: enable.</br></td> </tr> <tr> <td width="28%" valign="top">TOUPCAM_OPTION_THREAD_PRIORITY</td> <td width="72%" valign="top">set the priority of the internal thread which grab data from the usb device.</br>0 = THREAD_PRIORITY_NORMAL; 1 = THREAD_PRIORITY_ABOVE_NORMAL; 2 = THREAD_PRIORITY_HIGHEST;</br>default: 0;</br>Please refer to <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms686277(v=vs.85).aspx">SetThreadPriority</a></br></td> </tr> <tr> <td width="28%" valign="top">TOUPCAM_OPTION_PROCESSMODE</td> <td width="72%" valign="top">0 = better image quality, more cpu usage. this is the default value</br>1 = lower image quality, less cpu usage.</br></td> </tr> <tr> <td width="28%" valign="top">TOUPCAM_OPTION_RAW</td> <td width="72%" valign="top">The default is 0 which means RGB mode.</br>1 means RAW mode, read the CMOS or CCD raw data.</br>This value can only be changed BEFORE Toupcam_StartXXX.</br></td> </tr> </table> </div> </blockquote></ul><ul> <li> <h2>Toupcam_put_RealTime, Toupcam_get_RealTime</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>BOOL bEnable: TRUE or FALSE</li> </ul> <p>Remarks: If you set RealTime mode as TRUE, then you get shorter frame delay but lower frame rate which damages fluency. The default value is FALSE.</p> </li> <li> <h2>Toupcam_get_AutoExpoEnable, Toupcam_put_AutoExpoEnable, Toupcam_get_AutoExpoTarget, Toupcam_put_AutoExpoTarget, Toupcam_put_MaxAutoExpoTimeAGain</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>BOOL bAutoExposure: TRUE or FALSE</li> <li>USHORT Target: auto-exposure target</li> <li>ULONG maxTime, USHORT maxAGain: the maximum time and maximum analog gain of auto-exposure</li> </ul> <p>Remarks: If auto exposure is enabled, the exposure time and analog gain are controlled by software to make the average brightness of the target rectangle as close as possible to the auto exposure target. The auto exposure target value is the target brightness of the target rectangle (see Toupcam_put_AEAuxRect, Toupcam_get_AEAuxRect).</p> </li> <li> <h2>Toupcam_get_ExpoTime, Toupcam_put_ExpoTime, Toupcam_get_ExpTimeRange</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>ULONG Time: exposure time, unit: microsecond</li> <li>ULONG* nMin, ULONG* nMax, ULONG* nDef: the minimum, maximum and default value of exposure time.</li> </ul> </li></ul><blockquote> <p>Remarks: exposure time related.</p></blockquote><ul> <li> <h2>Toupcam_get_ExpoAGain, Toupcam_put_ExpoAGain, Toupcam_get_ExpoAGainRange</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>USHORT AGain: analog gain, shown in percentage, eg, 200 means the analog gain is 200%</li> <li>USHORT* nMin, USHORT* nMax, USHORT* nDef: the minimum, maximum and default value of analog gain.</li> </ul> </li></ul><blockquote> <p>Remarks: analog gain related.</p></blockquote><ul> <li> <h2>Toupcam_put_Hue, Toupcam_get_Hue, Toupcam_put_Saturation, Toupcam_get_Saturation, Toupcam_put_Brightness, Toupcam_get_Brightness, Toupcam_get_Contrast, Toupcam_put_Contrast, Toupcam_get_Gamma, Toupcam_put_Gamma</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam h: camera instance handle</p> <p>Remarks: set or obtain hue, saturation, brightness, contrast and gamma.</p> </li> <li> <h2>Toupcam_get_Chrome, Toupcam_put_Chrome</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>BOOL bChrome: TRUE or FALSE</li> </ul> <p>Remarks: color or gray mode</p> </li> <li> <h2>Toupcam_get_VFlip, Toupcam_put_VFlip, Toupcam_get_HFlip, Toupcam_put_HFlip</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam h: camera instance handle</p> <p>Remarks: vertical/horizontal flip.</p> </li></ul><ul> <li> <h2>Toupcam_put_Speed, Toupcam_get_Speed, Toupcam_get_MaxSpeed</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>USHORT nSpeed: frame rate level</li> </ul> <p>Remarks: the minimum frame rate level is "0", the maximum one can be achieved through Function "Toupcam_get_MaxSpeed" which equals to maxspeed in ToupcamModel.</p> <p>Remind: CCD cameras cannot change frame rate setting real-timely, that's to say you can't change the frame rate setting any more after calling the function Toupcam_Startxxxx. Therefore, the frame rate for CCD cameras should be set after function Toupcam_Open but before function Toupcam_Startxxxx.</p> </li> <li> <h2>Toupcam_put_HZ, Toupcam_get_HZ</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>int nHZ: 0: 60Hz alternating current, 1: 50Hz alternating current, 2: direct current</li> </ul> <p>Remarks: set the light source power frequency</p> </li> <li> <h2>Toupcam_put_Mode, Toupcam_get_Mode</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <ul> <li>HToupCam h: camera instance handle</li> <li>BOOL bSkip: Bin mode or Skip mode.</li> </ul></ul><blockquote> <p>Remarks: set Bin mode or Skip mode. Cameras with higher resolution can support two sampling modes, one is Bin mode (Neighborhood averaging), the other is Skip (sampling extraction). In comparison, the former is with better image effect but decreasing frame rate while the latter is just the reverse.</p></blockquote><ul> <li> <h2>Toupcam_put_TempTint, Toupcam_get_TempTint</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <ul> <li>HToupCam h: camera instance handle</li> <li>int nTemp, int nTint: color temperature and Tint</li> </ul></ul><blockquote> <p>Remarks: set/obtain the color temperature and Tint parameters of white balance.</p> <p>Toupcam_TempTint2RGB(...) and Toupcam_RGB2TempTint(...) can be used to convert RGB Gain from / to Temp / Tint. This is to say:</p> <p>RGB adjustment is equal to TEMP/TINT adjustment. If you want to use the RGB adjustment, you can use the following helper functions.</p> <table width="100%" border="0" bgcolor="#B0D0B0"> <tr> <td>void Toupcam_TempTint2RGB(int nTemp, int nTint, int nRGB[3]);<br /> void Toupcam_RGB2TempTint(const int nRGB[3], int* nTemp, int* nTint);</td> </tr></table> <p>When setting RGB, please call Toupcam_RGB2TempTint first and translate RGB values to the Temp and Tint value. Then call Toupcam_put_TempTint to set.</p> <p>When getting RGB, please call Toupcam_get_TempTint first and get the Temp and Tint value. Then call Toupcam_TempTint2RGB to translate the Temp and Tint to RGB. </p></blockquote><ul> <li> <h2>Toupcam_AwbOnePush </h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>PITOUPCAM_TEMPTINT_CALLBACK fnTTProc, void* pTTCtx: callback function and callback context when the automatic white balance completes.</li> </ul> <p>Remarks: For AWB function, basically there are two methods available in the field. One is continuous AWB mode and the other is one push AWB mode. Continuous AWB mode will do the AWB function all the time and one push AWB mode will do the AWB function once triggered. And toupcam cameras use one push AWB mode because this mode is preferred for microscope industry and more accurate. Continuous AWB mode will introduce some errors in some conditions. Call this function to perform one "auto white balance". When the "auto white balance" completes, TOUPCAM_EVENT_TEMPTINT event notify the application (In Pull Mode) and callback happens. In pull mode, this callback is useless, set it to NULL.</p> </li> <li> <h2>Toupcam_put_AWBAuxRect, Toupcam_get_AWBAuxRect, Toupcam_put_AEAuxRect, Toupcam_get_AEAuxRect</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam h: camera instance handle</p> <p>Remarks: set/obtain the ROI (Rectangle of Interest) of automatic white balance and auto-exposure. The default ROI is in the center of the image, its width is 20% image with, its height is 20% image height. </p> </li></ul><ul> <li> <h2>Toupcam_get_MonoMode</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam h: camera instance handle</p> <p>Remarks: gray camera or not, find the flag in ToupCamModel: TOUPCAM_FLAG_MONO </p> </li> <li> <h2>Toupcam_get_StillResolutionNumber, Toupcam_get_StillResolution</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>ULONG nIndex: resolution index</li> <li>LONG* pWidth, LONG* pHeight: width/height</li> </ul> <p>Remarks: Toupcam_get_StillResolutionNumber means the number of supported still resolution. Take UCMOS03100KPA as an example, if we call the function Toupcam_get_StillResolutionNumber and get "3", which means it can support three kinds of resolution. If it doesn't support "still snap", then we get "0". Toupcam_get_Resolution obtains the width/height of each kind of resolution.</p> </li> <li> <h2>Toupcam_get_SerialNumber, Toupcam_get_FwVersion, Toupcam_get_HwVersion</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <ul> <li>HToupCam h: camera instance handle</li> <li>char sn[32]: buffer to the serial number, such as: TP110826145730ABCD1234FEDC56787</li> <li>char fwver[16]: buffer to the firmware version, such as: 3.2.1.20140922</li> <li>char hwver[16]: buffer to the hardware version, such as: 3.2.1.20140922</li> </ul></ul><blockquote> <p>Remarks: each camera has a unique serial number with 31 letters, eg,"TP110826145730ABCD1234FEDC56787"</p></blockquote><ul> <li> <h2>Toupcam_put_LEDState</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul><ul> <li>HToupCam h: camera instance handle</li> <li>unsigned short iLed: the index of LED light </li> <li>unsigned short iState: LED status, 1 -> Ever bright; 2 -> Flashing; other -> Off</li> <li>unsigned short iPeriod: Flashing Period (>= 500ms)</li> </ul></ul> <blockquote> <p>Remarks: One or more LED lights installed on some camera. This function controls the status of these lights.</p></blockquote><ul> <li> <h2>Toupcam_read_EEPROM, Toupcam_write_EEPROM</h2> <p>Return Value: HRESULT type means failure or byte(s) transferred</p> <p>Parameters: </p> </li></ul><ul><ul> <li>HToupCam h: camera instance handle</li> <li>unsigned addr: EEPROM address</li> <li>const unsigned char* pData: data to be written</li> <li>unsigned char* pBuffer: read EEPROM to buffer</li> <li>unsigned nDataLen: data length to be written</li> <li>unsigned nBufferLen: buffer length to read</li> </ul></ul><ul><li><h2>Toupcam_put_ExpoCallback</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <ul> <li>HToupCam h: camera instance handle</li> <li>PITOUPCAM_EXPOSURE_CALLBACK fnExpoProc, void* pExpoCtx: exposure callback function and callback context. If we set fnExpoProc as NULL, then it means stop calling back.</li> </ul></ul><blockquote> <p>Remarks: Once we set non-NULL callback function, then callback happens whenever the exposure time changes.</p></blockquote><ul> <li> <h2>Toupcam_put_ChromeCallback</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <ul> <li>HToupCam h: camera instance handle</li> <li>PITOUPCAM_CHROME_CALLBACK fnChromeProc, void* pChromeCtx: color/gray switches callback function and callback context. If we set fnChromeProc as NULL, then it means stop calling back.</li> </ul></ul><blockquote> <p>Remarks: once we set non-NULL callback function, then callback happens whenever the color/gray switches, eg, call Toupcam_put_Chrome </p></blockquote><ul> <li> <h2>Toupcam_LevelRangeAuto</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: HToupCam h: camera instance handle</p> <p>Remarks: auto Level Range.</p> </li></ul><ul> <li> <h2>Toupcam_put_LevelRange, Toupcam_get_LevelRange</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> <ul> <li>HToupCam h: camera instance handle</li> <li>USHORT aLow[4], USHORT aHigh[4]: Level Range of R, G, B, and Gray. RGB is only available for color image, and gray is only available for gray image.</li> </ul> <p>Remarks: level range related.</p> </li> <li> <h2>Toupcam_GetHistogram</h2> <p>Return Value: HRESULT type means success/failure</p> <p>Parameters: </p> </li></ul><ul> <ul> <li>HToupCam h: camera instance handle</li> <li>PITOUPCAM_HISTOGRAM_CALLBACK fnHistogramProc, void* pHistogramCtx: callback function and callback context of histogram data.</li> </ul></ul><blockquote> <p>Remarks: obtain histogram data.</p></blockquote><hr /><h1><font color="#0000FF">5. .NET and C# and VB.NET</font></h1><hr /><p>Toupcam does support .NET development environment (C# and VB.NET).</p><p>toupcam.cs in the 'inc' directory use P/Invoke call into toupcam.dll. Copy toupcam.cs to your C# project, please reference toupcamdemowinformcs in the samples directory.</p><p>The C# class ToupTek.ToupCam is a thin wrapper class of the native C/C++ API of toupcam.dll, it's properties and methods P/Invoke into the corresponding Toupcam_xxxx functions of toupcam.dll. So, the descriptions of the Toupcam_xxxx function are also applicable for the corresponding C# properties or methods. For example, the C# Snap method call the function Toupcam_Snap, the descriptions of the Toupcam_Snap function is applicable for C# Snap method:<table width="100%" border="0" bgcolor="#B0D0B0"> <tr> <td>[DllImport("toupcam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]<br /> private static extern int Toupcam_Snap(SafeHToupCamHandle h, uint nResolutionIndex);<br /><br /> public bool Snap(uint nResolutionIndex)<br /> {<br /> if (_handle == null || _handle.IsInvalid || _handle.IsClosed)<br /> return false;<br /> return (Toupcam_Snap(_handle, nResolutionIndex) >= 0);<br />}</td> </tr></table><p>VB.NET is similar with C#, not otherwise specified.</p><hr /><h1><font color="#0000FF">6. Others</font></h1><hr /><ul> <li>Ranges and default value of some parameters</li></ul><div align="center"> <table width="50%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0"> <tr> <td width="30%" valign="top">Parameters</td> <td width="26%" valign="top">Range </td> <td width="44%" valign="top">Default value</td> </tr> <tr> <td width="30%" valign="top">AutoExpoTarget</td> <td width="26%" valign="top">10~230</td> <td width="44%" valign="top">120</td> </tr> <tr> <td width="30%" valign="top">Temp</td> <td width="26%" valign="top">2000~15000</td> <td width="44%" valign="top">6503</td> </tr> <tr> <td width="30%" valign="top">Tint</td> <td width="26%" valign="top">200~2500</td> <td width="44%" valign="top">1000</td> </tr> <tr> <td width="30%" valign="top">LevelRange</td> <td width="26%" valign="top">0~255</td> <td width="44%" valign="top">Low = 0, High = 255</td> </tr> <tr> <td width="30%" valign="top">Contrast</td> <td width="26%" valign="top">-100~100</td> <td width="44%" valign="top">0</td> </tr> <tr> <td width="30%" valign="top">Hue</td> <td width="26%" valign="top">-180~180</td> <td width="44%" valign="top">0</td> </tr> <tr> <td width="30%" valign="top">Saturation</td> <td width="26%" valign="top">0~255</td> <td width="44%" valign="top">128</td> </tr> <tr> <td width="30%" valign="top">Brightness</td> <td width="26%" valign="top">-64~64</td> <td width="44%" valign="top">0</td> </tr> <tr> <td width="30%" valign="top">Gamma</td> <td width="26%" valign="top">20~180</td> <td width="44%" valign="top">100</td> </tr> </table></div><ul> <li>Platform <ul> <li>Windows: x86/x64; XP SP3 or above; SSE2 instruction set or above</li> <li>OSX: x64; 10.7 or above</li> <li>Linux: SSE3 instruction set or above; kernel 2.6.27 (Released in October 2008) or above <ul> <li>x86: GLIBC 2.9 (Released in November 2008) or above</li> <li>x64: GLIBC 2.14 (Released in June 2011) or above </li> </ul> </li> </ul> </li></ul><hr /><h1><font color="#0000FF">7. Changelog</font></h1><hr /><p>v1.1: support RAW format; support Linux and osx </p><p>v1.0: initial release</p><hr /><h1><font color="#0000FF">8. Contact Information</font></h1><hr /><p>If you have any problems in using this SDK, please use the following information to contact us.<br /> www: <a href="http://www.touptek.com">www.touptek.com</a><br /> email: [email protected]</p></body></html>