TW68XX系列SDK说明.doc

TW68XX系列SDK说明1. SDK功能概述SDK提供以下功能：(1) 获取板卡信息，包括板卡个数、位置、包含的设备个数等；(2) 获取设备信息，包括设备个数、索引、能力描述等；(3) 获取通道信息，包括通道个数、索引、能力描述等；(4) 提供设备能力设置接口，包括Input Source，采集通道数等；(5) 提供设备I2C接口，用于加密等；(6) 提供设备GPIO接口，用于IO报警等；(7) 提供视频属性设置接口，包括制式、亮度等、像素格式、图像大小等；(8) 提供视频原始数据；(9) 提供音频原始数据；2. 更新说明l 版本1.0.0.1(1) 支持TW6802、TW6802B、TW6805芯片；(2) 支持实时和非实时切换模式；(3) 仅支持YUY2（YUV 4:2:2 Packet）格式；(4) 音频仅支持8 khz，8 bit，单声道PCM格式；l 版本1.0.1.1(1) 支持TW6864芯片；(2) 暂不支持非实时切换模式；(3) 视频数据固定为YUY2（YUV 4:2:2 Packet）；(4) 音频数据固定为8 khz，8 bit，单声道PCM格式；l 版本1.0.1.4支持非实时切换模式，但TW2865上通道必须使用同样的分辨率和亮度、对比度等值。l 版本1.0.1.5支持Y41P(YUV411 packet)、RGB555、RGB565格式。l 版本1.1.0.2支持TW6868 16路卡。l 版本1.1.0.3支持TW6816/TW6815卡。l 版本1.1.0.4(1) 修正TW686x读写GPIO异常的错误。(2) 修正TW681x读写音频寄存器无效的错误。(3) 支持TW680x、TW681x的Y41P,RGB15,RGB16格式采集。l 版本1.1.0.5支持每个通道图像位置微调（图像左移或右移，调整左边或者右边垂直黑边）。l 保留3. SDK接口和功能详述3.1. 初始化和反初始化l BOOL TwInitSDK()功能：初始化SDK参数：无返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码l VOID TwUninitSDK()功能：反初始化SDK，释放设备和内存资源参数：无返回：无3.2. 板卡信息l int TwGetBoardCount()功能：获取板卡数量参数：无返回：成功返回板卡数，否则返回-1，调用TwGetLastError获取错误码l HANDLE TwGetBoardHandle(int nBoard)功能：获取板卡句柄参数：innBoard，板卡索引，从0到TwGetBoardCount()获取的板卡数减1返回：成功返回板卡句柄，否则返回NULL，调用TwGetLastError获取错误码l BOOL TwGetBoardDetail(HANDLE hBoard, TBoardDesc *pBoardDesc)功能：获取板卡信息参数：inhBoard，板卡句柄，从TwGetBoardHandle()获取 outpBoardDesc,板卡描述指针返回：成功返回TRUE，pBoardDesc中包含详细板卡信息；失败返回FALSE，调用TwGetLastError获取错误码3.3. 设备信息和能力l int TwGetDeviceCount()功能：获取设备个数参数：无返回：成功返回设备个数，否则返回-1，调用TwGetLastError获取错误码l HANDLE TwGetDeviceHandle(int nDevice)功能：获取设备句柄参数：innDevice，设备索引号，从0到TwGetDeviceCount获取的设备数减1返回：成功返回设备句柄，否则返回NULL，调用TwGetLastError获取错误码l BOOL TwGetDeviceDetail(HANDLE hDevice, TDeviceDesc *pDevDesc)功能：获取设备详细信息参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 outpDevDesc，设备描述指针返回：成功返回TRUE，pDevDesc包含设备详细描述信息；失败返回FALSE，调用TwGetLastError获取错误码l BOOL TwGetDeviceRegBYTE(HANDLE hDevice, ULONG uReg, BYTE* value)功能：读取指定设备的寄存器（字节）参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 inuReg，寄存器地址 outvalue，返回寄存器值返回：成功返回TRUE，value包含指定寄存器的值；失败返回FALSE，调用TwGetLastError 获取错误码l BOOL TwGetDeviceRegWORD(HANDLE hDevice, ULONG uReg, USHORT* value)功能：读取指定设备的寄存器（字）参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 inuReg，寄存器地址 outvalue，返回寄存器值返回：成功返回TRUE，value包含指定寄存器的值；失败返回FALSE，调用TwGetLastError 获取错误码l BOOL TwGetDeviceRegDWORD(HANDLE hDevice, ULONG uReg, DWORD* value)功能：读取指定设备的寄存器（双字）参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 inuReg，寄存器地址 outvalue，返回寄存器值返回：成功返回TRUE，value包含指定寄存器的值；失败返回FALSE，调用TwGetLastError 获取错误码l BOOL TwSetDeviceRegBYTE(HANDLE hDevice, ULONG uReg, BYTE value)功能：设置指定设备的寄存器（字节）参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 inuReg，寄存器地址 invalue，寄存器值返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码l BOOL TwSetDeviceRegWORD(HANDLE hDevice, ULONG uReg, WORD value)功能：设置指定设备的寄存器（字）参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 inuReg，寄存器地址 invalue，寄存器值返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码l BOOL TwSetDeviceRegDWORD(HANDLE hDevice, ULONG uReg, WORD value)功能：设置指定设备的寄存器（双字）参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 inuReg，寄存器地址 invalue，寄存器值返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码l BOOL TwGetDevicePciConfigSpace(HANDLE hDevice, int nOffset, int nBytes, BYTE* pData)功能：读取指定设备的PCI配置空间参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 innOffset，要读取的配置空间偏移地址 innBytes，要读取的字节数 outpData，返回值返回：成功返回TRUE，pData包含指定配置空间值；失败返回FALSE，调用TwGetLastError 获取错误码l BOOL TwSetDevicePciConfigSpace(HANDLE hDevice, int nOffset, int nBytes, BYTE* pData)功能：读取指定设备的PCI配置空间参数：inhDevice，设备句柄，从TwGetDeviceHandle获取 innOffset，要读取的配置空间偏移地址 innBytes，要读取的字节数 inpData，要写入的值返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码l int TwGetSubDeviceCount()功能：获取子设备个数参数：无返回：成功返回子设备个数，否则返回-1，调用TwGetLastError获取错误码l HANDLE TwGetSubDeviceHandle(int nSubDevice)功能：获取设备句柄参数：innSubDevice，子设备索引，从0到TwGetSubDeviceCount获取的设备数减1返回：成功返回子设备句柄，否则返回NULL，调用TwGetLastError获取错误码l BOOL TwGetSubDeviceDetail(HANDLE hSubDevice, TSubDeviceDesc *pSubDevDesc)功能：获取设备详细信息参数：inhSubDevice，子设备句柄，从TwGetSubDeviceHandle获取 outpSubDevDesc，子设备描述指针返回：成功返回TRUE，pSubDevDesc包含子设备详细描述信息；失败返回FALSE，调用 TwGetLastError获取错误码l BOOL TwEnableVideoInput(HANDLE hSubDevice, TVideoInput vInput, BOOL bEnable)功能：是否允许视频源输入（默认允许的视频源输入为mux 0）参数：inhSubDevice，子设备句柄，从TwGetSubDeviceHandle获取 invInput，视频输入源 inbEnable，TRUE为允许，否则不允许返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码l BOOL TwTwEnableVideoField2(HANDLE hSubDevice, BOOL bEnable)功能：允许奇偶场分开采集（默认值是不分开采集）参数：inhSubDevice，子设备句柄，从TwGetSubDeviceHandle获取 inbEnable，TRUE为允许，否则不允许返回：成功返回TRUE；失败返回FALSE，调用TwGetLastError获取错误码说明：奇偶场分开采集的情况下，设置的视频采集高度不能大过CIF的高度3.4. 通道信息l int TwGetChannelCount()功能：获取通道个数参数：无返回：成功返回通道个数，否则返回-1，调用TwGetLastError获取错误码l BOOL TwGetChannelDetail(HANDLE hChannel, TChannelDesc *pChannelDesc)功能：获取通道详细信息参数：inhChannel，通道句柄，从TwChannelOpen获取 outpChannelDesc，通道信息描述指针 返回：成功返回TRUE，pChannelDesc包含通道信息，否则返回FALSE，调用 TwGetLastError获取错误码3.5. I2C接口l HANDLE TwI2COpen(int nDevice)功能：打开指定设备I2C参数：innDevice，设备索引号返回：成功返回I2C设备句柄，否则返回NULL，调用TwGetLastError获取错误码l VOID TwI2CClose (HANDLE hI2C)功能：关闭指定的I2C句柄参数：inhI2C，I2C设备句柄返回：无l BOOL TwI2CWrite(HANDLE hI2C, int nBytes, BYTE* cValue)功能：写数据到指定I2C设备参数：inhI2C，I2C设备句柄innBytes，要写入的字节数incValue，要写入的数据，包含I2C设备地址，子地址等返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l TwI2CWriteNoStop(HANDLE hI2C, int nBytes, BYTE* cValue)功能：写数据到指定I2C设备，但写完后不发STOP信号参数：inhI2C，I2C设备句柄innBytes，要写入的字节数incValue，要写入的数据，包含I2C设备地址，子地址等返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwI2CRead(HANDLE hI2C, int nWriteBytes, BYTE* cValue, int nReadBytes, BYTE* pValue)功能：从指定I2C设备地址读取数据参数：inhI2C，I2C设备句柄innWriteBytes，读取之前要写入的字节数incValue，要写入的数据，包含设备地址，子地址等innReadBytes，要读取的字节数outpValue，读出的值返回：成功返回TRUE，pValue包含读取的值，否则返回FALSE，调用TwGetLastError获取错误码3.6. GPIO接口l HANDLE TwGPIOOpen(int nDevice)功能：打开指定设备的GPIO参数：innDevice，设备索引号返回：成功返回GPIO句柄，否则返回NULL，调用TwGetLastError获取错误码l VOID TwGPIOClose(HANDLE hGpio)功能：关闭指定GPIO设备参数：inhGpio，GPIO设备句柄返回：无l BOOL TwGPIOEnableOutput(HANDLE hGpio, int nGpio, int nBits, BOOL bEnable)功能：允许指定GPIO输出参数：inhGpio，GPIO设备句柄innGpio，指定要允许输出的GPIO位置innBits，指定要允许输出的GPIO数，从nGpio开始inbEnable，是否允许输出返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwGPIOSetBits(HANDLE hGpio, int nGpio, int nBits, ULONG* ulValue)功能：在指定的GPIO上输出参数：inhGpio，GPIO设备句柄 innGpio，指定要输出的GPIO位置 innBits，指定要输出的GPIO数，从nGpio开始 inulValue，要输出的值返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwGPIOGetBits(HANDLE hGpio, int nGpio, int nBits, ULONG* pValue)功能：获取指定GPIO输入值参数：inhGpio，GPIO设备句柄 innGpio，指定要读取输入的GPIO位置 innBits，指定要读取输入的GPIO数，从nGpio开始 outpValue，读取的输入值返回：成功返回TRUE，pValue包含读取的值，否则返回FALSE，调用TwGetLastError获取错误码3.7. 通道操作l HANDLE TwChannelOpen(int nChannel)功能：打开指定通道，获取通道句柄参数：innChannel，通道索引号，从0开始返回：成功返回通道句柄，否则返回NULL，调用TwGetLastError获取错误码l VOID TwChannelClose(HANDLE hChannel)功能：关闭指定通道参数：inhChannel，通道句柄返回：无l BOOL TwSetVideoStandard(HANDLE hChannel, TVideoStandard vStandard)功能：设置视频制式参数：inhChannel，通道句柄 invStandard，指定的视频制式返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwSetVideoPara(HANDLE hChannel, TVideoPara vPara, LONG lValue)功能：设置视频参数值，包括亮度、对比度、色度、饱和度、清晰度等参数：inhChannel，通道句柄invPara，指定要设置的视频参数inlValue，视频参数值返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwGetVideoPara(HANDLE hChannel, TVideoPara vPara, LONG *pValue)功能：获取指定视频参数的当前值参数：inhChannel，通道句柄invpara，指定要获取的视频参数inpValue，参数取值指针返回：成功返回TRUE，pValue包含指定视频参数的当前值，否则返回FALSE，调用 TwGetLastError获取错误码l BOOL TwStartVideoCapture(HANDLE hChannel)功能：启动指定通道视频采集参数：inhChannel，通道句柄返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwStopVideoCapture(HANDLE hChannel)功能：停止指定通道视频采集参数：inhChannel，通道句柄返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwStartAudioCapture(HANDLE hChannel)功能：启动指定通道音频采集参数：inhChannel，通道句柄返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwStopAudioCapture(HANDLE hChannel) 功能：停止指定通道音频采集参数：inhChannel，通道句柄返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwStartVideoField2(HANDLE hChannel)功能：启动指定通道偶场采集参数：inhChannel，通道句柄返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l BOOL TwStopVideoField2(HANDLE hChannel)功能：停止指定通道偶场采集参数：inhChannel，通道句柄返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码3.8. 数据流获取l BOOL TwRegisterVideoStreamCallback(TwVideoStreamCallback VideoStreamCallback, void *Context)功能：注册视频数据流回调函数参数：inVideoStreamReadCallback，指定的回调函数指针 inContext，指定的回调函数上下文指针返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l typedef int (_stdcall *TwVideoStreamCallback)(int nChannel, VOID *DataBuf, int width, int height, BOOL bField2, void *Context, _int64 pts)功能：提供视频原始数据流给用户参数：innChannel，通道索引号inDataBuf，数据缓存的指针inwidth，视频宽度inheight，视频高度inbField2，是否是偶场数据inContext，上下文指针inpts，帧时间戳返回：成功返回TRUE，否则返回FALSEl BOOL TwRegisterAudioStreamCallback(TwAudioStreamCallback AudioStreamCallback, VOID *Context)功能：注册音频数据流回调函数参数：inAudioStreamReadCallback，指定的回调函数指针 inContext，指定的回调函数上下文指针返回：成功返回TRUE，否则返回FALSE，调用TwGetLastError获取错误码l typedef int (_stdcall *TwAudioStreamCallback)(int nChannel, VOID *DataBuf, LONG Length, void *Context, _int64 pts)功能：提供音频原始数据流给用户参数：innChannel，通道索引号inDataBuf，数据缓存的指针inLength，数据帧长度inContext，上下文指针inpts，帧时间戳返回：成功返回TRUE，否则返回FALSE3.9. 保留4. 数据类型定义4.1. 板卡信息结构typedef struct intnBoardId;板卡索引号intnSlot;板卡所在的插槽号intnDeviceCount;板卡包含的设备数intnFirstDevice;板卡上的第一个设备索引号ULONGreserved1;保留ULONGreserved2;保留ULONGreserved3;保留ULONGreserved4;保留TBoardDesc;4.2. 设备信息结构typedef struct intnDeviceId;设备索引号intnBoardId;设备所在的板卡索引号intnBus;设备所在的总线号ULONGHardwareId;设备硬件IDintDeviceNumber;设备号intnSubDevice;设备包含的子设备数intnFirstSubDevice;设备包含的第一个子设备索引号ULONGreserved1;保留ULONGreserved2;保留ULONGreserved3;保留ULONGreserved4;保留TDeviceDesc;4.3. 子设备信息结构typedef struct intnDeviceId;子设备所在的设备索引号intnBoardId;子设备所在的板卡索引号intnAudio;是否包含音频，nAudio大于0表示有音频intiSwitch;子设备支持非实时切换的最大通道数intnChannels;子设备包含的通道数intnFirstChannel;子设备包含的第一个通道索引号BOOLbField2;是否奇偶场分开采集ULONGVideoInputMask;视频输入允许的掩码，bit 0对应viComposite1，依次类推ULONGreserved1;保留ULONGreserved2;保留ULONGreserved3;保留ULONGreserved4;保留TSubDeviceDesc;4.4. 通道信息结构typedef struct intnBoardId;通道所在的板卡索引号intnDeviceId;通道所在的设备索引号intnSubDeviceId;通道所在的子设备索引号intnMaxFrameRate;通道最大帧率BOOLbAudio;通道是否包含音频ULONGreserved1;保留ULONGreserved2;保留ULONGreserved3;保留ULONGreserved4;保留TChannelDesc;4.5. 视频输入结构typedef enum viCompositeVideo1,复合视频输入1viCompositeVideo2,复合视频输入2viCompositeVideo3,复合视频输入3viCompositeVideo4复合视频输入4TVideoInput;4.6. 视频制式typedef enum vsStandardNone = 0x80000000,vsStandardNTSC = 0x00000001,vsStandardPAL = 0x00000002,vsStandardSECAM = 0x00000004,TVideoStandard;4.7. 视频像素格式typedef enum vpfRGB15Alpha = 0x00000004,vpfRGB16 = 0x00000008,vpfRGB24 = 0x00000010,vpfRGB24Alpha = 0x00000020,vpfYUV420Planar = 0x00000040,vpfYUV411Planar = 0x00000100,vpfYUV422Interspersed = 0x00000400,vpfYUV411Interspersed = 0x00000800,TPixelFormat;4.8. 视频参数结构typedef enum vpBrightness,亮度vpContrast,对比度vpSaturation,饱和度vpHue,色度vpSharpnes