JPEG Encode Driver

Table of Contents

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

JPEG Encode HAL Module Introduction

The JPEG Encode HAL module provides a high-level API for industry standard JPEG image encode processing (compression) and uses the Synergy MCU JPEG Codec peripheral. A user callback function is available to inform the application program of key processing events.

JPEG Encode HAL Module Features

• Supports JPEG Compression.
• Supports polling mode that allows an application to wait for JPEG Encoder to complete.
• Supports interrupt mode with user-supplied callback functions.
• Configures parameters such as horizontal and vertical resolution, horizontal stride, and Quality factor. 
• Supports putting raw image data in an input buffer and an output buffer to store the encoded/compressed jpeg image.
• Supports streaming raw image data into JPEG Encoder module. This feature allows an application to read coded raw image from a capture device or camera or from network without buffering the entire image.
• Only supports the YCbCr422 color space to input.
• Supports DRI Maker for RTP streaming application.
• Supports quality factor configuration: The quality factor value determines the quality of output image.

JPEG Encode HAL Module Block Diagram

JPEG Encode 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	Input data format 8 lines by 8 pixels in YCbCr444	Input data format 8 lines by 16 pixels in YCbCr422	Input data format 8 lines by 32 pixels in YCbCr411	Input data format 16 lines by 16 pixels in YCbCr420	Output format JPEG
S124	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A
S3A1	N/A	N/A	N/A	N/A	N/A
S3A3	N/A	N/A	N/A	N/A	N/A
S3A6	N/A	N/A	N/A	N/A	N/A
S3A7	N/A	N/A	N/A	N/A	N/A
S5D3	N/A	N/A	N/A	N/A	N/A
S5D5	N/A	N/A	N/A	N/A	N/A
S5D9	N/A	✓	N/A	N/A	✓
S7G2	N/A	✓	N/A	N/A	✓

JPEG Encode HAL Module APIs Overview

The JPEG Encode HAL Module defines APIs to open, set up processing parameters for, process, get status from 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 HAL Module API Summary.

JPEG Encode HAL Module API Summary

Function Name	Example API Call and Description
open	g_jpeg_encode0.p_api->open(g_jpeg_encode0.p_ctrl, g_jpeg_encode0.p_cfg); Initial configuration.
imageParameterSet	g_jpeg_encode0.p_api->imageParameterSet(g_jpeg_encode0.p_ctrl, p_image_parameters); Set image parameters to JPEG Codec.
outputBufferSet	g_jpeg_encode0.p_api->outputBufferSet(g_jpeg_encode0.p_ctrl, p_buffer); Assign output buffer to JPEG Codec for storing output data.
inputBufferSet	g_jpeg_encode0.p_api->inputBufferSet(g_jpeg_encode0.p_ctrl, p_buffer, buffer_size); Assign input data buffer to JPEG Codec.
statusGet	g_jpeg_encode0.p_api->statusGet(g_jpeg_encode0.p_ctrl, p_status); Retrieve current status of the JPEG Codec module.
close	g_jpeg_encode0.p_api->close(g_jpeg_encode0.p_ctrl); Cancel an outstanding operation.
versionGet	g_jpeg_encode0.p_api->versionGet(&version); Get version and store it in the provided pointer 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	API Call Successful.
SSP_ERR_INVALID_ARGUMENT	Parameter has invalid value.
SSP_ERR_INVALID_ALIGNMENT	Horizontal 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.

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 Encode HAL Module Operational Overview

The JPEG Encoder HAL module can be used in the input buffer streaming mode or normal mode.

Input Buffer Streaming Mode Operational Description

In this mode the raw image data arrives from the network, file or capturing device in separate data 'chunks'. The HAL-layer driver handles this mode without requiring the input data to be stored in memory first.

Normal Operational Description

In this mode raw image data arrives from the network, file or capturing device as a complete frame. The HAL-layer driver handles this mode and can compress the entire raw image frame.

