CB_Device SDK · 数据结构 - 凯视佳产品文档

本页汇总 CB_Define.h 中定义的结构体、回调类型与基础枚举；GenICam 风格的特征枚举（触发、传感器、增益、像素格式等）集中在 CB_Enum.h，此处仅列出分类中最常用的几个，完整集合请查阅头文件。

结构体

CB_UVersion

SDK / 驱动 / 固件版本号联合体，按字节拆分主/副/子版本。

类型	字段	说明
`uint32_t`	`iValue`	整体 32 位版本值
`struct{uint8 bmSubMinor; uint8 bmMinor; uint8 bmSubMajor; uint8 bmMajor;}`	`CB_bmValue`	按字节拆分的子副/副/子主/主版本

CB_TGigeDeviceInfo

千兆网（GigE）设备特有信息。

类型	字段	说明
`uint32_t`	`eDriverType`	驱动类型，参考 CB_EGigeDriverType
`uint8[128]`	`chAdapterFriendlyName`	网卡名称
`uint8[8]`	`iAdapterMac`	网卡 MAC 地址
`uint8[8]`	`iAdapterIp`	网卡 IP 地址
`uint8[8]`	`iAdapterSubnetMask`	网卡子网掩码
`uint8[8]`	`iAdapterDefaultGateway`	网卡默认网关
`uint32_t`	`iMtu`	网络最大传输单元 MTU
`uint8[8]`	`iDeviceMac`	设备 MAC 地址
`uint8[8]`	`iDeviceIp`	设备 IP 地址
`uint8[8]`	`iDeviceSubnetMask`	设备子网掩码
`uint8[8]`	`iDeviceDefaultGateway`	设备默认网关

CB_TUsbDeviceInfo

USB 设备特有信息。

类型	字段	说明
`uint16_t`	`iVID`	厂商 ID（Vendor ID）
`uint16_t`	`iPID`	产品 ID（Product ID）
`CB_UVersion`	`uBCD`	USB 协议版本（2.0 / 3.0）

CB_TDeviceInfo

设备信息结构体，兼容不同接口类型（GigE / USB）。

类型	字段	说明
`uint8[64]`	`chDeviceVendorName`	厂商名称
`uint8[64]`	`chDeviceModelName`	型号名称
`uint8[64]`	`chDeviceManufacturerInfo`	厂商信息
`uint8[64]`	`chDeviceVersion`	硬件版本
`uint8[64]`	`chDeviceFirmwareVersion`	固件版本号
`uint8[64]`	`chDeviceSerialNumber`	设备序列号
`uint8[64]`	`chDeviceUserDefinedName`	用户自定义名称
`uint8[64]`	`chDeviceUserId`	用户存储数据区
`uint8[128]`	`iReserved0`	保留字节
`uint32_t`	`eInterfaceType`	设备接口类型，参考 CB_EInterfaceType
`CB_UVersion`	`uDriverVersion`	驱动版本
`CB_UVersion`	`uDeviceControlVersion`	设备控制版本
`CB_UVersion`	`uDeviceConfigFileVersion`	配置文件版本
`CB_UVersion`	`uDevicecbXmlVersion`	设备描述文件版本
`union`	`SpecialInfo`	不同接口类型的特有信息（tGigeDeviceInfo / tUsbDeviceInfo / 保留 256 字节）

CB_TImageInfo

采集帧的基本图像信息。

类型	字段	说明
`uint32_t`	`ePixelFormat`	像素格式，参考 CB_Enum.h 的 PixelFormat_e
`uint32_t`	`iWidth`	图像宽度（像素）
`uint32_t`	`iHeight`	图像高度（行）
`uint32_t`	`iOffsetX`	ROI 水平偏移（像素）
`uint32_t`	`iOffsetY`	ROI 垂直偏移（行）
`uint32_t`	`iWidthBytes`	图像一行所占字节数
`uint32_t`	`iTotalBytes`	图像数据总字节数
`uint32_t[32]`	`iReserved`	保留

CB_TChunkData

随采集帧返回的水印（Chunk）信息。

类型	字段	说明
`uint64_t`	`iFrameId`	帧 Id
`uint32_t`	`iWidth`	宽度
`uint32_t`	`iHeight`	高度
`uint32_t`	`iPixelFormat`	像素格式
`uint64_t`	`iTimestampRaw`	时间戳原始值
`float`	`fExposureTime`	曝光时间
`float`	`fGain`	增益
`uint32_t`	`iLineStatusAll`	所有 IO Line 的状态
`uint32_t`	`iCounterValue`	计数器计数值
`uint32_t`	`iEncoderCounter`	编码器计数值
`uint32_t[3]`	`iBalanceRatioRaw`	白平衡系数原始值
`uint32_t[9]`	`iColorTransformationValueRaw`	色彩矩阵系数原始值
`uint32_t`	`iSourceIDValue`	图像输入源 Id
`uint32_t[32]`	`iReserved`	保留

