Video Engine Module

[中文]

Module Introduction

Video Engine provides a concise video engine management interface, supporting initialization, start, stop, and resource cleanup for DVP and UVC cameras. All configurations are automatically set based on CONFIG macros, making it simple and convenient to use. This module encapsulates complex functions such as camera control, video frame queue management, and video transmission, providing a unified video processing interface for upper-layer applications.

Core Features

  • Auto Configuration: Automatically configures camera parameters based on CONFIG macros

  • One-key Initialization: video_engine_init() completes all initialization in one step

  • State Management: Complete startup state tracking

  • Complete Lifecycle Management: init/start/stop/deinit complete flow

  • State Query: video_engine_is_running() real-time state query

  • Multiple Format Support: Supports JPEG, H.264, H.265 formats

  • Frame Queue Management: Automatically manages video frame queues, supports multiple formats

Module Architecture

The Video Engine module architecture is as follows:

Application Layer (Application)
        ↓
Video Engine API (video_engine.h)
        ↓
Camera Controller (bk_camera_ctlr)
        ↓
Video Pipeline (Video Pipeline)
        ↓
Frame Queue (Frame Queue)
        ↓
Network Transfer
        ↓
Hardware Layer (DVP/UVC Camera)

Workflow

Initialization Flow

The Video Engine initialization flow is as follows:

video_engine_init()
    ↓
1. Check if Already Initialized
    - If initialized and started, return directly
    - If initialized but not started, call start
    ↓
2. Allocate Context Memory
    - Allocate video_engine_ctx_t structure
    - Initialize all fields to 0
    ↓
3. Initialize Frame Queue
    - frame_queue_init_all()
    - Initialize frame queues for all formats (MJPEG, H264, YUV)
    ↓
4. Auto Start Video Engine
    - video_engine_start()
    ↓
Initialization Complete

Start Flow

Detailed flow of video_engine_start():

1. Parameter Validation
    - Check context validity
    - Check if already started (prevent duplicate start)
    ↓
2. Build Camera Parameters
    - Read configuration from CONFIG macros
    - camera_parameters_t structure
        * id: 0 (DVP) or 1 (UVC)
        * width: CONFIG_VIDEO_ENGINE_RESOLUTION_WIDTH
        * height: CONFIG_VIDEO_ENGINE_RESOLUTION_HEIGHT
        * format: 0 (JPEG) or 1 (H.264)
    ↓
3. Open Camera
    - video_engine_camera_turn_on()
        * Configure DVP (if using DVP)
        * Create camera controller
        * Open camera device
    ↓
4. Start Video Transfer Task
    - video_engine_transfer_start()
        * Create transfer task thread
        * Set transfer_task_running = true
    ↓
5. Set Start Flag
    - is_started = true
    ↓
Start Complete

Video Data Flow

Video Capture and Transmission Flow:

Camera Capture
    ↓
Video Pipeline Processing
    ↓
Frame Callback (dvp_camera_cbs.on_frame)
    ↓
Frame Queue Enqueue (frame_queue_put_frame)
    ↓
Transfer Task (video_engine_transfer_task)
    ↓
Get Frame from Queue (frame_queue_get_frame)
    ↓
network_transfer_send_video()
    ↓
Network Send

Transfer Task Loop

video_engine_transfer_task() task loop:

while (transfer_task_running) {
    1. Get Frame from Queue
       - frame_queue_get_frame()
       - Timeout wait: BEKEN_WAIT_FOREVER
    ↓
    2. Check Frame Validity
       - If frame == NULL, continue loop
    ↓
    3. Send Video Frame
       - ntwk_trans_send_video(frame)
    ↓
    4. Release Frame Resources
       - frame_queue_free()
    ↓
    Continue loop
}

Stop Flow

Detailed flow of video_engine_stop():

1. Check if Started
    - If not started, return directly
    ↓
2. Stop Transfer Task
    - video_engine_transfer_stop()
        * Set transfer_task_running = false
        * Wait for task to exit
        * Delete task thread
    ↓
3. Close Camera
    - video_engine_camera_close()
        * bk_camera_close()
        * Release camera controller
    ↓
4. Clear Start Flag
    - is_started = false
    ↓
Stop Complete

Important Interfaces

Initialization Interface

/**
 * @brief Initialize video engine (using default configuration)
 *
 * This function initializes video engine context, frame queue, opens camera, and starts transfer task.
 * Configuration is read from CONFIG_* macros.
 *
 * @return int
 *         - AVDK_ERR_OK: Success
 *         - AVDK_ERR_NOMEM: Out of memory
 *         - Others: Error codes returned by sub-functions
 */
int video_engine_init(void);

/**
 * @brief Deinitialize video engine and release resources
 *
 * This function stops transfer task, closes camera, deinitializes frame queue, and releases all allocated memory.
 *
 * @return int
 *         - AVDK_ERR_OK: Success
 */
