JPEG Codec Interface

Detailed Description

Interface for JPEG functions.

Data Structures
struct	jpeg_encode_image_size_t
struct	jpeg_callback_args_t
struct	jpeg_cfg_t
struct	jpeg_api_t
struct	jpeg_instance_t

Typedefs
typedef void	jpeg_ctrl_t

Enumerations
enum	jpeg_color_space_t
enum	jpeg_data_order_t
enum	jpeg_status_t
enum	jpeg_decode_pixel_format_t
enum	jpeg_decode_subsample_t

---

Data Structure Documentation

jpeg_encode_image_size_t

struct jpeg_encode_image_size_t

Image parameter structure

Data Fields
uint16_t	horizontal_stride_pixels	Horizontal stride.
uint16_t	horizontal_resolution	Horizontal Resolution in pixels.
uint16_t	vertical_resolution	Vertical Resolution in pixels.

jpeg_callback_args_t

struct jpeg_callback_args_t

Callback status structure

Data Fields
jpeg_status_t	status	JPEG status.
uint32_t	image_size	JPEG image size.
void *	p_context	Pointer to user-provided context.

jpeg_cfg_t

struct jpeg_cfg_t

User configuration structure, used in open function.

Data Fields
IRQn_Type	jedi_irq
	Data transfer interrupt IRQ number.
IRQn_Type	jdti_irq
	Decompression interrupt IRQ number.
uint8_t	jdti_ipl
	Data transfer interrupt priority.
uint8_t	jedi_ipl
	Decompression interrupt priority.
jpeg_mode_t	default_mode
	Mode to use at startup.
jpeg_data_order_t	decode_input_data_order
	Input data stream byte order.
jpeg_data_order_t	decode_output_data_order
	Output data stream byte order.
jpeg_decode_pixel_format_t	pixel_format
	Pixel format.
uint8_t	alpha_value
	Alpha value to be applied to decoded pixel data. Only valid for ARGB8888 format.
void(*	p_decode_callback )(jpeg_callback_args_t *p_args)
	User-supplied callback functions.
void *	p_decode_context
	Placeholder for user data. Passed to user callback in jpeg_callback_args_t.
jpeg_data_order_t	encode_input_data_order
	Input data stream byte order.
jpeg_data_order_t	encode_output_data_order
	Output data stream byte order.
uint16_t	dri_marker
	DRI Marker setting (0 = No DRI or RST marker)
uint16_t	horizontal_resolution
	Horizontal resolution of input image.
uint16_t	vertical_resolution
	Vertical resolution of input image.
uint16_t	horizontal_stride_pixels
	Horizontal stride of input image.
uint8_t const *	p_quant_luma_table
	Luma quantization table.
uint8_t const *	p_quant_chroma_table
	Chroma quantization table.
uint8_t const *	p_huffman_luma_ac_table
	Huffman AC table for luma.
uint8_t const *	p_huffman_luma_dc_table
	Huffman DC table for luma.
uint8_t const *	p_huffman_chroma_ac_table
	Huffman AC table for chroma.
uint8_t const *	p_huffman_chroma_dc_table
	Huffman DC table for chroma.
void(*	p_encode_callback )(jpeg_callback_args_t *p_args)
	User-supplied callback functions.
void *	p_encode_context
	Placeholder for user data. Passed to user callback in jpeg_callback_args_t.

jpeg_api_t

struct jpeg_api_t

JPEG functions implemented at the HAL layer will follow this API.

Data Fields
fsp_err_t(*	open )(jpeg_ctrl_t *const p_ctrl, jpeg_cfg_t const *const p_cfg)
fsp_err_t(*	inputBufferSet )(jpeg_ctrl_t *const p_ctrl, void *p_buffer, uint32_t buffer_size)
fsp_err_t(*	outputBufferSet )(jpeg_ctrl_t *const p_ctrl, void *p_buffer, uint32_t buffer_size)
fsp_err_t(*	statusGet )(jpeg_ctrl_t *const p_ctrl, jpeg_status_t *const p_status)
fsp_err_t(*	close )(jpeg_ctrl_t *const p_ctrl)
fsp_err_t(*	horizontalStrideSet )(jpeg_ctrl_t *const p_ctrl, uint32_t horizontal_stride)
fsp_err_t(*	pixelFormatGet )(jpeg_ctrl_t *const p_ctrl, jpeg_color_space_t *const p_color_space)
fsp_err_t(*	imageSubsampleSet )(jpeg_ctrl_t *const p_ctrl, jpeg_decode_subsample_t horizontal_subsample, jpeg_decode_subsample_t vertical_subsample)
fsp_err_t(*	linesDecodedGet )(jpeg_ctrl_t *const p_ctrl, uint32_t *const p_lines)
fsp_err_t(*	imageSizeGet )(jpeg_ctrl_t *const p_ctrl, uint16_t *p_horizontal_size, uint16_t *p_vertical_size)
fsp_err_t(*	imageSizeSet )(jpeg_ctrl_t *const p_ctrl, jpeg_encode_image_size_t *p_image_size)
fsp_err_t(*	modeSet )(jpeg_ctrl_t *const p_ctrl, jpeg_mode_t mode)

