CBXS3D SDK 快速开始

关于本 SDK

CBXS3D 是凯视佳 XS3D 系列高速高分辨率 3D 相机的 C 接口开发包（XS3D = X 系列 3D 传感器），
导出函数前缀统一为 CBXS_，采用 __stdcall 调用约定，返回 int 状态码。

⚠️ 返回码约定：CBXS_RET_SUCCESS 的值为 0，负数为错误（见错误码章节）。
所有函数都返回 int，必须逐个判断是否为 CBXS_RET_SUCCESS。

开发包组成

引入方式：

#include "CBXSApi.h"   // 已内部包含 CameraParams.h 与 ErrorDefine.h

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

调用流程总览

CBXS_SetLog              （可选）开启日志，便于定位问题
CBXS_Initial             初始化 SDK
CBXS_EnumDevices         枚举设备 → 得到 CBXS_DEVICE_INFO_LIST
CBXS_CreateDeviceHandle  按设备信息创建设备句柄
CBXS_OpenDevice          打开设备（独占）
  ├─ CBXS_SetDataFormat   设置数据格式（决定 CaptureData 的解析方式）
  ├─ 参数设置（曝光 / 增益 / 镜像 / 激光 / 触发 / ROI …）
  ├─ CBXS_StartAcquisition
  ├─ CBXS_CaptureData     主动采集一帧 → 解析 CaptureData
  ├─ CBXS_ReleaseData     释放帧内存
  ├─ CBXS_StopAcquisition
  └─（改参数 / 反复采集）
CBXS_CloseDevice         关闭设备
CBXS_DestroyDeviceHandle 销毁句柄
CBXS_UnInitial           反初始化 SDK

采集模式说明

XS3D SDK 不提供回调模式，取数统一通过 主动采集：调用 CBXS_StartAcquisition 开始采集后，
在需要数据时调用 CBXS_CaptureData 取一帧，用完必须调用 CBXS_ReleaseData 释放帧内存。

CBXS_StartAcquisition(handle, nMode) 的 nMode 当前无实际区分意义；启动采集后，部分参数
（ROI、触发模式、数据格式等）不可再改动，需先 CBXS_StopAcquisition。

数据格式与 CaptureData 的对应关系

CBXS_SetDataFormat 决定一帧 CaptureData 中哪些指针有效：

pPoint 为 unsigned short*：该值除以 16 即得该列光条点的图像坐标；值为 0 表示空点。
pImage 数组长度 = usWidth * usHeight；pPoint / pIndensity 数组长度 = usWidth。

无效帧与丢帧约定

• CBXS_DATA_PARAM::ullTimesTamp 为 0 时表示该帧为无效帧（用于通知一次 Start 结束）。
• 相邻两帧的 ullFrameID 不连续表示硬件 FrameBuffer 丢帧；ullLostFrameNum 给出连续两帧间的丢帧计数。
• 可用 CBXS_GetLostFrameStatus 拉取起始信号丢失、轮廓触发丢失、FrameBuffer 溢出三类统计。

线程注意

CBXS_CaptureData 在调用线程内同步返回，不涉及回调线程；但如果 UI 程序将取数放在工作线程，
涉及 UI 更新时必须投递回主线程（Qt 中可用 queued signal，自定义类型先 qRegisterMetaType 注册）。

单位约定速查