ieucap.h

ID/IE系列工业像机 驱动程序开发包SDK-VC库

//IEUCap.h
/*
* Copyright (c) 2006,  
* All rights reserved.
* 
* 文件名称：IEUCap.h
* 文件标识：IEUCap.h
* 摘    要：IEUCap.dll输出函数声明
*
* 开发环境：Microsoft Win32 SDK, Visual C++ 6.00
* 
* 当前版本：V2.3.4.0
* 作    者：何珊
* 完成日期：2007年7月3日
*
* 修改记录：
*			V2.2.9.0
*			1、增加了IEU_SetADCOffset和IEU_SetGain函数。何珊，2006-12-5
*			V2.3.0.0
*			2、增加了IEU_GetImageRawDataEx函数。何珊，2006-12-12
*			V2.3.1.0
*			3、删除了IEU_StopImage函数说明(无用的函数)。何珊，2006-12-19
*			V2.3.2.0
*			4、增加了IEU_SetADCControl函数。2007-1-10
*			5、增加了IEU_SetEOOffset、IEU_SetEOOffsetCtrl函数。2007-1-12
*			8、增加了IEU_SetFPNLineCtrl函数。2007-1-18
*			V2.3.3.0
*			9、增加了IEU_SetRGBOffsetCtrl、IEU_SetRGBOffset函数。2007-1-22
*			10、更新了函数说明。2007-3-16
*			V2.3.4.0
*			11、增加了IEU_SetRegister、IEU_GetRegister函数。2007-7-3
*/
//////////////////////////////////////////////////////////////////////

#ifndef _IEUCAP_H
#define _IEUCAP_H

#include "IEUDef.h"
#include "BayerDef.h"

#ifdef IEUCAP_EXPORTS
#define IEUCAP_API __declspec(dllexport)
#else
#define IEUCAP_API __declspec(dllimport)
#endif