CB_TFrameData

采集一帧的数据（图像指针 + 基本信息 + 水印信息）。

类型	字段	说明
`void*`	`pBuffer`	图像数据内存指针，由 SDK 内部分配
`CB_TImageInfo`	`tImageInfo`	图像基本信息
`CB_TChunkData`	`tChunkData`	图像水印信息

CB_TEventInfo

事件信息，由事件回调返回。

类型	字段	说明
`uint32_t`	`iEventId`	事件 Id，参考 CB_Enum.h 的 EventSelector_e
`uint64_t`	`iTimestampRaw`	时间戳原始值
`uint64_t`	`iFrameId`	帧 Id
`uint32_t`	`iData`	事件的附加信息

CB_TSaveImage

保存图像时所需信息（CB_SaveImage 入参）。

类型	字段	说明
`char*`	`pFilePathName`	图像保存路径和文件名
`void*`	`pImageBuf`	图像数据缓冲区地址
`CB_TImageInfo`	`tImageInfo`	图像缓冲区中的图像信息
`CB_EImageFileFormat`	`eImageFileFormat`	保存的图像文件格式
`uint32_t`	`iJpgQuality`	Jpg 编码质量，(50-99]

CB_TDisplayImage

显示图像时所需信息（CB_DisplayImage 入参）。

类型	字段	说明
`void*`	`pImageBuf`	图像数据缓冲区地址
`CB_TImageInfo`	`tImageInfo`	图像缓冲区中的图像信息
`HWND`	`hWnd`	显示窗口句柄（Windows）
`int32_t`	`iDestOffsetX`	显示起始 X（相对窗口左上角）
`int32_t`	`iDestOffsetY`	显示起始 Y（相对窗口左上角）
`int32_t`	`iDestWidth`	显示宽度
`int32_t`	`iDestHeight`	显示高度
`int32_t`	`iMode`	显示模式：0 正常，1 高质量耗时

CB_TParamInfo

参数信息结构体，由 CB_GetParamInfoByName 返回。

类型	字段	说明
`CB_CategoryType_e`	`eCategoryType`	参数所属类别
`CB_ParamType_e`	`eParamType`	参数数据类型
`CB_AccessMode_e`	`eAccessMode`	参数访问模式（只读/只写/读写）
`CB_IntegerType_e`	`eIntegerType`	参数类型为 Integer 时的整型类型
`CB_IncMode_e`	`eIncMode`	参数增减模式
`CB_Unit_e`	`eUnit`	参数单位
`CB_RepresentationType_e`	`eRepresentationType`	参数值的表示形式
`uint32_t`	`iByteSize`	参数字节长度（Register 类型无意义）

枚举

CB_ELogLevel

日志输出级别（CB_SetLogLevel / CB_GetLogLevel）。

常量	值	说明
`CB_LogLevel_Off`	`0`	不输出日志
`CB_LogLevel_Error`	`1`	只输出错误
`CB_LogLevel_Warning`	`2`	只输出警告和错误
`CB_LogLevel_Information`	`3`	只输出关键信息、警告及错误
`CB_LogLevel_Debug`	`4`	输出调试信息（会明显影响效率）
`CB_LogLevel_Max`	`5`	输出所有日志

CB_EInterfaceType

设备物理接口类型（CB_TDeviceInfo::eInterfaceType）。

常量	值	说明
`CB_InterfaceType_Undefined`	`0x00000000`	未定义
`CB_InterfaceType_Usb`	`0x00000001`	USB2.0 / USB3.0
`CB_InterfaceType_Gige`	`0x00000002`	千兆网 / 10GigE

CB_EGigeDriverType

GigE 设备驱动类型。

常量	值	说明
`CB_GigeDriverType_Socket`	`0`	Socket 驱动（效率低）
`CB_GigeDriverType_Filter`	`1`	Filter 驱动（效率高）

CB_EImageFileFormat

图像文件格式（CB_TSaveImage::eImageFileFormat）。

常量	值	说明
`CB_ImageFileFormat_Bmp`	`0`	BMP，无压缩
`CB_ImageFileFormat_Tiff`	`1`	TIFF，无压缩，支持 >8bit 单色
`CB_ImageFileFormat_Jpeg`	`2`	JPEG，有损压缩
`CB_ImageFileFormat_Png`	`3`	PNG，无损压缩

CB_CategoryType_e

参数所属控制类别（GenICam 风格，部分常用值）。

