JPEG Decode Framework

Table of Contents

• JPEG Decode Framework Module Introduction
  • JPEG Decode Framework Module Features
• JPEG Decode Framework Module APIs Overview
• JPEG Decode Framework Module Operational Overview
  • JPEG Decode Framework Module Important Operational Notes and Limitations
    • JPEG Decode Framework Module Operational Notes
    • JPEG Decode Framework Module Limitations
• Including the JPEG Decode Framework Module in an Application
• Configuring the JPEG Decode Framework Module
  • Configuration Settings for the JPEG Decode Framework Module Lower Level Modules
  • JPEG Decode Framework Module Clock Configuration
  • JPEG Decode Framework Module Interrupt Configuration
  • JPEG Decode Framework Module Pin Configuration
• Using the JPEG Decode Framework Module in an Application

JPEG Decode Framework Module Introduction

The JPEG Decode HAL module provides a high-level API for industry standard JPEG image decode processing and supports the Renesas Synergy™ JPEG Codec peripheral. The JPEG Decode Framework Module is a ThreadX^®-aware implementation and provides thread-safe access to the Synergy JPEG hardware on a Synergy MCU. A user-defined callback can be created to detect hardware supported events.

JPEG Decode Framework Module Features

• Provides thread-safe access to the Synergy JPEG hardware.
• Supports JPEG decompression using the JPEG Decode HAL module.
• Supports a polling mode that allows an application to wait for the JPEG Decoder to complete.
• Supports an 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 the JPEG Decoder module. This feature allows an application to read a coded JPEG image from a file or from a 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 formats YCbCr444, YCbCr422, YCbCr420 and YCbCr411.
• Supports the output formats ARGB8888 and RGB565.
• Returns an error when the JPEG image's size, height, and width do not meet the requirements.
• Supports the sf_jpeg_decode_api_t::wait API function to suspend/resume the thread for synchronizing with the JPEG hardware supported events.

JPEG Decode Framework Module Block Diagram

JPEG Decode Framework Module APIs Overview

The JPEG Decode Framework module defines APIs for opening, closing, setting alarms and starting and stopping RTC operations. 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 Framework Module API Summary

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

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	JPEG Decode driver is successfully opened.
SSP_ERR_ASSERTION	Assertion error.
SSP_ERR_IN_USE	Module already in use.
SSP_ERR_TIMEOUT	The wait operation times out, the underlying driver did not respond in time.
SSP_ERR_WAIT_ABORTED	System internal error occurred.

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 Framework Module Operational Overview

The JPEG Decode Framework module implements the standard JPEG decode operation. It takes the data in an input buffer and applies the defined JPEG decode algorithm to the buffer, the output is then delivered to the defined output buffer location. A wait API function can be used to suspend/resume the thread for synchronization with JPEG hardware supported events.

JPEG Decode Framework Module Important Operational Notes and Limitations

JPEG Decode Framework Module Operational Notes

• Start decoding JPEG-encoded data by calling the sf_jpeg_decode_api_t::open API. To open the module, use the JPEG Decode Framework module instance, that includes the API function pointer, the pointer to the control block and static configuration that is generated through the Synergy Project configurator in the e² studio for ISDE.
• Stop the JPEG Decode Framework module by calling the sf_jpeg_decode_api_t::close API.
• An input buffer-streaming mode is available when an input-centric function is needed.
• An output buffer-streaming mode is available when an output-centric function is needed.
• Supports RGB565 and ARGBB888 output data-color formats.
• The JPEG Decode Framework module has a status flag in the control block, which provides the current status of the module through the sf_jpeg_decode_api_t::statusGet API. The status is also reported through a user-callback function when specific events occur in the module.
• The JPEG Decode Framework module supports buffer-streaming mode for the input buffer in cases when the input buffer is smaller than the source image size. Set the next input frame as an input buffer every time there is a hardware-generated INPUT_PAUSE interrupt.
• The JPEG Decode Framework module supports buffer-streaming mode for the output buffer in cases when the resultant image is larger than the output buffer-size. Read and store data from the output buffer to make space for upcoming data every time there is a hardware generated OUTPUT_PAUSE interrupt.
• The input and output buffers should be 8-bytes aligned for the JPEG Decode Framework module to be successful. Otherwise, API functions will return error codes that indicate unsuccessful execution.

JPEG Decode Framework Module Limitations

• The JPEG Decode Framework module does not support JPEG-encode processing.
• Check for timeout error (SSP_ERR_TIMEOUT) using sf_jpeg_decode_api_t::wait API; if it returns timeout error, close the framework, re-open it and then perform the decoding operation.
• Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the JPEG Decode Framework Module in an Application

This section describes how to include the JPEG Decode Framework 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 Framework 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 Framework is g_sf_jpeg_decode0. This name can be changed in the associated Properties window.)

JPEG Decode Framework Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sf_jpeg_decode0 JPEG Framework	Threads	New Stack> Framework> Graphics> JPEG Decode Framework on sf_jpeg_decode

When the JPEG Decode Framework on sf_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 Framework Module Stack

Decompression Process Interrupt (JEDI)

The JPEG decompression-process interrupt occurs when:

• The current decompression process is successfully completed.
• An error happens in the decompression process.
• Image size and pixel format are successfully read out.

Data Transfer Interrupt (JDTI)

The JPEG data-transfer interrupt occurs when:

• All the JPEG-coded data has successfully completed.
• The number of output image-data lines specified by sf_jpeg_decode_api_t::linesDecodedGet has been transferred.

The number of input image-data lines specified by sf_jpeg_decode_api_t::inputBufferSet has been transferred.

Configuring the JPEG Decode Framework Module

The JPEG Decode Framework 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 Framework Module on sf_jpeg_decode

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter checking.
Name	g_sf_jpeg_decode0	The name to be used for a JPEG Decode Framework module instance.

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 Decode Framework Module Lower Level Modules

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.

Configuration Settings for the JPEG HAL Module on r_jpeg

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 Swap (7)(8)(5)(6)(3)(4)(1)(2) 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 Swap (7)(8)(5)(6)(3)(4)(1)(2) 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 Framework Module Clock Configuration

The JPEG Framework module uses the peripheral module clock A (PCLKA) to run the internal logic.

JPEG Decode Framework Module Interrupt Configuration

To enable interrupts, set the priority of the decompression interrupt and the data-transfer interrupt in the Properties window of the JPEG Decode Framework module in the ISDE.

JPEG Decode Framework Module Pin Configuration

The JPEG Decode Framework module does not use any pins.

Using the JPEG Decode Framework Module in an Application

The steps in using the JPEG Decode Framework module in a typical application are:

1. Initialize the JPEG Decode peripheral using the sf_jpeg_decode_api_t::open API.
2. Set Image Subsample using the sf_jpeg_decode_api_t::imageSubsampleSet API.
3. Set Horizontal stride using the sf_jpeg_decode_api_t::horizontalStrideSet API.
4. Set output buffer using the sf_jpeg_decode_api_t::outputBufferSet API.
5. Set Input buffer using the sf_jpeg_decode_api_t::inputBufferSet API.
6. Wait for decode to complete with the sf_jpeg_decode_api_t::wait API.
7. Check decode status with the sf_jpeg_decode_api_t::statusGet API.
8. Close the instance with the sf_jpeg_decode_api_t::close API (if needed).

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

Flow Diagram of a Typical JPEG Decode Framework Module Application