H-SDK说明书.doc

华旗数码技术实验室有限责任公司Digital Lab Inc DLC SDK 用户使用指南 V1。0华旗数码技术实验室有限责任公司Digital Lab Inc二零零六年二月九日 目录1、 版本更新说明 22、 返回值类型说明 63、 HqDLInitialize64、 HqDLStartView 85、 HqDLStopView 96、 HqDLPauseView 107、 HqDLUninitialize118、 HqDLSetCapInfo 129、 HqDLGetFrameRate 1310、 HqDLGetRawFrame1411、 HqDLGetRgbFrame1512、 HqDLGetPausedFrame 1613、 HqDLGetPausedFrameToBmp 1714、 HqDLGetRawFrameToBmp 1815、 HqDLGetRgbFrameToBmp 1916、 HqDLSetParam -2017、 HqDLSetGammaValue 2118、 HqDLSetFrameCallback 2219、 HqDLEnableColorOffset 2320、 HqDLBitOperation2421、 HqDLRegOperation2522、HqDLSetDoAWB2623、HqDLSetDoAE2724、HqDLSetDoAF2825、HqDLSetViewWin2926、HqDLGetViewWin3027、HqDLGetTotalDeviceNum3128、HqDLGetSerialsNum 3229、HqDLCalibration 3330、HqDLNoiseCalibration3431、HqDLAutoFocus3532、HqDLLedControl3633、HqDLCaptureToAvi371、版本更新说明 版本： V1.0.0.1更新日期：2005.12.13库说明:对于所有华旗数码实验室的摄像头提供统一接口对于功能最强大的智能证照检查仪提供所有可操作接口对于其他简化版摄像头有些接口不要调用比如对于White Hawk不支持HqDLBitOperation对于黑白摄像头不支持HqDLSetDoAWB,并且对于黑白摄像头,用原始数据预览并采集是标准的方式,但黑白摄像头也可以用彩色摄像头的方式操作. 版本：V1.0.0.3更新日期：2006.1.4库说明:加入噪点检测函数HqDLNoiseCalibration加入位置调节函数HqDLSizeCalibration 版本： V1.0.0.4更新日期：2006.1.18 库说明:加入控制电机HqDLAutoFocus及光源函数HqDLLedControl 版本： V1.0.0.6更新日期：2006.1.25 库说明:加入avi录影HqDLCaptureToAvi及自动调焦功能HqDLSetDoAF注：提供的开发包的所有操作都是针对24比特BMP图像。2、返回值类型说明ResSuccess0x0000/ 返回成功ResNullHandleErr0x0001/ 无效句柄ResNullPointerErr0x0002/ 指针为空ResFileOpenErr0x0003/ 文件打开失败ResNoDeviceErr0x0004/ 没有设备连接ResInvalidParameterErr0x0005/ 无效的参数ResOutOfMemoryErr0x0006/ 内存溢出ResNoPreviewRunningErr0x0007/ 预览没有开启ResOSVersionErr0x0008/ 操作系统版本错误ResUsbNotAvailableErr0x0009/ 设备无效ResNotSupportedErr0x000a/ 设备不支持此功能ResNoSerialString0x000b/ 读取不到序列号ResVerificationErr0x000c/ 效验失败ResTimeoutErr 0x000d/ 超时ResScaleModeErr0x000f/ 缩放错误ResUnknownErr0x00ff/ 未知错误ResDisplayWndExist0x0011/ 应该关闭预览窗口ResAllocated0x0012/ 内存已经分配ResAllocateFail0x0013/ 内存分配失败ResReadError0x0014 / USB读取失败ResWriteError0x0015/ USB命令发出失败ResUsbOpen0x0016 / USB端口已经打开ResCreateStreamErr0x0017/ 创建avi流失败ResSetStreamFormatErr0x0018/ 设置AVI流格式失败3、HqDLInitialize函数:HQDL_API HqDLInitialize(IN LPCTSTRpFilterName,OUT int*pIndex,IN CapInfoStruct*pCapInfo,OUT HANDLE*hCamera);功能:初始化设备，返回摄像头句柄，用于其它函数的调用参数: pIndex返回摄像头索引pFilterName保留pCapInfo初始化摄像头参数 hCamera返回给调用者的设备句柄 说明: 必须要给pCapInfo-Buffer分配足够的内存空间，一般要分配比最大的采集空间要大一些，推荐用MAXWIDTH*MAXHEIGHT+512，用于传递采集数据说明: 此函数要先于所有的API函数，并且每一次调用，都要有HqDLUninitialize相对应。当返回ResSuccess时表示函数调用成功，hCamera是返回给用户设备句柄。这个句柄将作为其它API函数的参数。*注1：摄像头的索引值从0开始计数。用户可以通过索引值同时操作多个摄像头。*注2：摄像头的索引值在每次重新启动计算机后有可能发生改变。一般是根据插入的顺序由操作系统搜索设备。CapInfoStruct结构定义：struct CapInfoStruct UCHAR*Buffer;/ 用户分配，用于接收采集的原始数据8bitULONGHeight;/ 采集高度ULONGWidth;/ 采集宽度ULONGOffsetX;/ 水平偏移ULONGOffsetY;/ 垂直偏移ULONGExposure;/ 曝光值 1-500MSUCHARGain3;/ R G B 增益 1-63UCHARControl;/ 控制位UCHARInternalUse;/ 用户不要对此字节进行操作UCHARColorOff3;/ 用户从外面不要改变此数组的值，要调用EnableColorOffset来改变UCHARReserved4;/ 保留位;注3：对于3M像素的设备，Exposure的取值范围一般在300MS左右。注4：Control一般只在GoldenHawk系列产品中使用，对于其他设备，初始化为0。4、HqDLStartView函数:HQDL_API HqDLStartView( IN HANDLEhCamera, IN LPCTSTRlpszWindowName, IN DWORDdwStyle, IN intx, IN inty, IN intnWidth, IN intnHeight, IN HWNDhwndParent, IN HMENUnIDorHMenu );功能:打开预览窗口,并启动视频流参数: hCamera通过调用HqDLInitialize得到的设备句柄 说明: 主要参数请参见CWnd：CreateEx函数说明。5、HqDLStopView函数:HQDL_API HqDLStopView( IN HANDLE hCamera );功能:停止视频流参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 6、HqDLPauseView函数:HQDL_API HqDLPauseView( IN HANDLE hCamera, IN BOOL bPause );功能:暂停视频流参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 7、HqDLUninitialize函数:HQDL_API HqDLUninitialize( IN HANDLE *hCamera );功能:反初始化设备参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 必须在程序退出时调用,用于释放内存分配空间8、HqDLSetCapInfo函数:HQDL_API HqDLSetCapInfo( IN HANDLE hCamera , IN CapInfoStruct *pCapInfo );功能:实时设置视频参数参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 9、HqDLGetFrameRate函数:HQDL_API HqDLGetFrameRate( IN HANDLEhCamera, OUT float *pfFrameRate );功能:得到摄像头的当前帧率参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 10、HqDLGetRawFrame函数:HQDL_API HqDLGetRawFrame(IN HANDLE hCamera, IN struct CapInfoStruct *pCapInfo);功能:采集一帧原始数据到pCapInfo-Buffer中参数: hCamera通过调用HqDLInitialize得到的设备句柄 说明: 11、HqDLGetRgbFrame函数:HQDL_APIHqDLGetRgbFrame(IN HANDLE hCamera, IN struct CapInfoStruct *pCapInfo, OUT BYTE* pDest);功能:hCamera通过调用HqDLInitialize得到的设备句柄参数: 说明: 采集一帧24bitRGB数据到pDest中，同时原始数据会保存在pCapInfo-Buffer中，pDest中的结果会根据CAMPARAM中的设定而改变，如果设置bClearView,pDest中是经过优化的转换算法而得到24bit的结果，如果设置bBW,那么是转换为8bit的灰度图像数据，如果设置UPDOWN则图像数据会做相应的垂直翻转。12、HqDLGetPausedFrame函数:HQDL_API HqDLGetPausedFrame(IN HANDLE hCamera, OUT BYTE* pDest);功能:根据当前暂停的视频，得到暂停的视频数据参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 通过调用此函数所得到的图像是当用户调用HqDLPauseView时暂存在内存中，等待用户来取得。参见HqDLPauseView函数。注：调用此函数时，视频流必须处于暂停状态。13、HqDLGetPausedFrameToBmp函数:HQDL_API HqDLGetPausedFrameToBmp(IN HANDLE hCamera, OUT BYTE* pDest, LPCTSTR strFileName );功能:将当前暂停视频保存为BMP文件参数: hCamera通过调用HqDLInitialize得到的设备句柄说明：通过调用此函数所得到的图像是当用户调用HqDLPauseView时暂存在内存中，等待用户来取得。参见HqDLPauseView函数。注：调用此函数时，视频流必须处于暂停状态。14、HqDLGetRawFrameToBmp函数:HQDL_API HqDLGetRawFrameToBmp(IN HANDLE hCamera, IN struct CapInfoStruct *pCapInfo, LPCTSTR strFileName );功能:采集一帧原始数据到pCapInfo-Buffer中的同时，将原始数据以8位位图的格式进行保存。参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 注：pCapInfo-Buffer必须由用户分配空间。15、HqDLGetRgbFrameToBmp函数:HQDL_API HqDLGetRgbFrameToBmp( IN HANDLE hCamera, IN struct CapInfoStruct *pCapInfo, OUT BYTE* pDest, LPCTSTR strFileName ); 功能:采集一帧图像到文件，文件格式会根据CAMPARAM中的设定改变。如果设置bClearView,pDest中是经过优化的转换算法而得到24bit的结果，如果设置bBW,那么是转换为8bit的灰度图像数据，如果设置UPDOWN则图像数据会做相应的垂直翻转。参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 注：pCapInfo-Buffer的空间必须在用户调用此函数前进行分配。如果用户不想通过pDest得到Rgb数据，可以将pDest设置为NULL,这样开发包不会在保存文件的同时，拷贝数据到pDest中。16、HqDLSetParam函数:HQDL_API HqDLSetParam(IN HANDLE hCamera, DLPARAM DLParam, ULONG Value );功能:设置图像参数参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: DLParam定义如下：enum DLPARAM BWSHOW = 0,/ 是否黑白显示RAWDATASHOW,/ 是否直接显示原始数据CLEARVIEW,/ 是否利用优化算法进行转换UPDOWN,/ 上下翻转;17、HqDLSetGammaValue函数:HQDL_API HqDLSetGammaValue( IN HANDLE hCamera, IN float fGammaValue, IN BOOL bGammaOn);功能:加入Gamma校正功能参数: hCamera通过调用HqDLInitialize得到的设备句柄fGammaValue 推荐范围 1 200bGammaOn TRUE 加入Gamma校正功能说明: 18、HqDLSetFrameCallback函数:HQDL_API HqDLSetFrameCallback( IN HANDLE hCamera, DL_FRAMECALLBACK pfFrameCallback, LPVOID lpContext );功能:用于鼠标在预览窗口上点击的回调，lpParam为用户上下文参数: hCamera通过调用HqDLInitialize得到的设备句柄pfFrameCallback 用户给定的每帧到达时的回调函数地址lpContext用户上下文说明: 回调函数的定义：typedef VOID (WINAPI *DL_FRAMECALLBACK)( LPVOID lpParam1, LPVOID lpPoint, LPVOID lpContext );lpParam1 - 指向显示数据指针lpPoint - 鼠标点击图像位置lpContext- 上下文回调函数的使用方法：19、HqDLEnableColorOffset函数:HQDL_API HqDLEnableColorOffset( IN HANDLE hCamera, IN int nRedOffset, IN int nGreenOffset, IN int nBlueOffset, IN BOOL bColorOffset );功能:进行颜色偏移量的调节参数:hCamera通过调用HqDLInitialize得到的设备句柄nRedOffset -255 255nGreenOffset-255 255nBlueOffset-255 255说明: 这3个色彩偏移量分别对应硬件中3个控制色彩的寄存器。20、HqDLBitOperation函数:HQDL_API HqDLBitOperation( IN HANDLE hCamera, IN BYTE Out, OUT BYTE *pIn, IN UCHAR Command );功能:对于智能证照检查仪，GoldenEagle，WhiteHawk的特殊操作参数:保留,调用此函数时不允许开启视频说明: 用户暂不要调用。21、HqDLRegOperation 函数:HQDL_API HqDLRegOperation( IN HANDLE hCamera, IN BYTE RegAddress, IN OUT USHORT* Value, IN BOOL bWrite);功能:对于GoldenHawk，GoldenEagle，WhiteHawk的特殊操作参数:保留,调用此函数时不允许开启视频说明: 用户暂不要调用。22、HqDLSetDoAWB函数:HQDL_API HqDLSetDoAWB( IN HANDLE hCamera, IN BOOL bAWB, IN BYTE btTarget, IN DL_AUTOCALLBACK pfAWBCallback, IN LPVOID lpContext );功能: 设置白平衡操作完成的回调函数参数: hCamera通过调用HqDLInitialize得到的设备句柄pfAWBCallback 指定AWB结束后的回调函数指针VOID (WINAPI *DL_AUTOCALLBACK )( DWORD dw1, LPVOID lpContext );lpParam1是指向AWB结果的指针，通过lpParam1来获得AWB结果如下：ULONG Result = dw1;/ 0xFF202020BYTE btRed= ( BYTE )(Result);/ 0x20BYTE btGreen= ( BYTE )( Result8 );/ 0x20BYTE btBlue= ( BYTE )( Result16 );/ 0x20ULONG Exposure = ( BYTE )( Result24 ) * 2;/ 255 * 2 = 510 ms说明: 当白平衡操作完成后，会调用用户设定的回调函数，在传递给回调函数的参数中给出操作结果，由于用户来更新程序中的CapInfoStruct结构，或更新界面的各项值。23、HqDLSetDoAE函数:HQDL_API HqDLSetDoAE( IN HANDLE hCamera, IN BOOL bAE, IN BYTE btTarget, IN DL_AUTOCALLBACK pfAECallback, IN LPVOID lpContext );功能:开始自动曝光操作参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 24、HqDLSetDoAF函数:HQDL_API HqDLSetDoAF( IN HANDLE hCamera, IN BOOL bAF );功能:开始自动聚焦参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 25、HqDLSetViewWin函数:HQDL_API HqDLSetViewWin(IN HANDLE hCamera, IN DLVIDEORECT *pRect);功能:设置预览窗口的位置参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: DLVIDEORECT结构定义如下：typedef struct _tagDLVIDEORECTint Left;/ 相对于父窗口的水平偏移int Top;/ 相对于父窗口的垂直偏移int Width;/ 视频窗口宽度int Height;/ 视频窗口高度DLVIDEORECT, *PDLVIDEORECT;26、HqDLGetViewWin函数:HQDL_API HqDLGetViewWin(IN HANDLE hCamera, IN DLVIDEORECT *pRect);功能:得到预览窗口的位置参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: DLVIDEORECT结构定义如下：typedef struct _tagDLVIDEORECTint Left;/ 相对于父窗口的水平偏移int Top;/ 相对于父窗口的垂直偏移int Width;/ 视频窗口宽度int Height;/ 视频窗口高度DLVIDEORECT, *PDLVIDEORECT;27、HqDLGetTotalDeviceNum函数:HQDL_API HqDLGetTotalDeviceNum(IN HANDLE hCamera, IN int *pDeviceNum );功能:得到与本机连接的摄像头数目参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 28、HqDLGetSerialsNum 函数:HQDL_API HqDLGetSerialsNum(IN HANDLE hCamera, IN char *SerialsNum );功能:得到摄像头序列号参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: 目前的序列号不是真正意义上的序列号，它是固件版本的说明。29、HqDLCalibration 函数:HQDL_API HqDLSizeCalibration(IN HANDLE hCamera, IN OUT USHORT *pOffH, IN OUT USHORT *pOffV,IN OUT USHORT *pWidth, IN OUT USHORT *pHeight, BOOL bWrite );功能:专门对于采集图像位置的校正，其参数存储在硬件之中参数: hCamera通过调用HqDLInitialize得到的设备句柄说明: GoldenHawk设备专有，其他设备不要调用此函数。30、HqDLNoiseCalibration函数: HQDL_API HqDLNoiseCalibration( IN HANDLE hCamera, const char* FileName, BOOL bPreview, BOOL bSave );功能:加载校正图像，主要用于去除噪点。参数:hCamera通过调用HqDLInitialize得到的设备句柄bPreview 指定是否在预览时加入去噪功能bSave 指定是否在保存时加入去噪功能FileName 加载校正图像的文件名,是采集原始数据得到的256色bmp灰度图,当FileName = 时,可以只设置加入去噪的时机说明: 可以在无视频流时调用注意: 加载图像的大小必须与视频采集大小相符,否则不会加载31、HqDLAutoFocus函数: H