JPEG Encode HAL Module Important Operational Notes and Limitations

JPEG Encode HAL Module Operational Notes

Motion JPEG

There is no defined standard for Motion JPEG (MJPEG), but the basic concept is to continuously project JPEG images to the rendering device. The basic application steps to implement an MJPEG function using the JPEG Encoder HAL module are as follows:

1. Open the JPEG Encoder driver with the desired quality factor value (default = 50).
2. Setup the image resolution (optional if already configured in Thread stack window).
3. Initialize the capturing device for capturing a YCbCr422 image.
4. Set the output buffer to hold the jpeg image using the jpeg_encode_api_t::outputBufferSet API function.
5. Capture the image.
6. Set the input buffer which holds the RAW YCbCr 422 image captured from the capturing device using jpeg_encode_api_t::inputBufferSet API function.
7. Check the status of the encode operation and if DONE send the image to the rendering device.
8. Continue the process from step 5 as needed.

JPEG Encode 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 encoding procedure.

Event Name	Event Condition
JPEG_ENCODE_STATUS_INPUT_PAUSE	JPEG Encode paused waiting for more input data.
JPEG_ENCODE_STATUS_DONE	JPEG Encode 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 Encode HAL Module Limitations

• The JPEG Encode HAL module only support JPEG Encode processing. For decoding please use the JPEG Decode HAL module.
• In an Application where both the encode and decode modules are used, JPEG Decode module needs to be closed for the application to use JPEG Encode driver (or vice versa) as both modules share the same MCU peripheral.
• The JPEG Encode HAL module only supports the "Normal byte order" in the thread stack window. Other option may result in an invalid image.

Including the JPEG Encode HAL Module in an Application

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

JPEG Encode HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_jpeg_encode0 JPEG Encode Driver on r_jpeg_encode	Threads	New Stack> Driver> Graphics> JPEG Encode Driver

When the JPEG Encode Driver on r_jpeg_encode 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 Encode HAL Module Stack

Configuring the JPEG Encode HAL Module

The JPEG Encode 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 Encode HAL Module on r_jpeg_encode

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_jpeg_encode0	Module name.
RAW Image Vertical Resolution	800	RAW image vertical resolution selection.
RAW Image Horizontal Resolution	480	RAW image horizontal resolution selection.
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	Byte order for input data format selection.
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	Byte order for output data format selection.
Define Restart Marker	512	Define restart marker selection.
Quality Factor	50	Quality factor selection.
Name of user callback function	NULL	Name of user callback function selection.
Decompression Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	Decompression interrupt priority selection.
Data Transfer Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	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 Encode HAL Module Clock Configuration

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

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

JPEG Encode HAL Module Pin Configuration

The JPEG Encode HAL module has no configurable input or output pins on the device.

Using the JPEG Encode HAL Module in an Application

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

1. Initialize the JPEG Encode using jpeg_encode_api_t::open API.
   1. Configures the quality factor, horizontal stride, horizontal and vertical resolution.
2. Set the output buffer address (should be large enough to hold compressed jpeg image) using the jpeg_encode_api_t::outputBufferSet API.
3. Set the input buffer to start the encoding operation (address of raw image data and size) using thejpeg_encode_api_t::inputBufferSet API.
4. The jpeg_encode_api_t::statusGet API can be used to get the JPEG operation, thejpeg_encode_api_t::statusGet API return an enumerated value (described above) to notify user.
   1. Status JPEG_ENCODE_STATUS_DONE from the jpeg_encode_api_t::statusGet API shows that the encode operation is complete.
   2. Status JPEG_ENCODE_STATUS_INPUT_PAUSE from the jpeg_encode_api_t::statusGet API shows that driver is waiting for more input – Go to step 3 and set the input buffer with remaining data.
5. Operate on the received JPEG image data as needed by the application.
6. Close the module using the jpeg_encode_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 Encode HAL Module Application