# ToupCam Native API 手册

# 1. 版本

> 1.0.2774.20140217

# 2. 介绍

ToupCam系列相机（包含UCMOS, U3CMOS, UHCCD, EXCCD, SCCCD等型号系列）支持多种API，包括：Native C/C++，.Net/C#, DirectShow, Twain, LabView等等. Native C/C++ API作为底层(Low Level) API相比较其他API的特点是使用纯C/C++开发，不依赖其他的运行时库，接口简洁，控制灵活. 本SDK压缩包包含了所有需要用到的的资源和信息, 目录如下:

- inc目录

> toupcam.h, C/C++ 头文件
> toupcam.cs, 支持.Net/C#. toupcam.cs使用P/Invoke调用至toupcam.dll. 请把toupcam.cs 拷贝到你的.Net/C#工程中使用.

- x86目录

> toupcam.lib, x86 lib 文件.
> toupcam.dll, x86 动态库文件.
> toupcamdemocpp.exe, x86 C++ demo执行程序.

- x64目录

> toupcam.lib, x64 lib文件.
> toupcam.dll, x64 动态库文件.
> toupcamdemocpp.exe, x64 C++ demo 执行程序.

- drivers目录

> x86 文件夹包含x86的内核态驱动文件,包括toupcam.cat, toupcam.inf 和 toupcam.sys.
> x64 文件夹包含x64的内核态驱动文件,包括toupcam.cat, toupcam.inf 和 toupcam.sys.

- samples目录

- toupcamdemocpp, C++例子.本例子演示了枚举设备，打开设备，预览视频，抓拍图像，多种图片格式(.bmp, .jpg, .png等)保存图像到文件，wmv格式录像等等.这个例子使用了Pull Mode机制. 为了保持代码整洁, 例子使用的WTL库可以从这个链接下载http://sourceforge.net/projects/wtl/
- toupcamdemomfc, 一个非常简单的例子，使用MFC作为GUI库，支持打开设备，预览视频，设置分辨率等.这个例子使用了Pull Mode机制.
- toupcamdemowinform, c# winform例子. 这个例子使用了Pull Mode机制.

- extras目录

> directshow 目录包含directshow SDK和demo程序
> twain 目录包含twain SDK 和demo程序
> labview 目录包含labview SDK 和demo程序.

- doc目录

> 包含中英文SDK使用文档.

# 3. 获取图像数据的模式: Pull Mode vs Push Mode

Toupcam提供了两种模式来获取图像数据: Pull Mode 和 Push Mode. 前者更有优势因为它更简单,且在多线程情况下更加稳定可靠, 尤其是使用windows消息机制的情况下.

- Pull Mode, toupcam 扮演被动角色. 内部线程从相机获得图像数据,并保存到内部缓存中, 然后通知应用程序来取图像数据. 应用程序可以调用 Toupcam_PullImage和Toupcam_PullStillImage来获取图像数据.下面列出两种方式来通知应用程序以供参考:
  - 使用Windows消息机制: 通过调用函数 Toupcam_StartPullModeWithWndMsg启动Pull mode模式. 当事件发生时,toupcam会主动发送消息到指定窗口. 参数WPARAM 是时间类型, 请参考TOUPCAM_EVENT_xxxx的定义.
  - 使用回调函数使用 Toupcam_StartPullModeWithCallback启动Pull mode模式. 当事件发生时, 会调用PTOUPCAM_EVENT_CALLBACK回调函数（请注意这个回掉函数是在toupcam.dll内部线程上下文中执行的）.

> 在Pull Mode 情况下, toupcam不但可以通知应用程序图像数据或者静态图片到达，还可以通知其他事件类型，如下所示:

> TOUPCAM_EVENT_EXPOSURE | 曝光时间发生改变
> TOUPCAM_EVENT_TEMPTINT | 白平衡参数发生改变
> TOUPCAM_EVENT_IMAGE | 视频图像数据到达(视频).使用Toupcam_PullImage获取数据
> TOUPCAM_EVENT_STILLIMAGE | 静态图片数据到达(Toupcam_Snap引发).使用Toupcam_PullStillImage获取数据
> TOUPCAM_EVENT_ERROR | 发生错误，数据采集不能继续

