HAL JPEG How to Use ¶

group JPEG_How_To_Use

How to use the HAL JPEG driver ¶

The HAL JPEG driver can be used as follows: ¶

• Initialize the JPEG handle by calling the HAL_JPEG_Init() API that performs these operations:

  • Associate instance to the handle

  • Enable the JPEG clock interface (When USE_HAL_JPEG_CLK_ENABLE_MODEL compilation flag is set to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM in the stm32u5xx_hal_conf.h module)

  • Initialize of the handle state to the HAL_JPEG_STATE_IDLE.

• For JPEG encoding, use the HAL_JPEG_SetConfigEncoding() function to set the encoding parameters. This step is mandatory before calling the encoding function. The application can adjust the image_quality parameter, ranging from 1 to 100, to balance visual quality against the original raw image and the resulting JPEG file size. Higher values result in better visual quality but larger file sizes, while lower values produce smaller file sizes with reduced visual quality.

• Note that for decoding operation the JPEG peripheral output data are organized in YCbCr blocks called MCU (Minimum Coded Unit) as defined in the JPEG specification ISO/IEC 10918-1 standard. It is up to the application to transform these YCbCr blocks to RGB data that can be display.

  Respectively, for Encoding operation the JPEG peripheral input must be organized in YCbCr MCU blocks. It is up to the application to perform the necessary RGB to YCbCr MCU blocks transformation before feeding the JPEG peripheral with data.

• Use the HAL_JPEG_Encode() and HAL_JPEG_Decode() functions to start respectively a JPEG encoding/decoding operation in polling method (blocking).

• Use the HAL_JPEG_Encode_IT() and HAL_JPEG_Decode_IT() functions to start respectively a JPEG encoding/decoding operation with Interrupt method (non blocking).

• Use the HAL_JPEG_Encode_DMA() and HAL_JPEG_Decode_DMA() functions to start respectively a JPEG encoding/decoding operation with DMA method (non blocking).

• Use the HAL_JPEG_GetState() function to get the HAL JPEG global_state.

• Use the HAL_JPEG_GetEncoderState() function to get the HAL JPEG encode_config_state.

• Use the HAL_JPEG_GetHeaderProcessingState() function to get the HAL JPEG header_processing_state.

Pause Resume feature usage ¶

Pause Resume InputBuffer usage ¶

• The mechanism of HAL_JPEG_PauseInputBuffer() and HAL_JPEG_ResumeInputBuffer() allows to the application to provide the input data (for encoding or decoding) in chunks. If a new input data chunk is not available (for example, because data must be read from an input file), the application can pause the JPEG input using the HAL_JPEG_PauseInputBuffer() function. Once the new input data chunk is available ( read from a file for example), the application can call the HAL_JPEG_UpdateInputBuffer() function to provide the HAL with the new chunk, and then resume the JPEG HAL input by calling the HAL_JPEG_ResumeInputBuffer() function.

• When the Input is paused, the application can call functions HAL_JPEG_UpdateInputBuffer() then HAL_JPEG_ResumeInputBuffer() any time (outside the HAL_JPEG_GetDataCallback() ) Once the new input chunk data available. However, to maintain data coherency, the HAL_JPEG_PauseInputBuffer() function must be called (if necessary) within the HAL_JPEG_GetDataCallback() callback . This ensures that the pause occurs when the HAL JPEG has finished transferring the previous chunk buffer to the JPEG peripheral.

Pause Resume OutputBuffer usage ¶

• The mechanism of HAL_JPEG_PauseOutputBuffer() and HAL_JPEG_ResumeOutputBuffer() allows the application to receive data from the JPEG peripheral in chunks. When a chunk is received, the application can pause the HAL JPEG output to process the received data (such as YCbCr to RGB conversion in the case of decoding or data storage in the case of encoding).

• When the output is paused, the application can call the HAL_JPEG_UpdateOutputBuffer() and HAL_JPEG_ResumeOutputBuffer() functions at any time (outside the HAL_JPEG_DataReadyCallback() ) once the output data buffer is free to use. However, to maintain data coherency, the HAL_JPEG_PauseOutputBuffer() function must be called (if necessary) within the HAL_JPEG_DataReadyCallback() callback. This ensures that the pause occurs when the HAL JPEG has finished transferring the previous chunk buffer from the JPEG peripheral to the application.

Header parsing and generation feature ¶

• The Header parsing and generation feature is enabled by default within the HAL JPEG driver.

• User can disable this feature by calling HAL_JPEG_DisableHeaderProcessing() .

• User can enable this feature by calling HAL_JPEG_EnableHeaderProcessing() .

• User can check whether the header processing feature is Enabled/Disabled by calling HAL_JPEG_GetHeaderProcessingState() .

• For decoding with header processing disabled the user have to provide the decoding parameter to the CODEC (as they are no longer filled by the hardware ).

