JPEG Decode Driver

Table of Contents

• JPEG Decode HAL Module Introduction
  • JPEG Decode HAL Module Features
  • JPEG Decode Hardware support details
• JPEG Decode HAL Module APIs Overview
• JPEG Decode HAL Module Operational Overview
  • JPEG Decode HAL Module Important Operational Notes and Limitations
    • JPEG Decode HAL Module Operational Notes
    • JPEG Decode HAL Module Limitations
• Including the JPEG Decode HAL Module in an Application
• Configuring the JPEG Decode HAL Module
  • JPEG Decode HAL Module Clock Configuration
  • JPEG Decode HAL Module Pin Configuration
• Using the JPEG Decode HAL Module in an Application

JPEG Decode HAL Module Introduction

The JPEG Decode HAL module provides high-level APIs for JPEG Decode image processing. The JPEG Decode HAL module uses the Synergy MCU JPEG Codec peripheral. A user callback function is available to inform the application program of key processing events.

JPEG Decode HAL Module Features

• Supports JPEG decompression.
• Supports polling mode that allows an application to wait for JPEG Decoder to complete.
• Supports interrupt mode with user-supplied callback functions.
• Configures parameters such as horizontal and vertical subsample values, horizontal stride, decoded pixel format, input and output data format, and color space.
• Obtains the size of the image prior to decoding it.
• Supports putting coded data in an input buffer and an output buffer to store the decoded image frame.
• Supports streaming coded data into JPEG Decoder module. This feature allows an application to read coded JPEG image from a file or from network without buffering the entire image.
• Configures the number of image lines to decode. This feature enables the application to process the decoded image on the fly without buffering the entire frame.
• Supports the input decoded format YCbCr444, YCbCr422, YCbCr420, YCbCr411.
• Supports the output format ARGB8888, RGB565.
• Returns error when the JPEG image's size, height and width do not meet the requirements.

JPEG Decode HAL Module Block Diagram

JPEG Decode Hardware support details

The following hardware features are, or are not, supported by SSP for JPEG.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

 

MCU Group	8 lines by 8 pixels in YCbCr444	8 lines by 16 pixels in YCbCr422	8 lines by 32 pixels in YCbCr411	16 lines by 16 pixels in YCbCr420	Output decoded format ARGB8888	Output decoded format RGB565
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	N/A	N/A	N/A	N/A	N/A	N/A
S3A3	N/A	N/A	N/A	N/A	N/A	N/A
S3A6	N/A	N/A	N/A	N/A	N/A	N/A
S3A7	N/A	N/A	N/A	N/A	N/A	N/A
S5D3	N/A	N/A	N/A	N/A	N/A	N/A
S5D5	N/A	N/A	N/A	N/A	N/A	N/A
S5D9	✓	✓	✓	✓	✓	✓
S7G2	✓	✓	✓	✓	✓	✓

JPEG Decode HAL Module APIs Overview

The JPEG Decode HAL Module implements APIs to open, set processing parameters, start processing, get processing status and close the module. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

JPEG Decode HAL Module API Summary

