Camera

[English]

概述

Camera模块提供统一的摄像头控制器管理接口，支持多种摄像头设备的操作和控制。

有关CAMERA的使用详细信息，请参阅：
- DVP CAMERA使用指南
- UVC CAMERA使用指南
有关CAMERA使用的示例工程，请参阅：
- DVP CAMERA使用示例工程
- UVC CAMERA使用示例工程

主要功能特性：

设备管理: 支持摄像头控制器的打开、关闭和删除操作
流控制: 提供暂停和恢复视频流输出的功能
IO控制: 通过统一的ioctl接口支持多种控制命令
错误处理: 完善的参数校验和错误码返回机制

核心API函数：

bk_camera_uvc_ctlr_new() - 创建UVC摄像头控制器
bk_camera_dvp_ctlr_new() - 创建DVP摄像头控制器
bk_camera_open() - 打开摄像头控制器
bk_camera_close() - 关闭摄像头控制器
bk_camera_delete() - 删除摄像头控制器
bk_camera_suspend() - 暂停视频流输出
bk_camera_resume() - 恢复视频流输出
bk_camera_ioctl() - 摄像头IO控制

该模块采用统一的控制器句柄接口设计，通过函数指针调用具体的硬件驱动实现，为上层应用提供简洁一致的摄像头操作接口。所有函数均包含完善的参数校验，确保系统稳定性和安全性。

调用流程

bk_camera_dvp_ctlr_new 或 bk_camera_uvc_ctlr_new : 创建相机控制器

bk_camera_open ：打开相机

bk_camera_ioctl：通过进行特定控制（DVP特有）

bk_camera_close ：关闭相机

bk_camera_delete ：删除控制器

注意事项：

DVP和UVC控制器创建后都需要通过通用接口进行操作
DVP的IO控制命令丰富，UVC目前IO控制功能有限
UVC不包含电源控制，需要用户自己控制，具体参考用例

摄像头控制器接口

接口说明：

bk_camera_uvc_ctlr_new

/**
* @brief 创建一个新的UVC摄像头控制器
*
* 此函数用于创建并初始化一个新的UVC摄像头控制器。
*
* @param handle 用于存储创建的控制器句柄的指针
* @param config 指向UVC控制器配置的指针
* @return AVDK错误码
*/
avdk_err_t bk_camera_uvc_ctlr_new(bk_camera_ctlr_handle_t *handle, bk_uvc_ctlr_config_t *config);

bk_camera_dvp_ctlr_new

/**
* @brief 创建一个新的DVP摄像头控制器
*
* 此函数用于创建并初始化一个新的DVP摄像头控制器。
*
* @param handle 用于存储创建的控制器句柄的指针
* @param config 指向DVP控制器配置的指针
* @return AVDK错误码
*/
avdk_err_t bk_camera_dvp_ctlr_new(bk_camera_ctlr_handle_t *handle, bk_dvp_ctlr_config_t *config);

bk_camera_open

/**
* @brief 打开摄像头控制器
*
* 此函数用于打开与给定控制器句柄关联的摄像头。
*
* @param handle 摄像头控制器句柄
* @return AVDK错误码
*/
avdk_err_t bk_camera_open(bk_camera_ctlr_handle_t handle);

bk_camera_close

/**
* @brief 关闭摄像头控制器
*
* 此函数用于关闭与给定控制器句柄关联的摄像头。
*
* @param handle 摄像头控制器句柄
* @return AVDK错误码
*/
avdk_err_t bk_camera_close(bk_camera_ctlr_handle_t handle);

bk_camera_suspend

/**
* @brief 挂起摄像头控制器
*
* 此函数用于挂起与给定控制器句柄关联的摄像头。
*
* @param handle 摄像头控制器句柄
* @return AVDK错误码
*/
avdk_err_t bk_camera_suspend(bk_camera_ctlr_handle_t handle);

bk_camera_resume

