JPEG DECODE SOFTWARE API

Overview

This section mainly describes the API introductions, and related data structures of the JPEG hardware decoder. The hardware decoder utilizes dedicated hardware to accelerate the JPEG image decoding process, providing higher decoding performance.

For detailed information about JPEG decoding, please refer to:
- JPEG Decoding Overview
- JPEG Software Decoding Guide
For JPEG decoding example projects, please refer to:
- JPEG Decoding Example Project

API Reference

Header File

bk_jpeg_decode/bk_jpeg_decode_sw.h

Functions

avdk_err_t bk_software_jpeg_decode_new(bk_jpeg_decode_sw_handle_t *handle, bk_jpeg_decode_sw_config_t *config)

Software JPEG Decoder API.

This file provides the external interface for the software-based JPEG decoder module. All functions in this file implement JPEG decoding using software algorithms rather than dedicated hardware.

Create a new software JPEG decoder instance

This function initializes and creates a new software-based JPEG decoder instance with the specified configuration parameters. It allocates memory for the decoder controller structure and initializes it with the provided configuration.

Parameters

handle – [out] Pointer to store the decoder handle, which will be used for subsequent operations
config – [in] Decoder configuration parameters, including callback functions, output format, etc.

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_software_jpeg_decode_on_multi_core_new(bk_jpeg_decode_sw_handle_t *handle, bk_jpeg_decode_sw_config_t *config)

Create a new software JPEG decoder instance optimized for multi-core execution.

This function creates a software JPEG decoder instance specifically optimized for execution across multiple cores, which can provide better performance by distributing the decoding workload.

Parameters

handle – [out] Pointer to store the decoder handle, which will be used for subsequent operations
config – [in] Decoder configuration parameters, including callback functions, output format, etc.

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_open(bk_jpeg_decode_sw_handle_t handle)

Open the software JPEG decoder.

This function prepares the software JPEG decoder for operation by initializing internal resources, setting up the decoding environment, and calling the underlying JPEG decoder’s initialization function. The decoder must be opened before starting any decoding operations.

Parameters

handle – [in] Software decoder handle obtained from bk_software_jpeg_decode_new or bk_software_jpeg_decode_on_multi_core_new

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_close(bk_jpeg_decode_sw_handle_t handle)

Close the software JPEG decoder.

This function closes the software JPEG decoder, releasing any resources that were allocated during the open operation and calling the underlying JPEG decoder’s deinitialization function. After closing, the decoder can be reopened or deleted.

Parameters

handle – [in] Software decoder handle

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_decode(bk_jpeg_decode_sw_handle_t handle, frame_buffer_t *frame, frame_buffer_t *out_frame)

Start JPEG decoding process.

This function initiates the decoding of a JPEG frame using the software decoder. It configures rotation, output format, and other parameters, then calls the underlying JPEG decoder’s start function to begin the decoding process. The decoder must be opened before calling this function.

Parameters

handle – [in] Software decoder handle
frame – [in] Input JPEG frame buffer containing the encoded JPEG data
out_frame – [out] Output decoded frame buffer where the decoded image will be stored

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_decode_async(bk_jpeg_decode_sw_handle_t handle, frame_buffer_t *frame)

Start JPEG decoding process asynchronously.

This function initiates the decoding of a JPEG frame using the software decoder in an asynchronous manner. It configures rotation, output format, and other parameters, then calls the underlying JPEG decoder’s start function to begin the decoding process. The decoder must be opened before calling this function.

Parameters

handle – [in] Software decoder handle
frame – [in] Input JPEG frame buffer containing the encoded JPEG data

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_delete(bk_jpeg_decode_sw_handle_t handle)

Delete the software JPEG decoder instance.

This function deletes the software JPEG decoder instance, releasing all associated resources including the decoder controller structure memory. After deletion, the handle is no longer valid for any operation.

Parameters

handle – [in] Software decoder handle to be deleted

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_set_config(bk_jpeg_decode_sw_handle_t handle, bk_jpeg_decode_sw_out_frame_info_t *config)

Set output frame configuration for software JPEG decoder.

This function allows setting output frame configuration parameters for the software JPEG decoder, specifically output format and byte order.

Parameters

handle – [in] Software decoder handle
config – [in] Output frame configuration parameters to be set

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_get_img_info(bk_jpeg_decode_sw_handle_t handle, bk_jpeg_decode_img_info_t *info)

Get image information before decoding.

This function retrieves image information from the input JPEG frame before actual decoding. It provides details such as image dimensions, color format, and other relevant parameters by calling the bk_get_jpeg_data_info function to parse the JPEG header.

Parameters

handle – [in] Software decoder handle
info – [out] Pointer to store the retrieved image information

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