Field Documentation

open

fsp_err_t(* jpeg_api_t::open) (jpeg_ctrl_t *const p_ctrl, jpeg_cfg_t const *const p_cfg)

Initial configuration

Precondition

none

Parameters

[in,out]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

inputBufferSet

fsp_err_t(* jpeg_api_t::inputBufferSet) (jpeg_ctrl_t *const p_ctrl, void *p_buffer, uint32_t buffer_size)

Assign input data buffer to JPEG codec.

Precondition

the JPEG codec module must have been opened properly.

Note

The buffer starting address must be 8-byte aligned.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[in]	p_buffer	Pointer to the input buffer space
[in]	buffer_size	Size of the input buffer

outputBufferSet

fsp_err_t(* jpeg_api_t::outputBufferSet) (jpeg_ctrl_t *const p_ctrl, void *p_buffer, uint32_t buffer_size)

Assign output buffer to JPEG codec for storing output data.

Precondition

The JPEG codec module must have been opened properly.

Note

The buffer starting address must be 8-byte aligned. For the decoding process, the HLD driver automatically computes the number of lines of the image to decoded so the output data fits into the given space. If the supplied output buffer is not able to hold the entire frame, the application should call the Output Full Callback function so it can be notified when additional buffer space is needed.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[in]	p_buffer	Pointer to the output buffer space
[in]	buffer_size	Size of the output buffer

statusGet

fsp_err_t(* jpeg_api_t::statusGet) (jpeg_ctrl_t *const p_ctrl, jpeg_status_t *const p_status)

Retrieve current status of the JPEG codec module.

Precondition

the JPEG codec module must have been opened properly.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[out]	p_status	JPEG module status

close

fsp_err_t(* jpeg_api_t::close) (jpeg_ctrl_t *const p_ctrl)

Cancel an outstanding operation.

Precondition

the JPEG codec module must have been opened properly.

Note

If the encoding or the decoding operation is finished without errors, the HLD driver automatically closes the device. In this case, application does not need to explicitly close the JPEG device.

Parameters

[in]

p_ctrl

Control block set in jpeg_api_t::open call.

horizontalStrideSet

fsp_err_t(* jpeg_api_t::horizontalStrideSet) (jpeg_ctrl_t *const p_ctrl, uint32_t horizontal_stride)

Configure the horizontal stride value.

Precondition

The JPEG codec module must have been opened properly.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[in]	horizontal_stride	Horizontal stride value to be used for the decoded image data.
[in]	buffer_size	Size of the output buffer

pixelFormatGet

fsp_err_t(* jpeg_api_t::pixelFormatGet) (jpeg_ctrl_t *const p_ctrl, jpeg_color_space_t *const p_color_space)

Get the input pixel format.

Precondition

the JPEG codec module must have been opened properly.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[out]	p_color_space	JPEG input format.

imageSubsampleSet

fsp_err_t(* jpeg_api_t::imageSubsampleSet) (jpeg_ctrl_t *const p_ctrl, jpeg_decode_subsample_t horizontal_subsample, jpeg_decode_subsample_t vertical_subsample)

Configure the horizontal and vertical subsample settings.

Precondition

The JPEG codec module must have been opened properly.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[in]	horizontal_subsample	Horizontal subsample value
[in]	vertical_subsample	Vertical subsample value

linesDecodedGet

fsp_err_t(* jpeg_api_t::linesDecodedGet) (jpeg_ctrl_t *const p_ctrl, uint32_t *const p_lines)

Return the number of lines decoded into the output buffer.

Precondition

the JPEG codec module must have been opened properly.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[out]	p_lines	Number of lines decoded

imageSizeGet

fsp_err_t(* jpeg_api_t::imageSizeGet) (jpeg_ctrl_t *const p_ctrl, uint16_t *p_horizontal_size, uint16_t *p_vertical_size)

Retrieve image size during decoding operation.

Precondition

the JPEG codec module must have been opened properly.

Note

If the encoding or the decoding operation is finished without errors, the HLD driver automatically closes the device. In this case, application does not need to explicitly close the JPEG device.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[out]	p_horizontal_size	Image horizontal size, in number of pixels.
[out]	p_vertical_size	Image vertical size, in number of pixels.

imageSizeSet

fsp_err_t(* jpeg_api_t::imageSizeSet) (jpeg_ctrl_t *const p_ctrl, jpeg_encode_image_size_t *p_image_size)