/**
* @brief 恢复摄像头控制器
*
* 此函数用于恢复与给定控制器句柄关联的摄像头。
*
* @param handle 摄像头控制器句柄
* @return AVDK错误码
*/
avdk_err_t bk_camera_resume(bk_camera_ctlr_handle_t handle);

bk_camera_ioctl

/**
* @brief 在摄像头控制器上执行IOCTL操作
*
* 此函数用于在摄像头上执行设备特定的IOCTL操作。
*
* @param handle 摄像头控制器句柄
* @param cmd 要执行的命令
* @param arg 命令的参数
* @return AVDK错误码
*/
avdk_err_t bk_camera_ioctl(bk_camera_ctlr_handle_t handle, uint32_t cmd, void *arg);

/**
* @brief 删除摄像头控制器
*
* 此函数用于删除并清理给定的摄像头控制器。
*
* @param handle 摄像头控制器句柄
* @return AVDK错误码
*/
avdk_err_t bk_camera_delete(bk_camera_ctlr_handle_t handle);

摄像头控制器数据结构

下面是摄像头控制器的数据结构：

bk_dvp_ctlr_config_t

/**
* @brief DVP相机配置结构体
* @details DVP相机的完整配置参数
*/
typedef struct
{
    bk_dvp_i2c_config_t i2c_config; /**< I2C配置 */
    uint8_t reset_pin;                /**< 复位IO引脚 */
    uint8_t pwdn_pin;                 /**< 断电IO引脚 */
    bk_dvp_io_config_t io_config;   /**< IO配置 */
    mclk_freq_t clk_source;         /**< 传感器核心输入时钟 */
    uint16_t img_format;            /**< 图像格式 */
    uint16_t width;                 /**< 图像宽度 */
    uint16_t height;                /**< 图像高度 */
    uint32_t fps;                   /**< 帧率 */
    void *user_data;                /**< 用户数据指针 */
} bk_dvp_config_t;

/**
* @brief DVP相机回调函数
* @details DVP相机操作的回调函数集合
*/
typedef struct
{
    /**
    * @brief 分配帧缓冲区
    * @param format 图像格式
    * @param size 缓冲区大小
    * @return 指向已分配帧缓冲区的指针
    */
    frame_buffer_t *(*malloc)(image_format_t format, uint32_t size);

    /**
    * @brief 帧完成回调
    * @param format 图像格式
    * @param frame 指向帧缓冲区的指针
    * @param result 操作结果
    */
    void (*complete)(image_format_t format, frame_buffer_t *frame, int result);
} bk_dvp_callback_t;

/**
* @brief DVP摄像头控制器配置结构
*
* 此结构用于存储DVP（数字视频端口）摄像头控制器的配置信息。
*/
typedef struct
{
    bk_dvp_config_t config;      /**< DVP配置参数 */
    const bk_dvp_callback_t *cbs;  /**< DVP回调函数 */
} bk_dvp_ctlr_config_t;

bk_uvc_ctlr_config_t

/**
* @brief UVC相机配置结构体
*
* 包含UVC相机初始化和运行所需的所有配置参数。设置新UVC相机时使用此结构体。
*/
typedef struct
{
    uvc_stream_type_t type;    /**< 流类型（单流或双流） */
    uint8_t port;              /**< 相机端口号（从1开始索引） */
    uint8_t drop_num;          /**< UVC流启动时丢弃的帧数 */
    image_format_t img_format; /**< 图像格式（如MJPEG、YUV、H264） */
    uint16_t width;            /**< 帧宽度（像素） */
    uint16_t height;           /**< 帧高度（像素） */
    uint32_t fps;              /**< 每秒帧数（帧率） */
    void *user_data;           /**< 传递给uvc_event_callback的用户定义参数 */
} bk_cam_uvc_config_t;