- Push Mode情况下, toupcam作为主动方，一旦内部底层线程从camera中抓取到图像数据，就通过PTOUPCAM_DATA_CALLBACK回调数据(请注意这个回掉函数是在toupcam.dll内部线程上下文中执行的).调用Toupcam_StartPushMode函数进入推模式.推模式比较复杂，有一些特别注意事项（如多线程问题，也不能在PTOUPCAM_DATA_CALLBACK回调函数里面调用Toupcam_Close和Toupcam_Stop等等）.

# 4. 函数

- ## Toupcam_Enum

> 返回值：非负整数，枚举到的相机数目

> 参数：ToupcamInst缓冲区

> 说明：调用该函数枚举计算机上当前插上的Toupcam相机.函数返回时，ToupcamInst缓冲区包含有枚举到的每个相机实例的信息.如果不关心多个相机同时联入电脑的情况的话，调用本函数枚举相机实例是可选的.

> > 如下面的代码片段：

> ToupcamInst arr[TOUPCAM_MAX]; unsigned cnt = Toupcam_Enum(arr); for (unsigned i = 0; i < cnt; ++i) ......

> typedef struct{ #ifdef _WIN32 const wchar_t* name; /* model name */ #else const char* name; #endif unsigned flag; /* TOUPCAM_FLAG_xxx */ unsigned maxspeed; /* number of speed level, Toupcam_get_MaxSpeed, the speed range = [0, max], closed interval */ unsigned preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */ unsigned still; /* number of still resolution, Toupcam_get_StillResolutionNumber */ ToupcamResolution res[TOUPCAM_MAX]; }ToupcamModel;

- ## Toupcam_Open

  返回值：HToupCam句柄.失败时返回NULL（如设备被突然拔出等等）

  参数：ToupCam相机实例，由Toupcam_Enum枚举得到.如果 id 是NULL 则自动打开第一个相机，所以，如果不关心多个相机实例同时连入电脑的情况，Toupcam_Enum 不是必须的，直接传入参数NULL 打开唯一的相机实例.

  说明：打开相机实例.

- ## Toupcam_Close

  返回值：无

  参数：HToupCam句柄

  说明：关闭相机实例.句柄关闭之后，请不要再使用之.不要在推模式的 PTOUPCAM_DATA_CALLBACK 回调函数里面调用Toupcam_Close，否则，会死锁.

- ## Toupcam_StartPullModeWithWndMsg , Toupcam_StartPullModeWithCallback

  返回值：HRESULT类型表示成功失败

  参数：

  - HToupCam h：由Toupcam_Open打开的实例句柄
  - HWND hWnd: 事件发生时，消息将Post到这个窗口
  - UINT nMsg: Windows自定义消息类型.消息的WPARAM参数是事件类型TOUPCAM_EVENT_xxxx，LPARAM参数不用（恒等于0）
  - PTOUPCAM_EVENT_CALLBACK pEventCallback, void* pCallbackContext：用户程序指定的回调函数和回调上下文参数.

- ## Toupcam_PullImage, Toupcam_PullStillImage

  返回值：HRESULT类型表示成功失败

  参数：

  - HToupCam h：由Toupcam_Open打开的实例句柄
  - void* pImageData：数据缓冲区.用户应用程序必须确保改缓冲区足够大，以容纳图像数据
  - int bits：图像颜色位数，支持24, 32和8，分别代表RGB24, RGB32, 8位灰度图像
  - unsigned* pnWidth, unsigned* pnHeight：图像的宽度高度

  说明：当pImageData为NULL而pnWidth, pnHeight参数不为NULL的时候，可以获取(Peek)图像的宽度高度信息

- ## Toupcam_StartPushMode

  返回值：HRESULT类型表示成功失败

  参数：

  - HToupCam h：由Toupcam_Open打开的实例句柄
  - PTOUPCAM_DATA_CALLBACK pDataCallback, void* pCallbackCtx：用户程序指定的回调函数和回调上下文参数.toupcam.dll内部从相机得到的图像数据后，会回调该函数.

> > typedef void (*PTOUPCAM_DATA_CALLBACK)(const void* pData, const BITMAPINFOHEADER* pHeader, BOOL bSnap, void* pCallbackCtx);

> > 如果回调时，pData参数==NULL，表示发生内部错误（如相机被突然拔出等等）.
> > BOOL bSnap参数，TRUE表示是由Toupcam_Snap函数发起的图片抓拍，FALSE表示普通的预览图片（视频）.
> > 注意：该回调函数是从toupcam.dll的内部线程上下文中回调出来，所以，非常有必要关注多线程问题.请尽量保持回调函数代码的简洁，并且快速返回.不要在回调函数上下文调用Toupcam_Stop或Toupcam_Close函数，否则，会死锁.正式因为使用Push模式的复杂性，所以，推荐使用Pull模式（特别是使用窗口消息通知事件）.

> 说明：开启相机实例.

- ## Toupcam_Stop

> 返回值：HRESULT类型表示成功失败

> 参数：HToupCam句柄

> 说明：停止相机实例.如果使用推模式（Push Mode），请不要在PTOUPCAM_DATA_CALLBACK回调函数里面调用Toupcam_Stop，否则，会死锁.停止之后，可以调用Toupcam_StartPushMode重新开启.比如切换视频分辨率：

> 步骤1：调用Toupcam_Stop停止

> 步骤2：调用Toupcam_put_Size或者Toupcam_put_eSize设置新分辨率

> 步骤3：调用Toupcam_Startxxxx重新开启

- ## Toupcam_Pause

  返回值：HRESULT类型表示成功失败

  参数：HToupCam句柄

  说明：暂停或者继续相机实例

- ## Toupcam_Snap

  返回值：HRESULT类型表示成功失败

  参数：

  - HToupCam h：相机实例句柄
  - ULONG nResolutionIndex：想要抓拍的分辨率序号.

> 说明：抓拍图片.抓拍成功之后，通过PTOUPCAM_DATA_CALLBACK回调函数返回，这种情况下，回调函数的参数BOOL bSnap设为TRUE.

> 有些相机支持在预览视频的不间断的情况下，抓拍单张的不同于正在视频预览的分辨率的所谓静态图片.例如UCMOS03100KPA，正在预览的分辨率是1024*768，调用Toupcam_Snap(h, 0)抓拍单张第0号分辨率（2048*1536）的图片.预览使用小分辨率（追求更快的帧率），抓拍使用大分辨率（追求更好的图片质量）.这种行为，称之为“静态抓拍”.
> 对于不支持静态抓拍的相机型号，则参数nResolutionIndex的值必须等于当前正在预览的分辨率，否则，函数返回E_UNEXPECTED.
> 某个型号是否支持静态抓拍能力，参见ToupcamModel的still域(大于0).

- ## Toupcam_put_Size, Toupcam_get_Size, Toupcam_put_eSize, Toupcam_get_eSize

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> ULONG nResolutionIndex：当前分辨率序号

> LONG nWidth, LONG nHeight：当前分辨率的宽度高度

> 说明：设置或者得到当前分辨率.

> 设置分辨率应该在ToupCam_Startxxxx之前进行.
> 有2种方法设置当前分辨率，一种是通过分辨率的序号，一种是通过宽度/高度.两种方法是等效的.比如UCMOS03100KPA支持以下3种分辨率:
> 序号0: 2048, 1536
> 序号1: 1024, 768
> 序号2: 680, 510
> 所以Toupcam_put_Size(h, 1024, 768) or Toupcam_put_eSize(h, 1)效果一样.

- ## Toupcam_get_ResolutionNumber, Toupcam_get_Resolution

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> ULONG nIndex：分辨率序号

> LONG* pWidth, LONG* pHeight：宽度、高度

> 说明：Toupcam_get_ResolutionNumber得到支持的分辨率个数（如UCMOS03100KPA返回3，表示支持3种分辨率）.Toupcam_get_Resolution得到每种分辨率的高度/宽度.

> 这些参数在Toupcam_Enum返回相机实例的ToupcamModel都已经包含.

- ## Toupcam_put_ProcessMode, Toupcam_get_ProcessMode

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> unsigned nProcessMode：处理模式

> TOUPCAM_PROCESSMODE_FULL：full模式，图像质量更好，但是更耗费CPU
> TOUPCAM_PROCESSMODE_FAST：fast模式，图像质量差些，耗费更少的CPU
> 说明：根据具体的使用情况选择FULL模式还是FAST模式.默认是FULL模式.

- ## Toupcam_put_RealTime, Toupcam_get_RealTime

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> BOOL bEnable：TRUE or FALSE

> 说明：如果设置RealTime模式为TRUE，更短的帧延时，但是帧速率降低，流畅性受损.缺省设为FALSE，一般不需要改动.

- ## Toupcam_get_AutoExpoEnable, Toupcam_put_AutoExpoEnable, Toupcam_get_AutoExpoTarget, Toupcam_put_AutoExpoTarget, Toupcam_put_MaxAutoExpoTimeAGain

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> BOOL bAutoExposure：TRUE or FALSE

> BYTE Target：自动保管目标

> ULONG maxTime, USHORT maxAGain：自动曝光的最大曝光时间和最大模拟增益

> 说明：自动曝光，自动曝光的目标.

- ## Toupcam_get_ExpoTime, Toupcam_put_ExpoTime, Toupcam_get_ExpTimeRange

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> ULONG Time：曝光时间，单位微秒

> ULONG* nMin, ULONG* nMax, ULONG* nDef：曝光时间的最小值，最大值，默认值

> 说明：曝光时间相关.

- ## Toupcam_get_ExpoAGain, Toupcam_put_ExpoAGain, Toupcam_get_ExpoAGainRange

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> USHORT AGain：模拟增益，百分比，如200表示增益200%

> USHORT* nMin, USHORT* nMax, USHORT* nDef：模拟增益的最小值，最大值，默认值

> 说明：模拟增益相关.

- ## 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

  返回值：HRESULT类型表示成功失败

  参数：HToupCam h：相机实例句柄

  说明：设置或者得到：色度，饱和度，亮度，对比度，Gamma

- ## Toupcam_get_Chrome, Toupcam_put_Chrome

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> BOOL bChrome：TRUE or FALSE

> 说明：多色模式或者单色模式.

- ## Toupcam_get_VFlip, Toupcam_put_VFlip, Toupcam_get_HFlip, Toupcam_put_HFlip

  返回值：HRESULT类型表示成功失败

  参数： HToupCam h：相机实例句柄

  说明：垂直或者水平翻转

- ## Toupcam_put_Speed, Toupcam_get_Speed, Toupcam_get_MaxSpeed

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> BYTE nSpeed：帧速率级别

> 说明：最小帧速率等级是0.最大帧速率级别可以通过Toupcam_get_MaxSpeed函数得到，和ToupcamModel的maxspeed是一个意思.

> 提醒：CCD型号不能实时改变帧速率设置，也即在调用Toupcam_Startxxxx之后就不能再改变帧速率设置.所以，针对CCD型号的帧率设置，应该在Toupcam_Open之后，Toupcam_Startxxxx之前.

- ## Toupcam_put_HZ, Toupcam_get_HZ

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> int nHZ：0表示60Hz交流，1表示50Hz交流，2表示直流

> 说明：设置光源的电力供应频率

- ## Toupcam_put_Mode, Toupcam_get_Mode

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> BOOL bSkip：Bin模式或者Skip模式

> 说明：设置Bin模式或者Skip模式.较高分辨率的相机支持2种采样模式，一种是Bin模式（邻域平均），一种是Skip模式（抽样提取）.相比较而言，前者图像效果较好，但是帧速率降低；后者帧速率较高，但是图像效果较差.

- ## Toupcam_put_TempTint, Toupcam_get_TempTint

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> int nTemp, int nTint：色温和Tint

> 说明：设置/获取白平衡的色温和Tint参数.

- ## Toupcam_AwbOnePush

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> PITOUPCAM_TEMPTINT_CALLBACK fnTTProc, void* pTTCtx：自动白平衡过程完成时的回调函数以及回调上下文.

> 说明: 自动白平衡功能,业界有两种模式, 一种是连续自动白平衡,一种是触发自动白平衡(one push). 连续自动白平衡功能会一直进行白平衡参数的计算, 触发模式只是在触发的时候才会计算白平衡参数. Toupcam使用了触发式白平衡计算方法因为这种方法在显微镜等领域更加合适和精确. 连续自动白平衡在某些场景情况下会出现错误. 调用这个函数来触发单次白平衡功能. 当白平衡参数计算完成的时候, TOUPCAM_EVENT_TEMPTINT 事件会通知应用程序 (In Pull Mode) 和调用回调函数. pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.

- ## Toupcam_put_AWBAuxRect, Toupcam_get_AWBAuxRect, Toupcam_put_AEAuxRect, Toupcam_get_AEAuxRect

  返回值：HRESULT类型表示成功失败

  参数：HToupCam h：相机实例句柄

  说明：设置/获取自动白平衡和自动曝光的参考矩形

- ## Toupcam_get_MonoMode

  返回值：HRESULT类型表示成功失败

  参数：HToupCam h：相机实例句柄

  说明：是否单色相机，对应ToupCamModel的flag: TOUPCAM_FLAG_MONO

- ## Toupcam_get_StillResolutionNumber, Toupcam_get_StillResolution

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> ULONG nIndex：分辨率序号

> LONG* pWidth, LONG* pHeight：宽度、高度

> 说明：Toupcam_get_StillResolutionNumber得到支持的静态抓拍分辨率个数（如UCMOS03100KPA返回3，表示支持3种分辨率），如果不支持静态抓拍能力，返回0.Toupcam_get_StillResolution得到每种分辨率的高度/宽度.

- ## Toupcam_get_SerialNumber

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> char sn[32]：存放序列号的缓冲区

> 说明：每个相机都有一个唯一的31位的序列号.如：“TP110826145730ABCD1234FEDC56787”

- ## Toupcam_put_ExpoCallback

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> PITOUPCAM_EXPOSURE_CALLBACK fnExpoProc, void* pExpoCtx：曝光回调函数以及回调上下文.设置fnExpoProc为NULL，表示停止回调.

> 说明：一旦设置了非NULL的回调函数，每当曝光时间变化时，回调发生.设置fnExpoProc为NULL，表示不再回调.

- ## Toupcam_put_ChromeCallback

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> PITOUPCAM_CHROME_CALLBACK fnChromeProc, void* pChromeCtx：多色/单色切换回调函数以及回调上下文.设置fnChromeProc为NULL，表示不再回调.

> 说明：一旦设置了非NULL的回调函数，每当单色/多色切换时（如调用Toupcam_put_Chrome），回调发生.

- ## Toupcam_LevelRangeAuto

  返回值：HRESULT类型表示成功失败

  参数：HToupCam h：相机实例句柄

  说明：自动LevelRange

- ## Toupcam_put_LevelRange, Toupcam_get_LevelRange

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> BYTE aLow[4], BYTE aHigh[4]: Level Range

> 说明：LevelRange相关.

- ## Toupcam_GetHistogram

  返回值：HRESULT类型表示成功失败

  参数：

> HToupCam h：相机实例句柄

> PITOUPCAM_HISTOGRAM_CALLBACK fnHistogramProc, void* pHistogramCtx：直方图数据的回调函数以及回调上下文

> 说明：获取直方图数据

# 5. C#和.Net

Toupcam支持.Net和C#开发环境.

inc目录下toupcam.cs使用P/Invoke调用至toupcam.dll. 把toupcam.cs 拷贝到你的.Net/C#工程中使用，请参考例子代码samples\toupcamdemowinform.

ToupTek.ToupCam c#类的属性和方法等等，直接调用toupcam.dll中对应的原生Toupcam_xxx函数. 所以，关于Toupcam_xxx的文档说明都适用于c#中对应的属性或方法，比如，c#中的Snap方法调用Toupcam_Snap函数，关于Toupcam_Snap函数的说明同样适用于c# ToupCam类的Snap方法：

[DllImport("toupcam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern int Toupcam_Snap(SafeHToupCamHandle h, uint nResolutionIndex); public bool Snap(uint nResolutionIndex) { if (_handle == null || _handle.IsInvalid || _handle.IsClosed) return false; return (Toupcam_Snap(_handle, nResolutionIndex) >= 0); }

# 6. 其他

一些参数的范围以及默认值

> 参数 | 范围 | 默认值
> AutoExpoTarget | 10~230 | 120
> Temp | 2000~15000 | 6503
> Tint | 200~2500 | 1000
> LevelRange | 0~255 | Low = 0, High = 255
> Contrast | -100~100 | 0
> Hue | -180~180 | 0
> Saturation | 0~255 | 128
> Brightness | -64~64 | 0
> Gamma | 20~180 | 100

# 7. 联系信息

如果在使用ToupCam SDK的过程中，碰到任何问题，请与我们联系
网站：www.touptek.com www.toupcam.com
QQ:862347751
EMAIL：support@touptek.com