凯视佳产品文档 产品文档与技术支持

CB_Device SDK · 回调与帧获取

版本 1.0 · 更新于 2026-10-21 · 阅读 0

注册采集回调、获取与释放帧数据、查询帧率，以及图像保存、显示、事件与失效回调。

CB_SetGrabCallback

CB_RESULT CB_SetGrabCallback(int32_t iDevIndex, CB_GRAB_CALLBACK *pCbFunction, void* pCbContext)

注册采集回调函数。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
pCbFunction in 回调函数地址，请参考CB_GRAB_CALLBACK回调函数定义
pCbContext in 回调上下文

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • @note 这个函数需要在停止采集的状态下调用
  • 图像数据采集有两种方式，两种方式不能复用： 方式一：调用CB_SetGrabCallback设置采集回调函数，然后调用CB_StartGrabbing开始采集，SDK会内部会开启采集线程，采集的每一帧数据信息将传递给回调函数。

CB_GetGrabCallback

CB_RESULT CB_GetGrabCallback(int32_t iDevIndex, CB_GRAB_CALLBACK** ppCbFunction, void** ppCbContext)

获取注册采集回调信息。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
ppCbFunction out 指向回调函数地址的指针，请参考CB_GRAB_CALLBACK回调函数定义
ppCbContext out 指向回调上下文地址的指针

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • 这个函数可以在采集状态下判断是否处于回调采集。

CB_GetGrabFrameBuffer

CB_RESULT CB_GetGrabFrameBuffer(int32_t iDevIndex, CB_TFrameData *ptFrameData)

获取一帧图像数据。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
ptFrameData out 返回一帧数据，包括图像缓冲区指针，图像基本信息和水印信息。

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • @note 数据使用完成之后，必须调用CB_FreeGrabFrameBuffer函数释放帧缓冲，否则SDK内部采集线程会阻塞。 图像缓冲区指针指向SDK内部分配的采集Buffer，用户不需分配内存。

CB_FreeGrabFrameBuffer

CB_RESULT CB_FreeGrabFrameBuffer(int32_t iDevIndex, CB_TFrameData* ptFrameData)

释放。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
ptFrameData in 通过CB_GetGrabFrameBuffer函数获取的指针

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • @note 调用CB_GetGrabFrameBuffer后，当ptFrameData不再使用时，必须调用CB_FreeGrabFrameBuffer通知库释放缓存。

CB_GetGrabFrameRate

CB_RESULT CB_GetGrabFrameRate(int32_t iDevIndex, float* pfFrameRate)

获取当前的采集帧率。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
pfFrameRate in 获取采集帧率的指针

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

CB_SaveImage

CB_RESULT CB_SaveImage(CB_TSaveImage *ptSaveImage)

保存图像文件。

参数 方向 说明
ptSaveImage in 保存图像的相关信息，请参考CB_TSaveImage结构体定义

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

CB_DisplayImage

CB_RESULT CB_DisplayImage(CB_TDisplayImage* ptDispImage)

显示图像。

参数 方向 说明
ptDispImage in 显示图像的相关信息，请参考CB_TDisplayImage结构体定义

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

CB_SetEventCallback

CB_RESULT CB_SetEventCallback(int32_t iDevIndex, CB_EVENT_CALLBACK *pCbFunction, void *pCbContext)

注册事件回调函数。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
pCbFunction in 事件回调函数地址，请参考CB_EVENT_CALLBACK回调函数定义
pCbContext in 回调上下文

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • 当注册的回调函数不为NULL，SDK库会启动读取事件线程，当接收到有效事件后，会调用事件回调函数。

CB_GetEventCallback

CB_RESULT CB_GetEventCallback(int32_t iDevIndex, CB_EVENT_CALLBACK** ppCbFunction, void** ppCbContext)

获取注册事件回调信息。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
ppCbFunction out 指向回调函数地址的指针，请参考CB_EVENT_CALLBACK回调函数定义
ppCbContext out 指向回调上下文地址的指针

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • 这个函数可以判断是否已经开启事件通知。

CB_SetInvalidateCallback

CB_RESULT CB_SetInvalidateCallback(int32_t iDevIndex, CB_INVALIDATE_CALLBACK* pCbFunction, void* pCbContext)

注册参数更新回调函数。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
pCbFunction in 参数更新回调函数地址，请参考CB_INVALIDATE_CALLBACK回调函数定义
pCbContext in 回调上下文

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • @note 回调函数在主线程中被调用，需尽快返回，否则主线程将被阻塞。
  • 在设置某些参数时，与之关联的参数值可能会发生改变，当这些关联参数发生改变时，会调用参数更新回调函数。

CB_GetInvalidateCallback

CB_RESULT CB_GetInvalidateCallback(int32_t iDevIndex, CB_INVALIDATE_CALLBACK** ppCbFunction, void** ppCbContext)

获取注册参数更新回调信息。

参数 方向 说明
iDevIndex in 设备索引，取值范围[0,(CB_EnumerateDevices()-1)]
ppCbFunction out 指向回调函数地址的指针，请参考CB_INVALIDATE_CALLBACK回调函数定义
ppCbContext out 指向回调上下文地址的指针

返回：成功返回 CB_E_SUCCESS；失败返回错误码（见错误码章节）

说明

  • 这个函数可以判断是否已经开启参数更新。