/* By C++ language compiler */
#ifdef __cplusplus
extern "C"{
#endif


//////////////////////////////////////////////////////////////////////////////////////////////////////////
//设备操作函数

/*
*函数说明：获得连接到计算机的第一台设备的句柄，即设备编号最小的设备的句柄。
*输入参数：无
*输出参数：无。
*返 回 值：操作成功则返回有效的设备句柄，否则返为NULL。
*/
IEUCAP_API HANDLE __stdcall IEU_GetDevice();

/*
*函数说明：获得指定设备编号的设备句柄。连接到计算机的第一台设备编号为1，第二台编号为2，以此类推。
*输入参数：
*		   nDevIndex：设备编号
*输出参数：无。
*返 回 值：操作成功则返回有效的设备句柄，否则返为NULL。
*/
IEUCAP_API HANDLE __stdcall IEU_GetIndexedDevice(int nDevIndex);

/*
*函数说明：释放创建的设备，与IEU_GetDevice或IEU_GetIndexedDevice对应。获得的设备句柄使用完后必须释放。
*输入参数：
*		   hDev：设备句柄。
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误代码。
*/
IEUCAP_API HRESULT __stdcall IEU_ReleaseDevice(HANDLE hDev);

/*
*函数说明：初始化设备。
*输入参数：
*		   hDev：设备句柄
*		   nReserved：保留值，必须为1。
*		   szDataPath：初始化设备所需的初始化文件路径及文件名。若设为NULL则检测硬件是否已初始化，
*		   返回FD_SUCCESSED说明硬件已初始化，不需要初始化文件，否则必须再次调用此函数，并将szDataPath
*		   设置为有效的初始化文件文件名。
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_Initialize(HANDLE hDev, int nReserved, const char *szDataPath);

/*
* 函数介绍：检查设备接入的USB接口是否为USB2.0接口。注意：如接入接口不是USB2.0接口，相机不能正常工作。
* 输入参数：无
* 输出参数：无
* 返 回 值：返回TRUE表示计算机USB接口是2.0接口，否则不是。
*/
IEUCAP_API bool __stdcall IEU_IsUsb20(HANDLE hDev);

/*函数说明：复位设备。
*输入参数：无
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_ResetDevice(HANDLE hDev);

//////////////////////////////////////////////////////////////////////////////////////////////////////////////
//获取相机信息的函数

/*
*函数说明：获得设备的硬件信息，包括相机的类型标识、相机ID号等，参见HARDWARE结构体定义。
*输入参数：
*		   hDev：设备句柄
*输出参数：
*		   Hardware：描述硬件信息的结构体。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误代码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetHardwareInfo(HANDLE hDev, HARDWARE &Hardware);

/*
*函数说明：获得当前配置下的相机参数信息，参数如曝光时间、增益、亮度等，参数信息指参数的范围和调节精度，
*			参见PARAM_INFO定义。	
*输入参数：
*		   hDev：设备句柄
*		   CamParam：参数标识
*输出参数：
*		   Info：参数信息
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误代码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetParameterInfo(HANDLE hDev, CAM_PARAM CamParam, PARAM_INFO &Info);

/*
*函数说明：获得分辨率信息，即相机处于此种分辨率下能输出的最大的图像尺寸。
*输入参数：
*		   hDev：设备句柄
*		   Resolution：分辨率标识
*输出参数：
*		   Size：分辨率信息，为此分辨率下的最大图像尺寸（以象素为单位）
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误代码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetResolutionInfo(HANDLE hDev, FD_RESOLUTION Resolution, SIZE &Size);

/*
*函数说明：获得相机输出数据阵列的Bayer样式。参见BAYER_PATTERN定义。
*输入参数：
*		   hDev：设备句柄
*输出参数：
*		   Pattern：相机输出数据阵列的Bayer样式
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误代码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetBayerPattern(HANDLE hDev, BAYER_PATTERN &Pattern);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//图像数据获取函数：多线程方式

/*
*函数说明：设置消息处理窗口句柄，启动图像数据传输后，相机的工作状态(例如：取完一帧图像数据)
*			会以消息的方式发送到此窗口。
*输入参数：
*			hDev：设备句柄
*			hMsgHandle：消息处理窗口句柄
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*///设置消息处理窗口句柄
IEUCAP_API HRESULT __stdcall IEU_SetMsgHandle(HANDLE hDev, HWND hMsgHandle);

									
/*
*函数说明：设置回调函数，启动图像数据传输后，每取完一帧图像数据后调用回调函数，用户可
*			在函数中对图像数据做后继处理（如格式转换、显示等）。
*输入参数：
*			hDev：设备句柄
*			pfnCallback：回调函数指针
*			pTransInfo：回调函数参数指针，参见IEU_TRANS_INFO定义
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/						
IEUCAP_API HRESULT __stdcall IEU_SetCallbackFunction(HANDLE hDev, IEU_CALLBACK pfnCallback, IEU_TRANS_INFO* pTransInfo);

/*
*函数说明：创建传输线程，准备传输图像数据到主机。
*输入参数：
*			hDev：设备句柄
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_StartImageTransfer(HANDLE hDev);

/*
*函数说明：启动一次图像传输任务，必须在IEU_StartImageTransfer后调用。图像传输任务可以定量的
*			(指定传输的图像帧数)、限时的(指定传输时间)或是无限的(既不限时也不限量，直至取消或停止)。
*			此函数设置好传输任务后马上返回，传输在底层线程中进行。如果设定了回调函数，每传输完一帧图像，
*			底层线程会调用回调函数，并将当前传输的状态保存在IEU_TRANS_INFO结构体中的相应成员中，因此调
*			用者可以在回调函数中查询状态并处理数据；或设定了消息处理窗口，传输状态(例如收到一帧图像数据、
*			传输任务完成等)会以消息的方式发送到指定的窗口，调用者可以在消息处理函数中查询状态并处理数据。
*输入参数：
*			hDev：设备句柄
*			pDataBuf：数据缓冲区地址
*			dwSize：数据缓冲区大小，设相机当前图像大小为nWidth * nHeight，则dwSize必须大于或等于
*					nWidth*nHeight*dwFrames，若dwFrames为-1，dwSize必须大于或等于nWidth*nHeight
*			lFrames：传输帧数。如小于0表示没有帧数限制，缓冲区只用前nWidth*nHeight字节，新的图
*					 像数据将会覆盖前一帧图像数据。
*			lMilliseconds：传输时间，以毫秒计，超过此时间则停止传输并通知用户超时，值小于等于0时没有时间限制
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetImages(HANDLE hDev, void* pDataBuf, DWORD dwSize, 
						long lFrames, long lMilliseconds);

/*
*函数说明：取消调用IEU_GetImages函数启动的、还未完成的传输任务。
*输入参数：
*			hDev：设备句柄
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_CancelTransfer(HANDLE hDev);
						
/*
*函数说明：销毁传输线程，与IEU_StartImageTransfer对应。
*输入参数：
*			hDev：设备句柄
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返为相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_StopImageTransfer(HANDLE hDev);

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//图像数据获取函数：单线程方式
/*
*函数说明：获取一帧图像原始数据。单线程方式取数，此函数必须等于一帧图像数据完全传输到主机后才返回，
*			主机端获得一帧图像数据的时间与相机当前的曝光时间及图像的大小有关，曝光时间越长或图像尺寸
*			越大，函数耗时越多，因此可能会造成调用者线程比较长时间的阻塞。
*输入参数：
*		   hDev：设备句柄
*		   pBuf：接收数据的缓冲区地址。
*		   nSize: 缓冲区大小，必须与图像大小匹配，否则函数调用失败或者获得数据不正确。例如：若图像
*		   宽为Width，高为Height，则缓冲区大小应为Width * Height个字节。
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返回相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetImageRawData(HANDLE hDev, PVOID pBuf, UINT nSize);

/*
*函数说明：获取一帧图像原始数据。可进行超时等待设置，如硬件处于忙状态，则再次查询硬件状态，直至等到
*			硬件空闲取到数据(返回成功)或超过用户设定的等待时间(返回超时)才返回。注意：相机获取并传送
*          一帧图像到计算机的时间与图像大小、曝光时间成正比，函数接收完数据后才返回，可能会导致调用
*          线程较长时间的阻塞。
*输入参数：
*          hDev：设备句柄
*          pBuf：接收数据的缓冲区地址。
*          lSize: 缓冲区大小，必须与图像大小匹配，否则函数调用失败或者获得数据不正确。例如：若图像
*          宽为Width，高为Height，则缓冲区大小应为Width * Height个字节。
*          lMilliseconds：等待超时时间。参数为-1时，超时时间为无限长，函数只有在取到图像数据后才会返回，与IEU_GetImageRawData函数相同
*输出参数：无。
*返 回 值：操作成功则返回FD_SUCCESSED，否则返回相应的错误码。
*/
IEUCAP_API HRESULT __stdcall IEU_GetImageRawDataEx(HANDLE hDev, PVOID pBuf, UINT nSize, long lMilliseconds);

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//软件触发函数

/*
*函数说明：当前设备状态为软件触发时，给一个软件触发信号，相机接到信号后开始曝光，一帧图像曝光完毕后，
*			停止曝光，等待下一个触发信号。