/**
* @brief UVC回调函数结构体
*
* 包含各种UVC事件和操作的函数指针。
* 这些回调函数允许应用程序响应UVC事件并管理帧缓冲区的分配和处理。
*/
typedef struct
{
    /**
    * @brief 帧缓冲区分配回调
    *
    * 此函数用于分配帧缓冲区内存。
    *
    * @param format 帧的图像格式（如MJPEG、YUV）
    * @param size 要分配的内存大小（字节）
    * @return 指向分配的帧缓冲区的指针，失败则返回NULL
    */
    frame_buffer_t *(*malloc)(image_format_t format, uint32_t size);

    /**
    * @brief 帧处理完成回调
    *
    * 此函数在帧处理完成时被调用。
    *
    * @param port 相机端口号
    * @param format 处理后帧的图像格式
    * @param frame 包含处理后数据的帧缓冲区指针
    * @param result 帧处理操作的结果
    */
    void (*complete)(uint8_t port, image_format_t format, frame_buffer_t *frame, int result);

    /**
    * @brief UVC事件回调
    *
    * 此函数在UVC状态发生变化时被调用。
    *
    * @param port_info USB集线器端口信息指针
    * @param arg 传递给回调的用户定义参数
    * @param code 指示事件类型的UVC错误代码
    */
    void (*uvc_event_callback)(bk_usb_hub_port_info *port_info, void *arg, uvc_error_code_t code);
} bk_uvc_callback_t;

/**
* @brief UVC摄像头控制器配置结构
*
* 此结构用于存储UVC（USB视频类）摄像头控制器的配置信息。
*/
typedef struct
{
    bk_cam_uvc_config_t config;  /**< UVC配置参数 */
    const bk_uvc_callback_t *cbs;  /**< UVC回调函数 */
} bk_uvc_ctlr_config_t;

bk_camera_ctlr_handle_t

/**
* @brief 摄像头控制器句柄类型
*
* 这是一个指向摄像头控制器实例的不透明句柄。
*/
typedef struct bk_camera_ctlr *bk_camera_ctlr_handle_t;

/**
* @brief 摄像头控制器结构
*
* 此结构定义了摄像头控制器的接口，提供了各种摄像头操作的函数指针。
*/
typedef struct bk_camera_ctlr bk_camera_ctlr_t;

/**
* @brief 摄像头控制器接口
*
* 此结构包含定义摄像头控制器可用操作的函数指针。
*/
struct bk_camera_ctlr
{
    /**
    * @brief 打开摄像头
    * @param controller 指向摄像头控制器的指针
    * @return AVDK错误码
    */
    avdk_err_t (*open)(bk_camera_ctlr_t *controller);

    /**
    * @brief 关闭摄像头
    * @param controller 指向摄像头控制器的指针
    * @return AVDK错误码
    */
    avdk_err_t (*close)(bk_camera_ctlr_t *controller);

    /**
    * @brief 挂起摄像头
    * @param controller 指向摄像头控制器的指针
    * @return AVDK错误码
    */
    avdk_err_t (*suspend)(bk_camera_ctlr_t *controller);

    /**
    * @brief 恢复摄像头
    * @param controller 指向摄像头控制器的指针
    * @return AVDK错误码
    */
    avdk_err_t (*resume)(bk_camera_ctlr_t *controller);

    /**
    * @brief 删除摄像头控制器
    * @param controller 指向摄像头控制器的指针
    * @return AVDK错误码
    */
    avdk_err_t (*del)(bk_camera_ctlr_t *controller);

    /**
    * @brief 摄像头IOCTL操作
    * @param controller 指向摄像头控制器的指针
    * @param cmd 要执行的命令
    * @param arg 命令的参数
    * @return AVDK错误码
    */
    avdk_err_t (*ioctlr)(bk_camera_ctlr_t *controller, uint32_t cmd, void *arg);
} ;

摄像头相关的数据结构

Header File

uvc_camera_types.h

Structures

struct uvc_separate_info_t

UVC Data Separation Information Structure.

Used to track the valid data after separating H.264/JPEG from raw data stream. This structure holds information about the location and length of valid data within a UVC data packet.

Public Members

uint32_t data_len: Length of the valid data in bytes

uint8_t *data_off: Pointer to the start of valid data within the packet

