esp-idf/components/esp_rom/include/esp_rom_tjpgd.h

153 lines
8.1 KiB
C
Raw Normal View History

/*
* SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*-----------------------------------------------------------------------------/
/ TJpgDec - Tiny JPEG Decompressor R0.01b (C)ChaN, 2012
/-----------------------------------------------------------------------------/
/ The TJpgDec is a generic JPEG decompressor module for tiny embedded systems.
/ This is a free software that opened for education, research and commercial
/ developments under license policy of following terms.
/
/ Copyright (C) 2012, ChaN, all right reserved.
/
/ * The TJpgDec module is a free software and there is NO WARRANTY.
/ * No restriction on use. You can use, modify and redistribute it for
/ personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY.
/ * Redistributions of source code must retain the above copyright notice.
/
/-----------------------------------------------------------------------------*/
#pragma once
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Error code */
typedef enum {
JDR_OK = 0, /* 0: Succeeded */
JDR_INTR, /* 1: Interrupted by output function */
JDR_INP, /* 2: Device error or wrong termination of input stream */
JDR_MEM1, /* 3: Insufficient memory pool for the image */
JDR_MEM2, /* 4: Insufficient stream input buffer */
JDR_PAR, /* 5: Parameter error */
JDR_FMT1, /* 6: Data format error (may be damaged data) */
JDR_FMT2, /* 7: Right format but not supported */
JDR_FMT3 /* 8: Not supported JPEG standard */
} esp_rom_tjpgd_result_t;
/* Rectangular structure */
typedef struct {
uint16_t left; /* Left end */
uint16_t right; /* Right end */
uint16_t top; /* Top end */
uint16_t bottom;/* Bottom end */
} esp_rom_tjpgd_rect_t;
typedef struct JDEC_s esp_rom_tjpgd_dec_t;
/**
* @brief Type of user defined input function to read data from input stream
* @param dec Specifies the decompression object of the decompression session
* @param buffer Specifies the pointer to the read buffer to store the read data. A NULL specifies to remove the data from input stream
* @param ndata Specifies number of bytes to read/remove from the input stream
*
* @return number of bytes read/removed. When a zero is returned, the esp_rom_tjpgd_prepare and esp_rom_tjpgd_decomp function aborts with JDR_INP
*/
typedef uint32_t (*esp_rom_tjpgd_input_function_t)(esp_rom_tjpgd_dec_t *dec, uint8_t *buffer, uint32_t ndata);
/**
* @brief User defined output function to write decompressed pixels to the output device
*
* This function is the data output interface of the TJpgDec module.
* The corresponding decompression session can be identified by the pointer to the device identifier jdec->device passed to the 5th argument of jd_prepare function.
* The bitmap is sent to the frame buffer or display device in this function.
* The first pixel in the bitmap is the left-top of the rectangular, the second one is next right and last pixel is the bottom-right of the rectangular.
* The size of rectangular varies from 1x1 to 16x16 depends on clipping, scaling and sampling factor of the image.
* If the rectangular is out of the frame buffer, it should be clipped in this function.
*
* The pixel format is currently configured to RGB888
*
* @param dec Specifies the decompression object of the decompression session
* @param bitmap Specifies the RGB bitmap to be output
* @param rect Specifies rectangular region in the image to output the RGB bitmap
*
* @return Normally returns 1. It lets TJpgDec to continue the decompressing process.
* When a 0 is returned, the esp_rom_tjpgd_decomp function aborts with JDR_INTR.
* This is useful to interrupt the decompression process
*/
typedef uint32_t (*esp_rom_tjpgd_output_function_t)(esp_rom_tjpgd_dec_t *dec, void *bitmap, esp_rom_tjpgd_rect_t *rect);
struct JDEC_s {
uint32_t dctr; /* Number of bytes available in the input buffer */
uint8_t *dptr; /* Current data read ptr */
uint8_t *inbuf; /* Bit stream input buffer */
uint8_t dmsk; /* Current bit in the current read byte */
uint8_t scale; /* Output scaling ratio */
uint8_t msx, msy; /* MCU size in unit of block (width, height) */
uint8_t qtid[3]; /* Quantization table ID of each component */
int16_t dcv[3]; /* Previous DC element of each component */
uint16_t nrst; /* Restart inverval */
uint32_t width, height; /* Size of the input image (pixel) */
uint8_t *huffbits[2][2]; /* Huffman bit distribution tables [id][dcac] */
uint16_t *huffcode[2][2]; /* Huffman code word tables [id][dcac] */
uint8_t *huffdata[2][2]; /* Huffman decoded data tables [id][dcac] */
int32_t *qttbl[4]; /* Dequaitizer tables [id] */
void *workbuf; /* Working buffer for IDCT and RGB output */
uint8_t *mcubuf; /* Working buffer for the MCU */
void *pool; /* Pointer to available memory pool */
uint32_t sz_pool; /* Size of momory pool (bytes available) */
esp_rom_tjpgd_input_function_t infunc; /* Pointer to jpeg stream input function */
void *device; /* Pointer to I/O device identifiler for the session */
};
/* TJpgDec API functions */
/**
* @brief Analyzes the JPEG data and create a decompression object for subsequent decompression process.
* @param dec Specifies the decompression object to be initialized. The decompression object is used for subsequent decompression process.
* @param infunc Specifies the user defined data input function.
* @param work Specifies pointer to the work area for this session. It should be aligned to word boundary or it can result an exception.
* @param sz_work Specifies size of the work area in unit of byte.
* TJpgDec requires upto 3092 bytes of work area depends on the built-in parameter tables of the JPEG image.
* Thus 3092 bytes of work area is sufficient for most case.
* @param dev Specifies pointer to the user defined device identifier for this session.
* It is stored to the member device in the decompression object. It can be referred by I/O functions to identify the current session.
* When I/O device is fixed in the project or this feature is not needed, set NULL and do not care about this.
*
* @return
* - JDR_OK Function succeeded and decompression object is valid.
* - JDR_INP An error occurred in input function due to hard error or wrong stream termination.
* - JDR_MEM1 Insufficient work area for this JPEG image.
* - JDR_MEM2 Insufficient input buffer for this JPEG image. JD_SZBUF may be too small.
* - JDR_PAR Parameter error. Given pointer to the work area is NULL.
* - JDR_FMT1 Data format error. The JPEG data can be collapsed.
* - JDR_FMT2 Right format but not supported. May be a grayscale image.
* - JDR_FMT3 Not supported JPEG standard. May be a progressive JPEG image.
*/
esp_rom_tjpgd_result_t esp_rom_tjpgd_prepare(esp_rom_tjpgd_dec_t *dec, esp_rom_tjpgd_input_function_t infunc, void *work, uint32_t sz_work, void *dev);
/**
* @brief Decompress the JPEG image and output it as RGB data.
* @param dec Specifies the valid decompressor object.
* @param outfunc Specifies the user defined data output function. The esp_rom_tjpgd_decomp function calls this function to output the decompressed JPEG image in RGB form.
* @param scale Specifies scaling factor N for output. The output image is descaled to 1 / 2 ^ N (N = 0 to 3).
*
* @return
* - JDR_OK Function succeeded.
* - JDR_INTR The decompression process is interrupted by output function.
* - JDR_INP An error occured in input function due to hard error or wrong stream termination.
* - JDR_PAR Parameter error. Given scale factor is invalid.
* - JDR_FMT1 Data format error. The JPEG data can be collapted.
*/
esp_rom_tjpgd_result_t esp_rom_tjpgd_decomp(esp_rom_tjpgd_dec_t *dec, esp_rom_tjpgd_output_function_t outfunc, uint8_t scale);
#ifdef __cplusplus
}
#endif