• For encoding with Header generation disabled the encoder produces a raw JPEG bitstream. This bitstream does not include the standard JPEG headers that are typically found in a complete JPEG file. Instead, it contains only the compressed image data.

Custom quantization tables usage ¶

• By default the HAL JPEG driver uses the default quantization tables as provide in the JPEG specification (ISO/IEC 10918-1 standard) for encoding. User can change these default tables if necessary using the function HAL_JPEG_SetUserQuantTableX() Note that for decoding the quantization tables are automatically extracted from the JPEG header.

1. Declare a 64 value quantization table for color component x .

2. Override the default table(s) by calling HAL_JPEG_SetUserQuantTableX().

3. Call the HAL_JPEG_SetConfigEncoding() to set the encoding parameters .

4. Start encoding operation by calling one of : HAL_JPEG_Encode() / HAL_JPEG_Encode_IT() / HAL_JPEG_Encode_DMA() .

Callback definition ¶

• The HAL_JPEG_InfoReadyCallback() callback is invoked during JPEG decoding operations to provide the application with JPEG image parameters. This callback is triggered when the JPEG peripheral successfully parses the JPEG header.

• The HAL_JPEG_GetDataCallback() callback is invoked during both encoding and decoding operations. It notifies the application that the input buffer has been consumed by the peripheral and requests a new data chunk if the operation (encoding or decoding) is not yet complete.

  • This callBack must be implemented on the application side. It must call the HAL_JPEG_UpdateInputBuffer() function if new input data is available, or call HAL_JPEG_PauseInputBuffer() to inform the JPEG HAL driver to pause the ongoing operation while waiting for the application to provide a new data chunk. Once the application successfully obtains new data and if the input has been paused, the application can call the HAL_JPEG_UpdateInputBuffer() function to set the new input buffer and size, then resume the JPEG HAL input by calling the HAL_JPEG_ResumeInputBuffer() function. If the application has finished providing input data to the HAL JPEG(no more input data is available), the application must call the HAL_JPEG_UpdateInputBuffer() (within the HAL_JPEG_GetDataCallback() callback) with the in_data_length_byte parameter set to zero.

• The HAL_JPEG_DataReadyCallback() callback is invoked when the HAL JPEG driver has filled the provided output buffer with the specified size.

  • This callback must be implemented on the application side. It must call the HAL_JPEG_UpdateOutputBuffer() function to provide the HAL JPEG driver with the new output buffer location and size for storing the next data chunk. If the application is not ready to provide the output buffer location, it can call the HAL_JPEG_PauseOutputBuffer() function to inform the JPEG HAL driver to pause output data. Once the application is ready to receive the new data chunk (i.e., the output buffer location is free or available), it must call the HAL_JPEG_UpdateOutputBuffer() function to provide the HAL JPEG driver with the new output buffer location and size. Then, it must call HAL_JPEG_ResumeOutputBuffer() to inform the HAL to resume outputting data into the provided output buffer.

• The HAL_JPEG_EncodeCpltCallback() callback is invoked when the HAL JPEG driver has completed the current JPEG encoding operation and all output data has been transmitted to the application.

• The HAL_JPEG_DecodeCpltCallback() callback is invoked when the HAL JPEG driver has completed the current JPEG decoding operation and all output data has been transmitted to the application.

• The HAL_JPEG_ErrorCallback() callback is invoked when an error occurs during the current operation. The application can call the HAL_JPEG_GetLastErrorCodes() function to retrieve the error codes.

Callback registration ¶

• The compilation define USE_HAL_JPEG_REGISTER_CALLBACKS when set to 1 allows the user to configure dynamically the driver callbacks.

  • Use the HAL_JPEG_RegisterInfoReadyCallback() function to register info ready user callbacks.

  • Use the HAL_JPEG_RegisterGetDataCallback() function to register get data user callbacks.

  • Use the HAL_JPEG_RegisterDataReadyCallback() function to register data ready user callbacks.

  • Use the HAL_JPEG_RegisterEncodeCpltCallback() function to register encode complete user callbacks.

  • Use the HAL_JPEG_RegisterDecodeCpltCallback() function to register decode complete user callbacks.

  • Use the HAL_JPEG_RegisterErrorCallback() function to register error user callbacks.

By default, after the HAL_JPEG_Init() and when the global_state is HAL_JPEG_STATE_IDLE all callbacks are set to the corresponding weak functions.

Callbacks can be registered in HAL_JPEG_STATE_IDLE global_state only. When The compilation define USE_HAL_JPEG_REGISTER_CALLBACKS is set to 0 or not defined, the callback registration feature is not available and all callbacks are set to the corresponding weak functions.

Interrupt functions ¶

• Use HAL_JPEG_EnableIT() function to enable the interrupts.

• Use HAL_JPEG_DisableIT() function to disable the interrupts.

• Use HAL_JPEG_IsEnabledIT() function to get the source of interrupt.

• Use HAL_JPEG_IsActiveFlag() function to get flags.

• Use HAL_JPEG_ClearFlag() function to clear flags.