avdk_err_t bk_jpeg_decode_sw_ioctl(bk_jpeg_decode_sw_handle_t handle, bk_jpeg_decode_sw_ioctl_cmd_t cmd, void *param)

Extended control interface for software JPEG decoder.

This function provides an extended interface for controlling the software JPEG decoder and accessing additional functionalities beyond basic decoding operations. Currently, this function is a placeholder that always returns success without performing any operations.

Parameters

handle – [in] Software decoder handle
cmd – [in] Command code specifying the operation to perform (defined in jpeg_decode_sw_ioctl_cmd_t)
param – [in/out] Command parameters specific to the operation being performed

Returns

BK_OK: Success
Others: Fail (error code indicates specific failure reason)

Note

Common JPEG decode function (like bk_get_jpeg_data_info) are defined in the Hardware JPEG Decoder documentation. Please refer to bk_jpegdec_hw for detailed information.

API Typedefs

Callback Function Usage Notes:

When implementing callback functions for JPEG decoding operations, please keep in mind:

Blocking operations (such as long waits, sleep, etc.) are NOT recommended in callback functions to avoid impacting decoding performance and system responsiveness.
Callback functions should only perform lightweight operations such as setting flags, sending messages/semaphores, etc. Move time-consuming operations to other tasks.

Note

Common JPEG decode types (like bk_jpeg_decode_img_info_t, bk_jpeg_decode_callback_t, jpeg_decode_status_t, jpeg_img_fmt_t) are defined in the Hardware JPEG Decoder documentation. Please refer to bk_jpegdec_hw for detailed information.

Header File

bk_jpeg_decode/bk_jpeg_decode_types_sw.h

Structures

struct bk_jpeg_decode_rotate_info

JPEG decode rotate information structure.

Note

If no rotation is needed, set rotate_angle to ROTATE_NONE and rotate_buf to NULL If rotation is needed, set rotate_angle to the desired rotation angle (ROTATE_90, ROTATE_180, ROTATE_270) If rotate_buf is NULL, internal buffer (16*16*2) will be allocated If rotate_buf is not NULL, external buffer will be used

Public Members

uint32_t rotate_angle: Rotate angle

uint8_t *rotate_buf: Rotate buffer

struct bk_jpeg_decode_out_format_info

JPEG decode output format command structure.

This structure specifies the desired output format for decoded JPEG images. It is used with the JPEG_DECODE_SW_IOCTL_CMD_SET_OUT_FORMAT command.

Public Members

bk_jpeg_decode_sw_out_format_t out_format: Output image format (RGB565, RGB888, YUYV, etc.)

struct bk_jpeg_decode_byte_order_info

JPEG decode byte order command structure.

This structure specifies the byte order for decoded JPEG image data. It is used with the JPEG_DECODE_SW_IOCTL_CMD_SET_BYTE_ORDER command.

Public Members

bk_jpeg_decode_byte_order_t byte_order: Byte order (JPEG_DECODE_LITTLE_ENDIAN or JPEG_DECODE_BIG_ENDIAN)

struct bk_jpeg_decode_sw_config

Software JPEG decoder configuration structure.

This structure contains configuration parameters for creating a software JPEG decoder instance.

Public Members

bk_jpeg_decode_callback_t decode_cbs: JPEG decode callback functions

uint32_t core_id: CPU core ID on which the decoder will run

bk_jpeg_decode_sw_out_format_t out_format: Output image format

bk_jpeg_decode_byte_order_t byte_order: Byte order for decoded data

struct bk_jpeg_decode_sw_out_frame_info

Public Members

bk_jpeg_decode_sw_out_format_t out_format: Output image format

bk_jpeg_decode_byte_order_t byte_order: Byte order for decoded data

struct bk_jpeg_decode_sw

Software JPEG decoder operations structure.

This structure defines the operations that can be performed on a software JPEG decoder instance. It implements the virtual function table pattern for the decoder interface.

Public Members

avdk_err_t (*open)(bk_jpeg_decode_sw_handle_t handle): Open the software JPEG decoder

avdk_err_t (*close)(bk_jpeg_decode_sw_handle_t handle): Close the software JPEG decoder

avdk_err_t (*decode)(bk_jpeg_decode_sw_handle_t handle, frame_buffer_t *in_frame, frame_buffer_t *out_frame): Decode JPEG frame

avdk_err_t (*decode_async)(bk_jpeg_decode_sw_handle_t handle, frame_buffer_t *in_frame): Decode JPEG frame asynchronously

avdk_err_t (*delete_sw)(bk_jpeg_decode_sw_handle_t handle): Delete the software JPEG decoder instance

avdk_err_t (*set_config)(bk_jpeg_decode_sw_handle_t handle, bk_jpeg_decode_sw_out_frame_info_t *config): Set the output format for decoded images

