JPEG DECODE HARDWARE 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:
For JPEG decoding example projects, please refer to:
API Reference
Header File
Functions
-
avdk_err_t bk_hardware_jpeg_decode_new(bk_jpeg_decode_hw_handle_t *handle, bk_jpeg_decode_hw_config_t *config)
Create a new hardware JPEG decoder instance.
This function initializes and creates a new hardware-based JPEG decoder instance that utilizes dedicated hardware for faster JPEG decoding operations. It allocates memory for the decoder controller structure and initializes it with the provided configuration and hardware-specific operation functions.
This is typically the first function called when working with the hardware JPEG decoder. The returned handle must be used for all subsequent operations on the decoder instance.
- Parameters
handle – [out] Pointer to store the hardware decoder handle, which will be used for subsequent operations
config – [in] Hardware decoder configuration parameters, specifying decoder behavior and capabilities
- Returns
BK_OK: Success, decoder instance created and handle returned
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_hardware_jpeg_decode_opt_new(bk_jpeg_decode_hw_handle_t *handle, bk_jpeg_decode_hw_opt_config_t *config)
Create a new hardware optimized JPEG decoder instance.
This function initializes and creates a new hardware-based optimized JPEG decoder instance that utilizes dedicated hardware for JPEG decoding operations. It allocates memory for the decoder controller structure and initializes it with the provided configuration and hardware-specific operation functions.
The optimized decoder allows decoding images in blocks with SRAM buffering, which reduces peak memory usage and enables efficient image display.
This is typically the first function called when working with the hardware optimized JPEG decoder. The returned handle must be used for all subsequent operations on the decoder instance.
- Parameters
handle – [out] Pointer to store the hardware optimized decoder handle, which will be used for subsequent operations
config – [in] Hardware optimized decoder configuration parameters, including lines_per_block setting
- Returns
BK_OK: Success, decoder instance created and handle returned
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_open(bk_jpeg_decode_hw_handle_t handle)
Open the hardware JPEG decoder.
This function prepares the hardware JPEG decoder for operation by initializing hardware registers, setting up the decoding environment, and calling the underlying hardware JPEG decoder’s initialization function. The decoder must be opened before starting any decoding operations.
- Parameters
handle – [in] Hardware decoder handle obtained from bk_hardware_jpeg_decode_new
- Returns
BK_OK: Success, decoder is ready for use
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_close(bk_jpeg_decode_hw_handle_t handle)
Close the hardware JPEG decoder.
This function closes the hardware JPEG decoder, releasing hardware resources that were allocated during the open operation and calling the underlying hardware JPEG decoder’s deinitialization function. After closing, the decoder can be reopened or deleted.
- Parameters
handle – [in] Hardware decoder handle
- Returns
BK_OK: Success, decoder resources released
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_decode(bk_jpeg_decode_hw_handle_t handle, frame_buffer_t *frame, frame_buffer_t *out_frame)
Perform synchronous hardware-based JPEG decoding.
This function initiates the hardware-based decoding of a JPEG frame and blocks until the decoding process is complete. It configures the hardware with the input and output buffers, then triggers the hardware to start the decoding process. The decoder must be opened before calling this function.
This is the blocking/synchronous version of the decode function, which waits for decoding to finish before returning to the caller.
- Parameters
handle – [in] Hardware 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, decoding completed
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_decode_async(bk_jpeg_decode_hw_handle_t handle, frame_buffer_t *frame)
Perform asynchronous hardware-based JPEG decoding.
This function initiates the hardware-based decoding of a JPEG frame but returns immediately without waiting for the decoding process to complete. The completion status will be signaled through a callback mechanism configured during decoder initialization.
This asynchronous version allows the application to perform other tasks while the decoding is in progress, making it suitable for time-critical applications.
- Parameters
handle – [in] Hardware decoder handle
frame – [in] Input JPEG frame buffer containing the encoded JPEG data
- Returns
BK_OK: Success, decode operation started successfully
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_delete(bk_jpeg_decode_hw_handle_t handle)
Delete the hardware JPEG decoder instance.
This function deletes the hardware JPEG decoder instance, releasing all associated hardware and software resources including the decoder controller structure memory. After deletion, the handle is no longer valid for any operation.
Typically, this is the last function called when finished working with a hardware JPEG decoder instance. The decoder should be closed before deletion.
- Parameters
handle – [in] Hardware decoder handle to be deleted
- Returns
BK_OK: Success, decoder instance deleted
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_get_img_info(bk_jpeg_decode_hw_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 analyzing the JPEG header information without performing the full decoding process.
This is useful for applications that need to determine image properties before allocating memory for the output buffer or setting up display parameters.
- Parameters
handle – [in] Hardware decoder handle
info – [out] Pointer to store the retrieved image information
- Returns
BK_OK: Success, image information retrieved
Others: Fail (error code indicates specific failure reason)
-
avdk_err_t bk_jpeg_decode_hw_ioctl(bk_jpeg_decode_hw_handle_t handle, bk_jpeg_decode_hw_ioctl_cmd_t cmd, void *param)
Extended control interface for hardware JPEG decoder.
This function provides an extended interface for controlling the hardware JPEG decoder and accessing additional functionalities beyond basic decoding operations. It allows sending specific commands to the hardware decoder for advanced configuration and control.
The supported commands are defined in the jpeg_decode_hw_ioctl_cmd_t enumeration, and each command may require specific parameters as defined in the corresponding command documentation.
- Parameters
handle – [in] Hardware decoder handle
cmd – [in] Command code specifying the operation to perform (defined in jpeg_decode_hw_ioctl_cmd_t)
param – [in/out] Command parameters specific to the operation being performed
- Returns
BK_OK: Success, command executed
Others: Fail (error code indicates specific failure reason)
Header File
Functions
-
avdk_err_t bk_get_jpeg_data_info(bk_jpeg_decode_img_info_t *img_info)
Get JPEG data information.
This function can be called independently to obtain image information
- Parameters
img_info – [in] Image information structure pointer
- Returns
AVDK_ERR_OK on success, others on failure
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.
Header File
Structures
-
struct bk_jpeg_decode_img_info
JPEG decode image info structure.
This structure is used to retrieve the information and format of a JPEG image before decoding.
Public Members
-
frame_buffer_t *frame
< [Input] Frame buffer containing the encoded JPEG data, frame->frame and frame->length must be valid
-
uint32_t width
Output: Image width in pixels
-
uint32_t height
Output: Image height in pixels
-
jpeg_img_fmt_t format
Output: Image format (YUV444, YUV422, YUV420, etc.)
-
frame_buffer_t *frame
-
struct bk_jpeg_decode_callback_t
JPEG decode callback structure.
This structure defines callback functions for JPEG decoding operations, allowing the application to be notified of significant events.
Warning
Callback Function Usage Notes:
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.
Public Members
-
frame_buffer_t *(*out_malloc)(uint32_t size)
Callback to allocate output buffer
Type Definitions
-
typedef struct bk_jpeg_decode_img_info bk_jpeg_decode_img_info_t
JPEG decode image info structure.
This structure is used to retrieve the information and format of a JPEG image before decoding.
Enumerations
-
enum jpeg_decode_status_t
Generic JPEG Decoder Types.
This file defines the common data types, enumerations, and structures used by both software and hardware JPEG decoder modules. These types are shared between different implementations of the JPEG decoder.
JPEG decoder status enumeration
This enumeration defines the operational states of the JPEG decoder.
Values:
-
enumerator JPEG_DECODE_DISABLED
Decoder is disabled and cannot perform decoding operations
-
enumerator JPEG_DECODE_ENABLED
Decoder is enabled and ready for decoding operations
-
enumerator JPEG_DECODE_DISABLED
-
enum jpeg_img_fmt_t
JPEG image format enumeration.
This enumeration defines the supported image formats for JPEG decoding. These formats specify different chroma subsampling schemes for YUV color space.
Values:
-
enumerator JPEG_FMT_ERR
Invalid or unsupported image format
-
enumerator JPEG_FMT_YUV444
YUV 4:4:4 format - full chroma resolution, no subsampling
-
enumerator JPEG_FMT_YUV422
YUV 4:2:2 format - horizontal chroma subsampling by 2:1
-
enumerator JPEG_FMT_YUV420
YUV 4:2:0 format - horizontal and vertical chroma subsampling by 2:1
-
enumerator JPEG_FMT_YUV400
YUV 4:0:0 format - grayscale image with only luma component
-
enumerator JPEG_FMT_ERR
Header File
Structures
-
struct bk_jpeg_decode_hw_config
Hardware JPEG decoder configuration structure.
This structure contains configuration parameters for creating a hardware JPEG decoder instance.
Public Members
-
bk_jpeg_decode_callback_t decode_cbs
JPEG decode callback functions
-
bk_jpeg_decode_callback_t decode_cbs
-
struct bk_jpeg_decode_hw_opt_config
Hardware optimized JPEG decoder configuration structure.
This structure contains configuration parameters for creating a hardware optimized JPEG decoder instance.
Public Members
-
bk_jpeg_decode_callback_t decode_cbs
JPEG decode callback functions
-
uint8_t *sram_buffer
SRAM buffer for optimized decode (NULL to auto-allocate) Buffer size should be: image_max_width * lines_per_block * 2 (bytes per pixel YUYV) If pingpong mode: image_max_width * lines_per_block * 2 * 2
-
uint32_t image_max_width
Maximum width of the image
-
uint8_t is_pingpong
Whether to use pingpong mode
-
bk_jpeg_decode_opt_lines_per_block_t lines_per_block
Number of lines to decode per block
-
bk_jpeg_decode_opt_copy_method_t copy_method
Copy method for data transfer
-
bk_jpeg_decode_callback_t decode_cbs
-
struct bk_jpeg_decode_hw
Hardware JPEG decoder operations structure.
This structure defines the operations that can be performed on a hardware JPEG decoder instance. It implements the virtual function table pattern for the decoder interface.
Public Members
-
avdk_err_t (*open)(bk_jpeg_decode_hw_handle_t handle)
Open the hardware JPEG decoder
-
avdk_err_t (*close)(bk_jpeg_decode_hw_handle_t handle)
Close the hardware JPEG decoder
-
avdk_err_t (*decode)(bk_jpeg_decode_hw_handle_t handle, frame_buffer_t *in_frame, frame_buffer_t *out_frame)
Decode JPEG frame
-
avdk_err_t (*decode_async)(bk_jpeg_decode_hw_handle_t handle, frame_buffer_t *in_frame)
Decode JPEG frame async
-
avdk_err_t (*delete_hw)(bk_jpeg_decode_hw_handle_t handle)
Delete the hardware JPEG decoder instance
-
avdk_err_t (*get_img_info)(bk_jpeg_decode_hw_handle_t handle, bk_jpeg_decode_img_info_t *info)
Get image information before decoding
-
avdk_err_t (*ioctl)(bk_jpeg_decode_hw_handle_t handle, bk_jpeg_decode_hw_ioctl_cmd_t cmd, void *param)
Extended interface for additional functionalities
-
avdk_err_t (*open)(bk_jpeg_decode_hw_handle_t handle)
Macros
-
delete_hw
Type Definitions
-
typedef struct bk_jpeg_decode_hw_config bk_jpeg_decode_hw_config_t
Hardware JPEG decoder configuration structure.
This structure contains configuration parameters for creating a hardware JPEG decoder instance.
-
typedef struct bk_jpeg_decode_hw *bk_jpeg_decode_hw_handle_t
Hardware JPEG decoder handle type.
This type defines the handle used to reference a hardware JPEG decoder instance.
-
typedef struct bk_jpeg_decode_hw_opt_config bk_jpeg_decode_hw_opt_config_t
Hardware optimized JPEG decoder configuration structure.
This structure contains configuration parameters for creating a hardware optimized JPEG decoder instance.
-
typedef struct bk_jpeg_decode_hw bk_jpeg_decode_hw_t
Hardware JPEG decoder operations structure.
This structure defines the operations that can be performed on a hardware JPEG decoder instance. It implements the virtual function table pattern for the decoder interface.
Enumerations
-
enum bk_jpeg_decode_hw_ioctl_cmd_t
Hardware JPEG Decoder Types.
This file defines the data types, enumerations, and structures used by the hardware-based JPEG decoder module. All types in this file are specific to hardware-based JPEG decoding implementation.
Hardware JPEG decoder extended command enumeration
This enumeration defines the extended control commands available for the hardware JPEG decoder through the ioctl interface.
Values:
-
enumerator JPEG_DECODE_HW_IOCTL_CMD_BASE
Base command start value for hardware decoder
-
enumerator JPEG_DECODE_HW_IOCTL_CMD_BASE