H-SDK说明书.doc

华旗数码技术实验室有限责任公司
Digital Lab Inc

DLC
SDK 用户使用指南
V1。0

华旗数码技术实验室有限责任公司
Digital Lab Inc
二零零六年二月九日

目录
1、 版本更新说明 ————————————————————2
2、 返回值类型说明 ———————————————————6
3、 HqDLInitialize———————————————————6
4、 HqDLStartView ———————————————————8
5、 HqDLStopView ———————————————————9
6、 HqDLPauseView ———————————————————10
7、 HqDLUninitialize——————————————————11
8、 HqDLSetCapInfo ——————————————————12
9、 HqDLGetFrameRate —————————————————13
10、 HqDLGetRawFrame——————————————————14
11、 HqDLGetRgbFrame——————————————————15
12、 HqDLGetPausedFrame ————————————————16
13、 HqDLGetPausedFrameToBmp ————————————17
14、 HqDLGetRawFrameToBmp ———————————————18
15、 HqDLGetRgbFrameToBmp ———————————————19
16、 HqDLSetParam ————------———————————20
17、 HqDLSetGammaValue ————————————————21
18、 HqDLSetFrameCallback ———————————————22
19、 HqDLEnableColorOffset ——————————————23
20、 HqDLBitOperation——————————————————24
21、 HqDLRegOperation——————————————————25
22、HqDLSetDoAWB————————————————————26
23、HqDLSetDoAE—————————————————————27
24、HqDLSetDoAF——————————————————————28

25、HqDLSetViewWin————————————————————29
26、HqDLGetViewWin————————————————————30
27、HqDLGetTotalDeviceNum——————————————————31
28、HqDLGetSerialsNum ————————————————————32
29、HqDLCalibration —————————————————————33
30、HqDLNoiseCalibration——————————————————34
31、HqDLAutoFocus——————————————————————35
32、HqDLLedControl——————————————————————36
33、HqDLCaptureToAvi—————————————————————37

1、版本更新说明
² 版本： 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、返回值类型说明
ResSuccess 0x0000 // 返回成功
ResNullHandleErr 0x0001 // 无效句柄
ResNullPointerErr 0x0002 // 指针为空
ResFileOpenErr 0x0003 // 文件打开失败
ResNoDeviceErr 0x0004 // 没有设备连接
ResInvalidParameterErr 0x0005 // 无效的参数
ResOutOfMemoryErr 0x0006 // 内存溢出
ResNoPreviewRunningErr 0x0007 // 预览没有开启
ResOSVersionErr 0x0008 // 操作系统版本错误
ResUsbNotAvailableErr 0x0009 // 设备无效
ResNotSupportedErr 0x000a // 设备不支持此功能
ResNoSerialString 0x000b // 读取不到序列号
ResVerificationErr 0x000c // 效验失败
ResTimeoutErr 0x000d // 超时
ResScaleModeErr 0x000f // 缩放错误
ResUnknownErr 0x00ff // 未知错误
ResDisplayWndExist 0x0011 // 应该关闭预览窗口
ResAllocated 0x0012 // 内存已经分配
ResAllocateFail 0x0013 // 内存分配失败
ResReadError 0x0014 // USB读取失败
ResWriteError 0x0015 // USB命令发出失败
ResUsbOpen 0x0016 // USB端口已经打开
ResCreateStreamErr 0x0017 // 创建avi流失败
ResSetStreamFormatErr 0x0018 // 设置AVI流格式失败

3、HqDLInitialize
函数: HQDL_API HqDLInitialize(
IN LPCTSTR pFilterName,
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; // 用户分配，用于接收采集的原始数据8bit
ULONG Height; // 采集高度
ULONG Width; // 采集宽度
ULONG OffsetX; // 水平偏移
ULONG OffsetY; // 垂直偏移
ULONG Exposure; // 曝光值 1-500MS
UCHAR Gain[3]; // R G B 增益 1-63
UCHAR Control; // 控制位
UCHAR InternalUse; // 用户不要对此字节进行操作
UCHAR ColorOff[3]; // 用户从外面不要改变此数组的值，要调用EnableColorOffset来改变
UCHAR Reserved[4]; // 保留位
};
注3：对于3M像素的设备，Exposure的取值范围一般在300MS左右。
注4：Control一般只在GoldenHawk系列产品中使用，对于其他设备，初始化为0。