avdk_err_t (*get_img_info)(bk_jpeg_decode_sw_handle_t handle, bk_jpeg_decode_img_info_t *info): Get image information before decoding

avdk_err_t (*ioctl)(bk_jpeg_decode_sw_handle_t handle, bk_jpeg_decode_sw_ioctl_cmd_t cmd, void *param): Extended interface for additional functionalities

Macros

delete_sw

SW_DECODE_ROTATE_BUFFER_SIZE

Software JPEG Decoder Types.

This file defines the data types, enumerations, and structures used by the software-based JPEG decoder module. All types in this file are specific to software-based JPEG decoding implementation.

MAX_DECODE_CORE

JPEG_DECODE_CORE_ID_1

JPEG_DECODE_CORE_ID_2

Type Definitions

typedef struct bk_jpeg_decode_rotate_info bk_jpeg_decode_rotate_info_t: JPEG decode rotate information structure.

Note

If no rotation is needed, set rotate_angle to ROTATE_NONE and rotate_buf to NULL If rotation is needed, set rotate_angle to the desired rotation angle (ROTATE_90, ROTATE_180, ROTATE_270) If rotate_buf is NULL, internal buffer (16*16*2) will be allocated If rotate_buf is not NULL, external buffer will be used

typedef struct bk_jpeg_decode_out_format_info bk_jpeg_decode_out_format_info_t

JPEG decode output format command structure.

This structure specifies the desired output format for decoded JPEG images. It is used with the JPEG_DECODE_SW_IOCTL_CMD_SET_OUT_FORMAT command.

typedef struct bk_jpeg_decode_byte_order_info bk_jpeg_decode_byte_order_info_t

JPEG decode byte order command structure.

This structure specifies the byte order for decoded JPEG image data. It is used with the JPEG_DECODE_SW_IOCTL_CMD_SET_BYTE_ORDER command.

typedef struct bk_jpeg_decode_sw_config bk_jpeg_decode_sw_config_t

Software JPEG decoder configuration structure.

This structure contains configuration parameters for creating a software JPEG decoder instance.

typedef struct bk_jpeg_decode_sw_out_frame_info bk_jpeg_decode_sw_out_frame_info_t

typedef struct bk_jpeg_decode_sw *bk_jpeg_decode_sw_handle_t

Software JPEG decoder handle type.

This type defines the handle used to reference a software JPEG decoder instance.

typedef struct bk_jpeg_decode_sw bk_jpeg_decode_sw_t

Software JPEG decoder operations structure.

This structure defines the operations that can be performed on a software JPEG decoder instance. It implements the virtual function table pattern for the decoder interface.

Enumerations

enum bk_jpeg_decode_byte_order_t

JPEG decode byte order enumeration.

This enumeration defines the supported byte order configurations for decoded image data.

Values:

enumerator JPEG_DECODE_LITTLE_ENDIAN: Little-endian byte order (LSB first)

enumerator JPEG_DECODE_BIG_ENDIAN: Big-endian byte order (MSB first)

enum bk_jpeg_decode_sw_out_format_t

Software JPEG decoder output format enumeration.

This enumeration defines the supported output formats for the software JPEG decoder. These formats include various color spaces and rotation options.

Values:

enumerator JPEG_DECODE_SW_OUT_FORMAT_GRAY: Grayscale output format

enumerator JPEG_DECODE_SW_OUT_FORMAT_RGB565: RGB565 output format (16-bit per pixel)

enumerator JPEG_DECODE_SW_OUT_FORMAT_RGB888: RGB888 output format (24-bit per pixel)

enumerator JPEG_DECODE_SW_OUT_FORMAT_YUYV: YUYV interleaved format (4:2:2)

enumerator JPEG_DECODE_SW_OUT_FORMAT_YUYV_ROTATE_90: YUYV format with 90-degree clockwise rotation

enumerator JPEG_DECODE_SW_OUT_FORMAT_YUYV_ROTATE_180: YUYV format with 180-degree rotation

enumerator JPEG_DECODE_SW_OUT_FORMAT_YUYV_ROTATE_270: YUYV format with 270-degree clockwise rotation

enumerator JPEG_DECODE_SW_OUT_FORMAT_VYUY: VYUY interleaved format (alternative 4:2:2)

enumerator JPEG_DECODE_SW_OUT_FORMAT_VUYY: VUYY interleaved format (another alternative 4:2:2)

enum bk_jpeg_decode_sw_ioctl_cmd_t

Software JPEG decoder extended command enumeration.

This enumeration defines the extended control commands available for the software JPEG decoder through the ioctl interface.

Values:

enumerator JPEG_DECODE_SW_IOCTL_CMD_BASE: Base command start value for software decoder