CB_Device SDK 快速开始

关于本 SDK

CB_Device 是凯视佳 lg、jr 等面阵工业相机（USB3 / GigE 接口）的 C 接口开发包，
导出函数前缀统一为 CB_，返回类型为 CB_RESULT（即 int），采用 __stdcall 调用约定。

⚠️ 返回码约定：CB_E_SUCCESS 的值为 0，其余为各类错误（见错误码章节）。
所有函数都返回 CB_RESULT，建议逐个判断是否为 CB_E_SUCCESS。

开发包组成

引入方式：

#include "CB_DeviceApi.h"   // 已内部包含 CB_Define.h / CB_Error.h 等

接口约定：所有导出函数均为 __stdcall 调用约定，返回 CB_RESULT（int）；不使用异常，
每个返回值都要判断是否为 CB_E_SUCCESS。

调用流程总览

CB_Initial                 初始化 SDK
CB_EnumerateDevices         枚举设备 → 得到设备数目
CB_GetDeviceInfo            获取设备信息（打开前即可调用）
CB_OpenDevice               打开（占用）设备
  ├─ 参数读写（CB_Get/Set*Param，整型/浮点/布尔/枚举/字符串/寄存器）
  ├─ CB_SetGrabBufferNum / CB_SetGrabTimeout
  ├─ CB_StartGrabbing        开始采集
  ├─ CB_SetGrabCallback      注册采集回调（或轮询 CB_GetGrabFrameBuffer）
  │     └─ 回调中 CB_GetGrabFrameBuffer 取帧 → 处理 → CB_FreeGrabFrameBuffer 释放
  ├─ CB_StopGrabbing         停止采集
  └─（改参数 / 反复采集）
CB_CloseDevice              关闭设备
CB_Uninitial                反初始化 SDK

参数树模型

CB_Device 采用 GenICam 风格的参数树，不提供成百上千个独立 Set/Get 函数，而是统一用
一组通用接口按参数名字符串读写：

1. CB_GetParamNum / CB_GetParamNameByIndex 列出设备支持的全部参数；
2. CB_GetParamInfoByName 取得参数类型（CB_TParamInfo：类别、数据类型、读写权限、单位、表示形式等）；
3. 根据类型调用对应的读写接口：
   • 整型：CB_GetIntParam / CB_SetIntParam（含 Min/Max/Inc 范围查询）；
   • 浮点：CB_GetFloatParam / CB_SetFloatParam；
   • 布尔：CB_GetBoolParam / CB_SetBoolParam；
   • 枚举：CB_GetEnumParam / CB_SetEnumParam，并用 CB_GetEnumParamEntry* 枚举可选条目；
   • 字符串：CB_GetStringParam / CB_SetStringParam；
   • 命令：CB_ExecuteCommandParam；寄存器：CB_Get/SetRegisterParam。

例如设置曝光时间，可先 CB_GetParamInfoByName 确认参数名与类型，再 CB_SetFloatParam(h, "ExposureTime", v)。
具体参数名请参考相机对应的 GenICam XML / 厂商文档。

回调模型

采集支持回调与主动取帧两种取数方式：

• 回调：CB_SetGrabCallback 注册 CB_GRAB_CALLBACK 类型回调，SDK 在每帧就绪时调用，回调中
  用 CB_GetGrabFrameBuffer 取得 CB_TFrameData 并处理，处理完必须 CB_FreeGrabFrameBuffer 释放；
• 也可不注册回调，在业务线程中轮询 CB_GetGrabFrameBuffer。

此外还有事件回调 CB_EVENT_CALLBACK（由 CB_SetEventCallback 注册）与参数失效回调
CB_INVALIDATE_CALLBACK（由 CB_SetInvalidateCallback 注册，设备参数被异步修改后通知应用刷新 UI）。

单位约定速查