Set image parameters to JPEG Codec

Precondition

The JPEG codec module must have been opened properly.

Parameters

[in,out]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_image_size	Pointer to the RAW image parameters

modeSet

fsp_err_t(* jpeg_api_t::modeSet) (jpeg_ctrl_t *const p_ctrl, jpeg_mode_t mode)

Switch between encode and decode mode or vice-versa.

Precondition

The JPEG codec module must have been opened properly. The JPEG Codec can only perform one operation at a time and requires different configuration for encode and decode. This function facilitates easy switching between the two modes in case both are needed in an application.

Parameters

[in]	p_ctrl	Control block set in jpeg_api_t::open call.
[in]	mode	Mode to switch to

jpeg_instance_t

struct jpeg_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
jpeg_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
jpeg_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
jpeg_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

jpeg_ctrl_t

typedef void jpeg_ctrl_t

JPEG decode control block. Allocate an instance specific control block to pass into the JPEG decode API calls.

Enumeration Type Documentation

jpeg_color_space_t

enum jpeg_color_space_t

Configuration for this module Image color space definitions

Enumerator
JPEG_COLOR_SPACE_YCBCR444	Color Space YCbCr 444.
JPEG_COLOR_SPACE_YCBCR422	Color Space YCbCr 422.
JPEG_COLOR_SPACE_YCBCR420	Color Space YCbCr 420.
JPEG_COLOR_SPACE_YCBCR411	Color Space YCbCr 411.

jpeg_data_order_t

enum jpeg_data_order_t

Multi-byte Data Format

Enumerator
JPEG_DATA_ORDER_NORMAL	(1)(2)(3)(4)(5)(6)(7)(8) Normal byte order
JPEG_DATA_ORDER_BYTE_SWAP	(2)(1)(4)(3)(6)(5)(8)(7) Byte Swap
JPEG_DATA_ORDER_WORD_SWAP	(3)(4)(1)(2)(7)(8)(5)(6) Word Swap
JPEG_DATA_ORDER_WORD_BYTE_SWAP	(4)(3)(2)(1)(8)(7)(6)(5) Word-Byte Swap
JPEG_DATA_ORDER_LONGWORD_SWAP	(5)(6)(7)(8)(1)(2)(3)(4) Longword Swap
JPEG_DATA_ORDER_LONGWORD_BYTE_SWAP	(6)(5)(8)(7)(2)(1)(4)(3) Longword Byte Swap
JPEG_DATA_ORDER_LONGWORD_WORD_SWAP	(7)(8)(5)(6)(3)(4)(1)(2) Longword Word Swap
JPEG_DATA_ORDER_LONGWORD_WORD_BYTE_SWAP	(8)(7)(6)(5)(4)(3)(2)(1) Longword Word Byte Swap

jpeg_status_t

enum jpeg_status_t

JPEG HLD driver internal status information. The driver can simultaneously be in more than any one status at the same time. Parse the status bit-fields using the definitions in this enum to determine driver status

Enumerator
JPEG_STATUS_NONE	JPEG codec module is not initialized.
JPEG_STATUS_IDLE	JPEG Codec module is open but not running.
JPEG_STATUS_RUNNING	JPEG Codec is running.
JPEG_STATUS_HEADER_PROCESSING	JPEG Codec module is reading the JPEG header information.
JPEG_STATUS_INPUT_PAUSE	JPEG Codec paused waiting for more input data.
JPEG_STATUS_OUTPUT_PAUSE	JPEG Codec paused after it decoded the number of lines specified by user.
JPEG_STATUS_IMAGE_SIZE_READY	JPEG decoding operation obtained image size, and paused.
JPEG_STATUS_ERROR	JPEG Codec module encountered an error.
JPEG_STATUS_OPERATION_COMPLETE	JPEG Codec has completed the operation.

jpeg_decode_pixel_format_t

enum jpeg_decode_pixel_format_t

Pixel Data Format

Enumerator
JPEG_DECODE_PIXEL_FORMAT_ARGB8888	Pixel Data ARGB8888 format.
JPEG_DECODE_PIXEL_FORMAT_RGB565	Pixel Data RGB565 format.

jpeg_decode_subsample_t

enum jpeg_decode_subsample_t

Data type for horizontal and vertical subsample settings. This setting applies only to the decoding operation.

Enumerator
JPEG_DECODE_OUTPUT_NO_SUBSAMPLE	No subsample. The image is decoded with no reduction in size.
JPEG_DECODE_OUTPUT_SUBSAMPLE_HALF	The output image size is reduced by half.
JPEG_DECODE_OUTPUT_SUBSAMPLE_ONE_QUARTER	The output image size is reduced to one-quarter.
JPEG_DECODE_OUTPUT_SUBSAMPLE_ONE_EIGHTH	The output image size is reduced to one-eighth.