4、HqDLStartView
函数: HQDL_API HqDLStartView( IN HANDLE hCamera,
IN LPCTSTR lpszWindowName,
IN DWORD dwStyle,
IN int x,
IN int y,
IN int nWidth,
IN int nHeight,
IN HWND hwndParent,
IN HMENU nIDorHMenu
);
功能: 打开预览窗口,并启动视频流
参数: 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 HANDLE hCamera,
OUT float *pfFrameRate );
功能: 得到摄像头的当前帧率
参数: hCamera 通过调用HqDLInitialize得到的设备句柄

说明:
10、HqDLGetRawFrame

函数: HQDL_API HqDLGetRawFrame(IN HANDLE hCamera,
IN struct CapInfoStruct *pCapInfo);
功能: 采集一帧原始数据到pCapInfo->Buffer中
参数: hCamera 通过调用HqDLInitialize得到的设备句柄

说明:
11、HqDLGetRgbFrame
函数: HQDL_API
HqDLGetRgbFrame(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 – 200
bGammaOn 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 ~ 255
nGreenOffset -255 ~ 255
nBlueOffset -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; // 0xFF202020
BYTE btRed = ( BYTE )(Result); // 0x20
BYTE btGreen = ( BYTE )( Result>>8 ); // 0x20
BYTE btBlue ( BYTE )( Result>>16 ); // 0x20
ULONG Exposure = ( BYTE )( Result>>24 ) * 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 _tagDLVIDEORECT
{
int 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 _tagDLVIDEORECT
{
int 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
函数: HQDL_API HqDLAutoFocus( IN HANDLE hCamera,
USHORT Step,
BOOL bFocusNear );
功能: 进行聚焦调节
参数: hCamera 通过调用HqDLInitialize得到的设备句柄
Step 电机一次移动的步长，(1~255) 越大步进越大
bFocusNear TRUE 拉近 FALSE 拉远
说明: GoldenEagle 特有，其他设备不要调用。

GoldenEagle是我公司即将推出的一款新型专业摄像机，集成了自动聚焦，带led光源调节，可实时预览及存储。用于办公系统，pcb检测系统，具有文本识别功能及图像处理功能于一体的功能强大的摄像机。32、HqDLLedControl
函数: HQDL_API HqDLLedControl( IN HANDLE hCamera, USHORT Value );
功能: 进行光源亮度调节
参数: hCamera 通过调用HqDLInitialize得到的设备句柄
Value (0~10)
说明: GoldenEagle 特有
对于黑白摄像头，可以使用同一个开发包，但需要设置如下：

1。首先对于黑白摄像头在调用HqDLSetCapInfo函数时，所传入的CapInfoStruct结构中的Gain[0],Gain[1],Gain[2]必须具有相同的值。

2。对于黑白摄像头在调用HqDLEnableColorOffset函数时，所传入的nRedOffset, nGreenOffset, nBlueOffset必须具有相同值。

3。在调用HqDLInitialize之后，要设置为原始图像预览和采集模式，即HqDLSetParam( hCamera, RAWDATASHOW, TRUE );

4。在采集时只需调用HqDLGetRawFrameToBmp，和HqDLGetRawFrame即可。

注意黑白摄像头没有白平衡操作。
33、HqDLCaptureToAvi
函数: HQDL_API HqDLCaptureToAvi( IN HANDLE hCamera,
BOOL bStart,
LPCTSTR strFileName );
功能: 启动或停止AVI录影
参数: hCamera 通过调用HqDLInitialize得到的设备句柄
bStart = TRUE 启动录影 FALSE 停止录影
strFileName 为avi录影文件的路径及文件名。
当bStart为FALSE时，字符串可以为空。当bStart为TRUE时，字符串不可为空。
说明:
38