struct bk_uvc_callback_t

UVC Callback Functions Structure.

Contains function pointers for various UVC events and operations. These callbacks allow the application to respond to UVC events and manage frame buffer allocation and processing.

Attention: In the callback functions, no blocking operations or long operations should be performed, otherwise the hardware interrupt will be delayed, leading to abnormal image data.

Public Members

frame_buffer_t *(*malloc)(image_format_t format, uint32_t size)

Frame buffer allocation callback.

This function is called to allocate memory for a frame buffer.

Param format: Image format of the frame (e.g., MJPEG, YUV)
Param size: Size of memory to allocate in bytes
Return: Pointer to allocated frame buffer, or NULL on failure

void (*complete)(uint8_t port, image_format_t format, frame_buffer_t *frame, int result)

Frame processing completion callback.

This function is called when frame processing is complete.

Param port: Camera port number
Param format: Image format of the processed frame
Param frame: Pointer to the frame buffer containing the processed data
Param result: Result of the frame processing operation

void (*uvc_event_callback)(bk_usb_hub_port_info *port_info, void *arg, uvc_error_code_t code)

UVC event callback.

This function is called when UVC state changes occur.

Param port_info: Pointer to USB hub port information
Param arg: User-defined argument passed to the callback
Param code: UVC error code indicating the type of event

struct bk_cam_uvc_config_t

UVC Camera Configuration Structure.

Contains all configuration parameters needed for UVC camera initialization and operation. This structure is used when setting up a new UVC camera.

Public Members

uvc_stream_type_t type: Stream type (single or double stream)

uint8_t port: Camera port number (1-based indexing)

uint8_t drop_num: Number of frames to drop when UVC stream starts

image_format_t img_format: Image format (e.g., MJPEG, YUV, H264)

uint16_t width: Frame width in pixels

uint16_t height: Frame height in pixels

uint32_t fps: Frames per second (frame rate)

void *user_data: User-defined argument to pass to uvc_event_callback

struct uvc_separate_config_t

UVC Packet Separation Configuration Structure.

Contains configuration for handling UVC packet separation and processing. This structure defines callbacks for packet processing operations.

Public Members

uint8_t id: Camera port ID

void (*uvc_separate_packet_cb)(uint8_t *data, uint32_t length, uvc_separate_info_t *sepatate_info)

UVC packet separation callback.

This function is called to separate UVC packets from the raw data stream.

Param data: Pointer to the raw data
Param length: Length of the raw data in bytes
Param sepatate_info: Pointer to structure that will receive separation results

bk_err_t (*uvc_init_packet_cb)(bk_cam_uvc_config_t *device, uint8_t init, const bk_uvc_callback_t *cb)

UVC packet initialization callback.

This function is called to initialize UVC packet processing.

Param device: Pointer to UVC camera configuration
Param init: Initialization flag (1 for init, 0 for deinit)
Param cb: Pointer to UVC callback functions
Return: BK_ERR_NONE on success, error code on failure

void (*uvc_eof_packet_cb)(bk_cam_uvc_config_t *device)

UVC end-of-frame packet callback.

This function is called when an end-of-frame packet is received.

Param device: Pointer to UVC camera configuration

Macros

UVC_PORT_MAX

Maximum number of UVC ports.

This macro defines the maximum number of UVC ports supported, based on the USB host hub maximum external ports configuration.

BK_UVC_864X480_30FPS_MJPEG_CONFIG()

Default UVC Configuration for 864x480 Resolution at 30 FPS with MJPEG Format.

Provides a standard configuration for UVC camera initialization with:

Resolution: 864x480 pixels
Frame rate: 30 FPS
Image format: MJPEG
Single stream mode
Port 1
No frame dropping
No user argument

BK_UVC_1920X1080_30FPS_H26X_CONFIG()

Enumerations

enum uvc_error_code_t

UVC Error Codes.

Defines the different types of UVC error codes that can occur during device operation.

Values:

enumerator BK_UVC_CONNECT: UVC device connected successfully

