 |
RTEMS 6.1-rc4
|
Loading...
Searching...
No Matches
|
RTEMS 6.1-rc4
|
JPEG HAL module driver. This file provides firmware functions to manage the following functionalities of the JPEG encoder/decoder peripheral: More...
#include "stm32h7xx_hal.h"JPEG HAL module driver. This file provides firmware functions to manage the following functionalities of the JPEG encoder/decoder peripheral:
Copyright (c) 2017 STMicroelectronics. All rights reserved.
This software is licensed under terms that can be found in the LICENSE file in the root directory of this software component. If no LICENSE file comes with this software, it is provided AS-IS.
==============================================================================
##### How to use this driver #####
==============================================================================
[..]
(#) Initialize the JPEG peripheral using HAL_JPEG_Init : No initialization parameters are required.
Only the call to HAL_JPEG_Init is necessary to initialize the JPEG peripheral.
(#) If operation is JPEG encoding use function HAL_JPEG_ConfigEncoding to set
the encoding parameters (mandatory before calling the encoding function).
the application can change the encoding parameter ImageQuality from
1 to 100 to obtain a more or less quality (visual quality vs the original row image),
and inversely more or less jpg file size.
(#) Note that for decoding operation the JPEG peripheral output data are organized in
YCbCr blocks called MCU (Minimum Coded Unit) as defioned 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 should 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 functions HAL_JPEG_Encode and HAL_JPEG_Decode to start respectively
a JPEG encoding/decoding operation in polling method (blocking).
(#) Use functions HAL_JPEG_Encode_IT and HAL_JPEG_Decode_IT to start respectively
a JPEG encoding/decoding operation with Interrupt method (not blocking).
(#) Use functions HAL_JPEG_Encode_DMA and HAL_JPEG_Decode_DMA to start respectively
a JPEG encoding/decoding operation with DMA method (not blocking).
(#) Callback HAL_JPEG_InfoReadyCallback is asserted if the current operation
is a JPEG decoding to provide the application with JPEG image parameters.
This callback is asserted when the JPEG peripheral successfully parse the
JPEG header.
(#) Callback HAL_JPEG_GetDataCallback is asserted for both encoding and decoding
operations to inform the application that the input buffer has been
consumed by the peripheral and to ask for a new data chunk if the operation
(encoding/decoding) has not been complete yet.
(++) This CallBack should be implemented in the application side. It should
call the function HAL_JPEG_ConfigInputBuffer if new input data are available,
or call HAL_JPEG_Pause with parameter XferSelection set to JPEG_PAUSE_RESUME_INPUT
to inform the JPEG HAL driver that the ongoing operation shall pause waiting for the
application to provide a new input data chunk.
Once the application succeed getting new data and if the input has been paused,
the application can call the function HAL_JPEG_ConfigInputBuffer to set the new
input buffer and size, then resume the JPEG HAL input by calling new function HAL_JPEG_Resume.
If the application has ended feeding the HAL JPEG with input data (no more input data), the application
Should call the function HAL_JPEG_ConfigInputBuffer (within the callback HAL_JPEG_GetDataCallback)
with the parameter InDataLength set to zero.
(++) The mechanism of HAL_JPEG_ConfigInputBuffer/HAL_JPEG_Pause/HAL_JPEG_Resume allows
to the application to provide the input data (for encoding or decoding) by chunks.
If the new input data chunk is not available (because data should be read from an input file
for example) the application can pause the JPEG input (using function HAL_JPEG_Pause)
Once the new input data chunk is available ( read from a file for example), the application
can call the function HAL_JPEG_ConfigInputBuffer to provide the HAL with the new chunk
then resume the JPEG HAL input by calling function HAL_JPEG_Resume.
(++) The application can call functions HAL_JPEG_ConfigInputBuffer then HAL_JPEG_Resume.
any time (outside the HAL_JPEG_GetDataCallback) Once the new input chunk data available.
However, to keep data coherency, the function HAL_JPEG_Pause must be imperatively called
(if necessary) within the callback HAL_JPEG_GetDataCallback, i.e when the HAL JPEG has ended
Transferring the previous chunk buffer to the JPEG peripheral.
(#) Callback HAL_JPEG_DataReadyCallback is asserted when the HAL JPEG driver
has filled the given output buffer with the given size.
(++) This CallBack should be implemented in the application side. It should
call the function HAL_JPEG_ConfigOutputBuffer to provide the HAL JPEG driver
with the new output buffer location and size to be used to store next data chunk.
if the application is not ready to provide the output chunk location then it can
call the function HAL_JPEG_Pause with parameter XferSelection set to JPEG_PAUSE_RESUME_OUTPUT
to inform the JPEG HAL driver that it shall pause output data. Once the application
is ready to receive the new data chunk (output buffer location free or available) it should call
the function HAL_JPEG_ConfigOutputBuffer to provide the HAL JPEG driver
with the new output chunk buffer location and size, then call HAL_JPEG_Resume
to inform the HAL that it shall resume outputting data in the given output buffer.
(++) The mechanism of HAL_JPEG_ConfigOutputBuffer/HAL_JPEG_Pause/HAL_JPEG_Resume allows
the application to receive data from the JPEG peripheral by chunks. when a chunk
is received, the application can pause the HAL JPEG output data to be able to process
these received data (YCbCr to RGB conversion in case of decoding or data storage in case
of encoding).
(++) The application can call functions HAL_JPEG_ ConfigOutputBuffer then HAL_JPEG_Resume.
any time (outside the HAL_JPEG_DataReadyCallback) Once the output data buffer is free to use.
However, to keep data coherency, the function HAL_JPEG_Pause must be imperatively called
(if necessary) within the callback HAL_JPEG_ DataReadyCallback, i.e when the HAL JPEG has ended
Transferring the previous chunk buffer from the JPEG peripheral to the application.
(#) Callback HAL_JPEG_EncodeCpltCallback is asserted when the HAL JPEG driver has
ended the current JPEG encoding operation, and all output data has been transmitted
to the application.
(#) Callback HAL_JPEG_DecodeCpltCallback is asserted when the HAL JPEG driver has
ended the current JPEG decoding operation. and all output data has been transmitted
to the application.
(#) Callback HAL_JPEG_ErrorCallback is asserted when an error occurred during
the current operation. the application can call the function HAL_JPEG_GetError()
to retrieve the error codes.
(#) 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_SetUserQuantTables
Note that for decoding the quantization tables are automatically extracted from
the JPEG header.
(#) To control JPEG state you can use the following function: HAL_JPEG_GetState()
*** JPEG HAL driver macros list ***
=============================================
[..]
Below the list of most used macros in JPEG HAL driver.
(+) __HAL_JPEG_RESET_HANDLE_STATE : Reset JPEG handle state.
(+) __HAL_JPEG_ENABLE : Enable the JPEG peripheral.
(+) __HAL_JPEG_DISABLE : Disable the JPEG peripheral.
(+) __HAL_JPEG_GET_FLAG : Check the specified JPEG status flag.
(+) __HAL_JPEG_CLEAR_FLAG : Clear the specified JPEG status flag.
(+) __HAL_JPEG_ENABLE_IT : Enable the specified JPEG Interrupt.
(+) __HAL_JPEG_DISABLE_IT : Disable the specified JPEG Interrupt.
(+) __HAL_JPEG_GET_IT_SOURCE : returns the state of the specified JPEG Interrupt (Enabled or disabled).
*** Callback registration ***
=============================================
The compilation define USE_HAL_JPEG_REGISTER_CALLBACKS when set to 1
allows the user to configure dynamically the driver callbacks.
Use Functions HAL_JPEG_RegisterCallback() or HAL_JPEG_RegisterXXXCallback()
to register an interrupt callback.
Function HAL_JPEG_RegisterCallback() allows to register following callbacks:
(+) EncodeCpltCallback : callback for end of encoding operation.
(+) DecodeCpltCallback : callback for end of decoding operation.
(+) ErrorCallback : callback for error detection.
(+) MspInitCallback : JPEG MspInit.
(+) MspDeInitCallback : JPEG MspDeInit.
This function takes as parameters the HAL peripheral handle, the Callback ID
and a pointer to the user callback function.
For specific callbacks InfoReadyCallback, GetDataCallback and DataReadyCallback use dedicated
register callbacks : respectively HAL_JPEG_RegisterInfoReadyCallback(),
HAL_JPEG_RegisterGetDataCallback() and HAL_JPEG_RegisterDataReadyCallback().
Use function HAL_JPEG_UnRegisterCallback() to reset a callback to the default
weak function.
HAL_JPEG_UnRegisterCallback() takes as parameters the HAL peripheral handle,
and the Callback ID.
This function allows to reset following callbacks:
(+) EncodeCpltCallback : callback for end of encoding operation.
(+) DecodeCpltCallback : callback for end of decoding operation.
(+) ErrorCallback : callback for error detection.
(+) MspInitCallback : JPEG MspInit.
(+) MspDeInitCallback : JPEG MspDeInit.
For callbacks InfoReadyCallback, GetDataCallback and DataReadyCallback use dedicated
unregister callbacks : respectively HAL_JPEG_UnRegisterInfoReadyCallback(),
HAL_JPEG_UnRegisterGetDataCallback() and HAL_JPEG_UnRegisterDataReadyCallback().
By default, after the HAL_JPEG_Init() and when the state is HAL_JPEG_STATE_RESET
all callbacks are set to the corresponding weak functions :
examples HAL_JPEG_DecodeCpltCallback() , HAL_JPEG_GetDataCallback().
Exception done for MspInit and MspDeInit functions that are
reset to the legacy weak function in the HAL_JPEG_Init()/ HAL_JPEG_DeInit() only when
these callbacks are null (not registered beforehand).
if not, MspInit or MspDeInit are not null, the HAL_JPEG_Init() / HAL_JPEG_DeInit()
keep and use the user MspInit/MspDeInit functions (registered beforehand)
Callbacks can be registered/unregistered in HAL_JPEG_STATE_READY state only.
Exception done MspInit/MspDeInit callbacks that can be registered/unregistered
in HAL_JPEG_STATE_READY or HAL_JPEG_STATE_RESET state,
thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
In that case first register the MspInit/MspDeInit user callbacks
using HAL_JPEG_RegisterCallback() before calling HAL_JPEG_DeInit()
or HAL_JPEG_Init() function.
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. 
1.9.6