Function Name	Example API Call and Description
open	g_jpeg_decode0.p_api->open(g_jpeg_decode0.p_ctrl, g_jpeg_decode0.p_cfg); Initial configuration.
outputBufferSet	g_jpeg_decode0.p_api->outputBufferSet(g_jpeg_decode0.p_ctrl, p_buffer, buffer_size); Assign output buffer to JPEG codec for storing output data.
horizontalStrideSet	g_jpeg_decode0.p_api->horizontalStrideSet(g_jpeg_decode0.p_ctrl, stride); Configure the horizontal stride value.
imageSubsampleSet	g_jpeg_decode0.p_api->imageSubsampleSet(g_jpeg_decode0.p_ctrl, horizontal, vertical); Configure the horizontal and vertical subsample settings.
inputBufferSet	g_jpeg_decode0.p_api->inputBufferSet(g_jpeg_decode0.p_ctrl, p_buffer, size); Assign input data buffer to JPEG codec.
linesDecodedGet	g_jpeg_decode0.p_api->linesDecodedGet g_jpeg_decode0.p_ctrl, p_lines); Return the number of lines decoded into the output buffer.
imageSizeGet	g_jpeg_decode0.p_api->imageSizeGet(g_jpeg_decode0.p_ctrl, p_horizontal, p_vertical); Retrieve image size during decoding operation.
statusGet	g_jpeg_decode0.p_api->statusGet(g_jpeg_decode0.p_ctrl, p_status); Retrieve current status of the JPEG codec module.
close	g_jpeg_decode0.p_api->close(g_jpeg_decode0.p_ctrl); Cancel an outstanding operation.
versionGet	g_jpeg_decode0.p_api->versionGet(&version); Get version and store it in provided pointer p_version.
pixelFormatGet	g_jpeg_decode0.p_api->pixelFormatGet(g_jpeg_decode0.p_ctrl, p_color_space); Get the input pixel format.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_INVALID_ARGUMENT	Parameter has invalid value.
SSP_ERR_INVALID_ALIGNMENT	Horizantal stride is not 8-byte aligned.
SSP_ERR_NOT_OPEN	Unit is not open.
SSP_ERR_ASSERTION	An input pointer is NULL.
SSP_ERR_IN_USE	Peripheral is in use or hardware lock is taken.
SSP_ERR_HW_LOCKED	JPEG Codec resource is locked.
SSP_ERR_INVALID_CALL	An invalid call has been made, Codec output buffer address is attempted to change during codec operation. Or set output buffer first.
SSP_ERR_JPEG_IMAGE_SIZE_ERROR	Image size is not supported by JPEG codec.
SSP_ERR_JPEG_BUFFERSIZE_NOT_ENOUGH	Invalid buffer size.
SSP_ERR_INVALID_MODE	JPEG Codec module is not decoding.
SSP_ERR_IMAGE_SIZE_UNKNOWN	The image size is unknown. More input data may be needed.

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

JPEG Decode HAL Module Operational Overview

The JPEG Decoder HAL module can be used in the Input Buffer Streaming mode or JPEG Output Buffer Streaming mode.

Input Buffer Streaming Mode Operational Description

In this scenario the JPEG image data resides on a file, or is received from network. The HAL-layer driver is able to handle this scenario without requiring the input data to be stored in memory first.

Output Buffer Streaming Mode Operational Description

In this scenario the application needs to write the decoded image data to a file or to a network. The HAL-layer driver does not require the application to allocate memory for the entire frame. Instead the application may choose to decode one or more lines at a time. With this feature the amount of memory needed for the output data is greatly reduced.

MJPEG Decode Operational Description

In this scenario the application needs to display a continuous stream of JPEG images on the native display. The JPEG images can reside on a file or can be received from the network. The HAL driver handles this scenario by using the Input Buffer Streaming Mode feature of the JPEG Decode module.

The basic flow to achieve this would be:

1. Open the JPEG Decode driver.
2. Set the image parameters: horizontal stride, image sub-samples.
3. Set the input buffer which holds the jpeg image frame.
4. Set the output buffer to hold the raw image.
5. Display the decoded image.
6. Close the jpeg driver.
7. Repeat the process from step 1 as needed.

JPEG Decode HAL Module Important Operational Notes and Limitations

JPEG Decode HAL Module Operational Notes

JPEG Decode Callbacks A user callback function can be registered in the open API. If a user callback function is provided, the callback function will be called from the interrupt service routine (ISR) each time an interrupt happens. The argument of the callback function status can take the enumerated values listed below so that user can identify which event occurred in the decoding procedure.

Event Name	Event Condition
JPEG_DECODE_STATUS_ERROR	JPEG Decode module encountered an error.
JPEG_DECODE_STATUS_IMAGE_SIZE_READY	JPEG Decode obtained the image size of data to be decoded, and paused.
JPEG_DECODE_STATUS_INPUT_PAUSE	JPEG Decode paused waiting for more input data.
JPEG_DECODE_STATUS_OUTPUT_PAUSE	JPEG Decode paused after decoded the number of lines specified by user.
JPEG_DECODE_STATUS_DONE	JPEG Decode operation has successfully completed.

Note

Since a user callback function is called from an ISR, be careful not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.

JPEG Decode HAL Module Limitations

• The JPEG Decode HAL module only support JPEG decoding processing. For encoding, use the JPEG Encode Driver.
• If both drivers are in use, the JPEG Encode driver needs to be closed in order to use the JPEG Decode Driver (or vice versa, as both drivers share the same IP).
• Ensure timeout detection logic is implemented (as in sf_jpeg_decode_api_t::wait API of SF_JPEG_DECODE). If timeout error occurs while decoding the image, close the driver, re-open it and then perform the decoding operation.
• Refer to the most recent SSP Release notes for the most up to date limitations for this module.

Including the JPEG Decode HAL Module in an Application