enumerator BK_UVC_CONFIG_ERROR: UVC configuration error occurred

enumerator BK_UVC_NO_MEMORY: Insufficient memory for UVC operations

enumerator BK_UVC_NO_RESOURCE: No available resources for UVC

enumerator BK_UVC_PPI_ERROR: PPI (Parallel Peripheral Interface) error

enumerator BK_UVC_DISCONNECT: UVC device disconnected

enumerator BK_UVC_NO_RESPON: UVC device not responding

enumerator BK_UVC_DMA_ERROR: DMA (Direct Memory Access) error

enumerator BK_UVC_NOT_PERMIT: Operation not permitted

enumerator BK_UVC_POWER_ERROR: Power supply error

enum uvc_stream_state_t

UVC Stream States.

Represents the different operational states of a UVC data stream.

Values:

enumerator UVC_STREAM_STATE_RUNNING: Stream is running normally

enumerator UVC_STREAM_STATE_RESUME: Stream is resumed from a suspended state

enumerator UVC_STREAM_STATE_SUSPEND: Stream is temporarily suspended

enum uvc_stream_type_t

UVC Stream Types.

Defines the streaming modes for UVC data transmission.

Values:

enumerator UVC_SINGLE_STREAM: Single stream mode - one data stream

enumerator UVC_DOUBLE_STREAM: Double stream mode - two simultaneous data streams

Header File

dvp_camera_types.h

Structures

struct bk_dvp_io_config_t

DVP IO configuration structure.

Configuration parameters for DVP interface IO pins

Public Members

sensor_bits_width_t data_width: Data bus width

uint8_t data_pin[16]: Data IO pins (up to 16 pins)

uint8_t vsync_pin: Vertical sync IO pin

uint8_t hsync_pin: Horizontal sync IO pin

uint8_t xclk_pin: Core input clock to sensor

uint8_t pclk_pin: Sensor output clock to core

struct bk_dvp_i2c_config_t

DVP I2C configuration structure.

Configuration parameters for I2C interface used by DVP sensor

Public Members

uint8_t id: I2C bus ID

uint8_t scl_pin: I2C clock line IO pin

uint8_t sda_pin: I2C data line IO pin

uint32_t baud_rate: I2C bus baud rate

uint32_t flags: I2C configuration flags

struct bk_dvp_config_t

DVP camera configuration structure.

Complete configuration parameters for DVP camera

Public Members

bk_dvp_i2c_config_t i2c_config: I2C configuration

uint8_t reset_pin: Reset IO pin

uint8_t pwdn_pin: Power down IO pin

bk_dvp_io_config_t io_config: IO configuration

mclk_freq_t clk_source: Core input clock to sensor

uint16_t img_format: Image format

uint16_t width: Image width

uint16_t height: Image height

uint32_t fps: Frames per second

void *user_data: User data pointer

struct bk_dvp_callback_t

DVP camera callback functions.

Callback functions for DVP camera operations

Attention: In the callback functions, no blocking operations or long operations should be performed, otherwise the hardware interrupt will be delayed, leading to abnormal image data.

Public Members

frame_buffer_t *(*malloc)(image_format_t format, uint32_t size)

Allocate frame buffer.

Param format: Image format
Param size: Buffer size
Return: Pointer to allocated frame buffer

void (*complete)(image_format_t format, frame_buffer_t *frame, int result)

Frame completion callback.

Param format: Image format
Param frame: Pointer to frame buffer
Param result: Operation result

struct dvp_sensor_reg_val_t

DVP sensor register value structure.

Structure to hold sensor register address and value pairs

Public Members

uint32_t reg: Register address

uint32_t val: Register value

struct dvp_sensor_config_t

DVP sensor configuration structure.

Configuration parameters and function pointers for DVP sensor

Public Members

char *name: Sensor name

media_ppi_t def_ppi: Sensor default resolution

frame_fps_t def_fps: Sensor default FPS

mclk_freq_t clk: Sensor working clock for configured FPS and PPI