常量	值	说明
`CB_CategoryType_DeviceControl`	`1`	设备控制类
`CB_CategoryType_ImageFormatControl`	`2`	图像格式控制类
`CB_CategoryType_AcquisitionControl`	`3`	采集控制类
`CB_CategoryType_AnalogControl`	`4`	模拟量控制类
`CB_CategoryType_LUTControl`	`5`	查找表控制类
`CB_CategoryType_DigitalIOControl`	`7`	数字 IO 控制类
`CB_CategoryType_EncoderControl`	`9`	编码器控制类
`CB_CategoryType_EventControl`	`13`	事件控制类
`CB_CategoryType_UserSetControl`	`14`	用户配置控制类
`CB_CategoryType_ChunkDataControl`	`21`	水印控制类
`CB_CategoryType_TransportLayerControl`	`24`	传输层控制类
`CB_CategoryType_VendorControl`	`25`	厂商自定义控制类
`CB_CategoryType_Unknown`	`-1`	未定义

CB_AccessMode_e

参数读写属性（CB_TParamInfo::eAccessMode）。

常量	值	说明
`CB_AccessMode_WO`	`0`	只写
`CB_AccessMode_RO`	`1`	只读
`CB_AccessMode_RW`	`2`	可读写
`CB_AccessMode_Unknown`	`-1`	未初始化

CB_ParamType_e

参数数据类型（CB_TParamInfo::eParamType），决定用哪一组读写接口。

常量	值	说明
`CB_ParamType_Integer`	`0`	整型
`CB_ParamType_Boolean`	`1`	布尔型
`CB_ParamType_Command`	`2`	命令类型
`CB_ParamType_Float`	`3`	浮点类型
`CB_ParamType_String`	`4`	字符串类型
`CB_ParamType_Register`	`5`	寄存器类型
`CB_ParamType_Enumeration`	`6`	枚举类型
`CB_ParamType_Unknown`	`-1`	未初始化

CB_IntegerType_e

整型参数的类型（CB_TParamInfo::eIntegerType）。

常量	值	说明
`CB_IntegerType_Null`	`0`	参数不是整型
`CB_IntegerType_Signed`	`1`	有符号整型
`CB_IntegerType_Unsigned`	`2`	无符号整型
`CB_IntegerType_Union`	`3`	联合体无符号整型（等同 Unsigned）

CB_RepresentationType_e

界面数值表示形式（CB_TParamInfo::eRepresentationType）。

常量	值	说明
`CB_RepresentationType_Null`	`0`	按参数类型自行决定
`CB_RepresentationType_Linear`	`1`	线性滚动条
`CB_RepresentationType_Logarithmic`	`2`	对数滚动条
`CB_RepresentationType_Boolean`	`3`	复选框
`CB_RepresentationType_PureNumber`	`4`	十进制编辑框
`CB_RepresentationType_HexNumber`	`5`	十六进制编辑框
`CB_RepresentationType_IPV4Address`	`6`	IP 地址
`CB_RepresentationType_MACAddress`	`7`	MAC 地址

CB_Unit_e

参数单位枚举（CB_TParamInfo::eUnit）。

常量	值	说明
`CB_Unit_Null`	`0`	没有单位
`CB_Unit_ns`	`1`	纳秒
`CB_Unit_us`	`2`	微秒
`CB_Unit_ms`	`3`	毫秒
`CB_Unit_s`	`4`	秒
`CB_Unit_Hz`	`5`	赫兹
`CB_Unit_KHz`	`6`	千赫
`CB_Unit_MHz`	`7`	兆赫
`CB_Unit_nm`	`8`	纳米
`CB_Unit_um`	`9`	微米
`CB_Unit_mm`	`10`	毫米
`CB_Unit_dB`	`14`	分贝
`CB_Unit_C`	`15`	摄氏度

CB_IncMode_e

参数增减模式（CB_TParamInfo::eIncMode）。

常量	值	说明
`CB_IncMode_Null`	`0`	非整型/浮点，无增量模式
`CB_IncMode_No`	`1`	没有增量
`CB_IncMode_Fixed`	`2`	固定值增量
`CB_IncMode_List`	`3`	离散值列表

回调类型

以下三个回调类型由 CB_Define.h 定义（均为 __stdcall），通过对应的 CB_Set*Callback 注册：

类型	签名（C）	说明
`CB_GRAB_CALLBACK`	`void __stdcall(int32_t iDevIndex, CB_TFrameData* ptFrameData, void* pContext)`	采集帧就绪回调
`CB_EVENT_CALLBACK`	`void __stdcall(int32_t iDevIndex, CB_TEventInfo EventInfo, void* pContext)`	事件回调
`CB_INVALIDATE_CALLBACK`	`void __stdcall(int32_t iDevIndex, const char* szParamName, void* pContext)`	参数失效（被异步修改）回调

完整的 GenICam 特征枚举（TriggerSelector_e、TriggerMode_e、ExposureMode_e、SensorShutterMode_e、PixelFormat_e、GainSelector_e 等约 50 组）定义于 CB_Enum.h，用于相机特性控制，请结合对应机型文档使用。

结构体