int video_engine_deinit(void);

Start and Stop Interface

/**
 * @brief Start video engine (using default configuration)
 *
 * This function starts video engine using configuration defined by CONFIG macros.
 * Will open camera and start transfer task.
 *
 * This function is automatically called by video_engine_init().
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_start(void);

/**
 * @brief Stop video engine and close all related resources
 *
 * This function stops video transfer task and closes camera.
 * Does not release memory or deinitialize frame queue.
 * Call video_engine_deinit() to completely clean up all resources.
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_stop(void);

Camera Control Interface

/**
 * @brief Open DVP camera
 *
 * @param config Camera configuration parameters
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_dvp_camera_open(camera_parameters_t *config);

/**
 * @brief Close camera
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_camera_close(void);

/**
 * @brief Open camera (with parameter initialization and validation)
 *
 * This function validates and initializes camera parameters with default values, then opens camera device.
 *
 * @param parameters Camera parameters (will be validated and modified)
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_camera_turn_on(camera_parameters_t *parameters);

Transfer Control Interface

/**
 * @brief Set camera transfer callback
 *
 * @param cb Transfer callback pointer (media_transfer_cb_t *)
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_set_camera_transfer_callback(void *cb);

/**
 * @brief Start video transfer task
 *
 * This function creates a task that continuously gets frames from frame queue and processes through registered transfer callback.
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_transfer_start(void);

/**
 * @brief Stop video transfer task
 *
 * @return int
 *         - BK_OK: Success
 *         - BK_FAIL: Failure
 */
int video_engine_transfer_stop(void);

State Query Interface

/**
 * @brief Check if video engine is running
 *
 * @return bool
 *         - true: Video engine is running
 *         - false: Video engine is not running
 */
bool video_engine_is_running(void);

Data Structures

camera_parameters_t: Camera parameter structure

typedef struct {
    uint16_t id;        // Camera ID: 0 = DVP, 1 = UVC
    uint16_t width;     // Image width
    uint16_t height;    // Image height
    uint16_t format;    // Format: 0 = JPEG, 1 = H.264, 2 = H.265
    uint16_t protocol; // Protocol (reserved field)
    uint16_t rotate;    // Rotation angle
} camera_parameters_t;

Main Macro Definitions

Kconfig Configuration Macros

Basic Configuration:

// Enable video engine
CONFIG_BK_VIDEO_ENGINE=y

Camera Type Selection (mutually exclusive):

// Use DVP camera
CONFIG_VIDEO_ENGINE_USE_DVP_CAMERA=y

// Or use UVC camera
// CONFIG_VIDEO_ENGINE_USE_UVC_CAMERA=y

Image Format Selection (mutually exclusive):

// Use JPEG format
CONFIG_VIDEO_ENGINE_JPEG_FORMAT=y

// Or use H.264 format
// CONFIG_VIDEO_ENGINE_H264_FORMAT=y

Resolution Configuration:

// Default width
CONFIG_VIDEO_ENGINE_RESOLUTION_WIDTH=1280  // Range: 1-2000

// Default height
CONFIG_VIDEO_ENGINE_RESOLUTION_HEIGHT=720  // Range: 1-2000

Custom Camera Parameters

#include "video_engine.h"

int custom_video_start(void)
{
    camera_parameters_t params = {
        .id = 0,              // DVP camera
        .width = 640,        // Width
        .height = 480,       // Height
        .format = 1,         // H.264 format
        .protocol = 0,       // Reserved
        .rotate = 0,         // No rotation
    };

    // Open camera
    int ret = video_engine_camera_turn_on(&params);
    if (ret != BK_OK) {
        LOGE("Camera turn on failed\n");
        return ret;
    }

    // Start transfer task
    ret = video_engine_transfer_start();
    if (ret != BK_OK) {
        LOGE("Transfer start failed\n");
        video_engine_camera_close();
        return ret;
    }

    return BK_OK;
}

Notes

  1. Initialization Order: Must call video_engine_init() first before using other interfaces

  2. Configuration Dependency: Camera parameters are read from CONFIG macros, ensure correct configuration in Kconfig

  3. Frame Queue Management: Frame queue is automatically managed by module, application layer does not need to directly operate

  4. Transfer Task: Transfer task runs in independent thread with priority 5 and stack size 4KB

  5. Resource Release: Must call video_engine_deinit() to release all resources after use

  6. Duplicate Start: If already started, calling video_engine_start() again will return success directly

  7. Format Support: - JPEG format: Suitable for low bandwidth scenarios - H.264 format: Suitable for high-quality video transmission - Format selection affects frame queue type

  8. Resolution Limitation: Resolution range 1-2000, recommend using standard resolutions (e.g., 640x480, 1280x720)

  9. Memory Management: Frame queue uses dynamic memory allocation, ensure system has sufficient memory