pixel_format_t fmt: Sensor input data format

sync_level_t vsync: Sensor VSYNC active level

sync_level_t hsync: Sensor HSYNC active level

uint16_t id: Sensor type (sensor_id_t)

uint16_t address: Sensor write register address by I2C

uint16_t fps_cap: Sensor supported FPS

uint16_t ppi_cap: Sensor supported resolutions

bool (*detect)(void)

Auto-detect used DVP sensor.

Return: true if sensor detected, false otherwise

int (*init)(void)

Initialize DVP sensor.

Return: 0 on success, error code on failure

int (*set_ppi)(media_ppi_t ppi)

Set resolution of sensor.

Param ppi: Resolution to set
Return: 0 on success, error code on failure

int (*set_fps)(frame_fps_t fps)

Set FPS of sensor.

Param fps: FPS to set
Return: 0 on success, error code on failure

int (*power_down)(void)

Power down or reset sensor.

Return: 0 on success, error code on failure

int (*read_register)(uint32_t reg, uint32_t *val)

Read sensor register.

Param reg: Register address
Param val: Pointer to store register value
Return: 0 on success, error code on failure

int (*write_register)(uint32_t reg, uint32_t val)

Write sensor register.

Param reg: Register address
Param val: Register value to write
Return: 0 on success, error code on failure

struct dvp_sensor_detect_func_t

Camera sensor detection function structure.

Public Members

const dvp_sensor_config_t *(*detect)(void): Detection function pointer

Macros

H264_SELF_DEFINE_SEI_SIZE: Size of H.264 self-defined SEI data.

_SECTION_ATTR_IMPL(SECTION, COUNTER)

Section attribute macro implementation.

参数

SECTION – Section name
COUNTER – Counter

_CPIMTER_STRINGIFY(COUNTER)

Stringify macro.

参数

COUNTER – Counter

BK_CAMERA_SENSOR_DETECT_SECTION(f)

Camera sensor detection function section registration macro.

This macro registers a sensor detection function into a dedicated section, enabling the system to automatically discover and run detection routines.

参数

f – Detection function name

GC_QVGA_USE_SUBSAMPLE: Flag for QVGA subsample usage.

BK_DVP_864X480_30FPS_MJPEG_CONFIG()

DVP camera configuration for 864x480 resolution at 30 FPS with MJPEG format.

Predefined configuration macro for common DVP camera settings

Enumerations

enum sensor_id_t

DVP sensor ID types.

Enumeration of supported DVP sensor IDs

Values:

enumerator ID_UNKNOW: Unknown sensor ID

enumerator ID_PAS6329: PAS6329 sensor

enumerator ID_OV7670: OV7670 sensor

enumerator ID_PAS6375: PAS6375 sensor

enumerator ID_GC0328C: GC0328C sensor

enumerator ID_BF2013: BF2013 sensor

enumerator ID_GC0308C: GC0308C sensor

enumerator ID_HM1055: HM1055 sensor

enumerator ID_GC2145: GC2145 sensor

enumerator ID_OV2640: OV2640 sensor

enumerator ID_GC0308: GC0308 sensor

enumerator ID_TVP5150: TVP5150 sensor

enumerator ID_SC101: SC101 sensor

enum sensor_bits_width_t

Sensor data bit width types.

Enumeration of supported data bit widths for DVP sensors

Values:

enumerator SENSOR_BITS_WIDTH_8BIT: 8-bit data width

enumerator SENSOR_BITS_WIDTH_10BIT: 10-bit data width

enumerator SENSOR_BITS_WIDTH_12BIT: 12-bit data width

enumerator SENSOR_BITS_WIDTH_16BIT: 16-bit data width

enum dvp_ioctl_cmd_t

Values:

enumerator DVP_IOCTL_CMD_H264_IDR_RESET: Regenerate idr frame

enumerator DVP_IOCTL_CMD_SENSOR_WRITE_REGISTER

enumerator DVP_IOCTL_CMD_SENSOR_READ_REGISTER: Read sensor register