This section describes how to include the JPEG Decode HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the JPEG Decode Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the JPEG Decode Driver is g_jpeg_decode0. This name can be changed in the associated Properties window.)

JPEG Decode HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_jpeg_decode0 JPEG Decode Driver on r_jpeg_decode	Threads	New Stack> Driver> Graphics> JPEG Decode Driver

When the JPEG Decode Driver on r_jpeg_decode is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

JPEG Decode HAL Module Stack

Configuring the JPEG Decode HAL Module

The JPEG Decode HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the JPEG Decode HAL Module on r_jpeg_decode

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_jpeg_decode0	The name to be used for a JPEG Decode module instance.
Byte Order for Input Data Format	Normal byte order (1)(2)(3)(4)(5)(6)(7)(8), Byte Swap (2)(1)(4)(3)(6)(5)(8)(7), Word Swap (3)(4)(1)(2)(7)(8)(5)(6), Word-Byte Swap (4)(3)(2)(1)(8)(7)(6)(5),  Longword Swap (5)(6)(7)(8)(1)(2)(3)(4), Longword-Byte Swap (6)(5)(8)(7)(2)(1)(4)(3), Longword-Word Swap (7)(8)(5)(6)(3)(4)(1)(2), Longword-Word-Byte Swap (8)(7)(6)(5)(4)(3)(2)(1) Default: Normal Byte order	Specify the byte order for input data. The order is swapped as specified in every 8-byte.
Byte Order for Output Data Format	Normal byte order (1)(2)(3)(4)(5)(6)(7)(8), Byte Swap (2)(1)(4)(3)(6)(5)(8)(7), Word Swap (3)(4)(1)(2)(7)(8)(5)(6), Word-Byte Swap (4)(3)(2)(1)(8)(7)(6)(5),  Longword Swap (5)(6)(7)(8)(1)(2)(3)(4), Longword-Byte Swap (6)(5)(8)(7)(2)(1)(4)(3), Longword-Word Swap (7)(8)(5)(6)(3)(4)(1)(2), Longword-Word-Byte Swap (8)(7)(6)(5)(4)(3)(2)(1) Default: Normal Byte order	Specify the byte order for output data. The order is swapped as specified in every 8-byte.
Output Data Color Format	Pixel Data RGB565 format, Pixel Data ARGBB888 format Default: Pixel Data RGB565 format	Specify the output data format.
Alpha value to be applied to decoded pixel data (only valid for ARGB8888 format)	255	Specify the alpha value for the output data format (only valid for ARGB8888 format).
Name of user callback function	NULL	Specify the name of user callback function.
Decompression Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Decompression interrupt priority selection.
Data Transfer Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Data transfer interrupt priority selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the JPEG Common Module

ISDE Property	Value	Description
Name	g_jpeg_common0	Module name.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

JPEG Decode HAL Module Clock Configuration

The JPEG Decode HAL Module uses the PCLKA as its clock source.

To change the clock frequency at run-time, use the CGC Interface.

JPEG Decode HAL Module Pin Configuration

The JPEG Decode HAL Module has no configurable input or output pins.

Using the JPEG Decode HAL Module in an Application

The typical steps in using the JPEG Decode HAL module in an application are:

1. Initialize the JPEG Decode using the jpeg_decode_api_t::open API.
2. Set the horizontal stride using the jpeg_decode_api_t::horizontalStrideSet API.
3. Set vertical and horizontal image sub-sample using the jpeg_decode_api_t::imageSubsampleSet API.
4. Set the input buffer address (which contains the JPEG image) using the jpeg_decode_api_t::inputBufferSet API.
5. Set the output buffer (should be large enough to hold the raw image data) using the jpeg_decode_api_t::outputBufferSet API.
6. The jpeg_decode_api_t::statusGet API can be used to get the JPEG operation. It returns an enumerated value (described above) to notify the user.
   1. The status JPEG_DECODE_STATUS_DONE returned from the jpeg_decode_api_t::statusGet API shows that the Decode operation is complete.
   2. The status JPEG_DECODE_STATUS_INPUT_PAUSE or JPEG_DECODE_STATUS_OUTPUT_PAUSE returned from the jpeg_decode_api_t::statusGet API shows that the decode operation is not complete.
   3. Implement a timeout detect function as part of this step. Refer to the wait function used for the JPEG Decode Framework if an illustration is required.
7. Operate on the received raw image data as needed by the application.
8. Close the module using the jpeg_decode_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical JPEG Decode HAL Module Application