# JPEG 图像编解码器

[English]

## 简介

JPEG 常用于数字图像，尤其是数码摄影图像的有损压缩。压缩程度会随图片大小和压缩质量的变化而改变。JPEG 通常能保证图像质量损失肉眼不可见，并实现 10:1 的压缩。

ESP32-S31 的 JPEG 编解码器是一种基于 JPEG 基线标准的图像编解码器，可以压缩和解压缩图像，从而降低传输图像所需的带宽或存储图像所需的空间，可以处理高分辨率的图像。但请注意，编解码器引擎不能同时作为编码器和解码器工作。

关于更多 JPEG 编解码器的硬件特性，请参考 ESP32-S31 技术参考手册中的 JPEG 编解码器 章节，了解更多详情。

## 功能概述

本文档包含以下几部分内容：

- 资源分配，包括如何正确地设置配置来分配 JPEG 资源、如何在完成工作时回收资源。

- 有限状态机，涵盖了 JPEG 的工作流程，介绍了 JPEG 驱动程序的软件流程，以及是如何使用内部资源的。

- JPEG 解码器引擎，包括 JPEG 解码器引擎的行为。介绍了如何使用解码器引擎函数为图像解码（从 jpg 格式到 raw 格式）。

- JPEG 编码器引擎，包括 JPEG 编码器引擎的行为。介绍了如何使用编码器引擎函数为图像编码（从 raw 格式到 jpg 格式）。

- 性能概述，介绍了编码器和解码器的性能。

- 不同颜色格式的像素存储布局，涵盖了 JPEG 解码器和编码器所需的颜色空间顺序。

- 线程安全性，列出了驱动程序能保证线程安全的 API。

- 电源管理，描述了影响 JPEG 驱动程序功耗的因素。

- 加密场景下的使用，介绍了在 flash/PSRAM 加密场景下如何正确使用 JPEG 编解码器。

- Kconfig 选项，列出了支持的 Kconfig 选项，可以为驱动程序带来不同的效果。

### 资源分配

#### 安装 JPEG 解码器引擎

JPEG 解码器引擎的配置需要由 `jpeg_decode_engine_cfg_t` 指定：

如果在 `jpeg_decode_engine_cfg_t` 中指定了配置，则可以调用 `jpeg_new_decoder_engine()` 来分配和初始化 JPEG 解码器引擎。如果该函数运行正确，则会返回一个 JPEG 解码器句柄。请参考以下代码：

    jpeg_decoder_handle_t decoder_engine;

    jpeg_decode_engine_cfg_t decode_eng_cfg = {
        .intr_priority = 0,
        .timeout_ms = 40,
    };

    ESP_ERROR_CHECK(jpeg_new_decoder_engine(&decode_eng_cfg, &decoder_engine));

#### 卸载 JPEG 解码器引擎

如果不再需要先前安装的 JPEG 引擎，建议通过调用 `jpeg_del_decoder_engine()` 回收资源，从而释放底层硬件。

    ESP_ERROR_CHECK(jpeg_del_decoder_engine(decoder_engine));

#### 安装 JPEG 编码器引擎

JPEG 编码器引擎的配置需要由 `jpeg_encode_engine_cfg_t` 指定。

如果在 `jpeg_encode_engine_cfg_t` 中指定了配置，则可以调用 `jpeg_new_encoder_engine()` 来分配和初始化 JPEG 编码器引擎。如果该函数运行正确，则会返回一个 JPEG 编码器句柄。请参考以下代码：

    jpeg_encoder_handle_t encoder_engine;

    jpeg_encode_engine_cfg_t encode_eng_cfg = {
        .intr_priority = 0,
        .timeout_ms = 40,
    };

    ESP_ERROR_CHECK(jpeg_new_encoder_engine(&encode_eng_cfg, &encoder_engine));

#### 卸载 JPEG 编码器引擎

如果不再需要先前安装的 JPEG 引擎，建议通过调用 `jpeg_del_encoder_engine()` 回收资源，从而释放底层硬件。

    ESP_ERROR_CHECK(jpeg_del_encoder_engine(encoder_engine));

### 有限状态机

JPEG 驱动程序对硬件资源的使用情况及其处理流程如下图所示：

JPEG 有限状态机

### JPEG 解码器引擎

通过 `jpeg_new_decoder_engine()` 安装好 JPEG 解码器驱动程序后，ESP32-S31 就可以用 `jpeg_decoder_process()` 解码 JPEG 图片。通过配置参数 `jpeg_decode_cfg_t`， `jpeg_decoder_process()` 能灵活地解码不同类型的图片：

此外，我们的 JPEG 解码器 API 提供了 helper 函数，可以帮助获取给定图像的基本信息。调用 `jpeg_decoder_get_info()`，将返回名为 `jpeg_decoder_get_info()` 的图片信息结构。如果图片的基本信息已知，则不需要调用此函数。

该驱动程序支持的格式转换如下表所示：

已压缩图像的格式 | 解压后的格式
--- | ---
YUV444 | RGB565/RGB888
YUV422 | RGB565/RGB888
YUV420 | RGB565/RGB888
GRAY | GRAY

可参考以下代码，为 1080*1920 大小的图片解码：

    jpeg_decode_cfg_t decode_cfg_rgb = {
        .output_format = JPEG_DECODE_OUT_FORMAT_RGB888,
        .rgb_order = JPEG_DEC_RGB_ELEMENT_ORDER_BGR,
    };

    size_t rx_buffer_size;

    jpeg_decode_memory_alloc_cfg_t rx_mem_cfg = {
        .buffer_direction = JPEG_DEC_ALLOC_OUTPUT_BUFFER,
    };

    const uint8_t *bit_stream = embedded_jpeg_start;
    uint8_t *out_buf = (uint8_t*)jpeg_alloc_decoder_mem(1920 * 1088 * 3, &rx_mem_cfg, &rx_buffer_size);

    jpeg_decode_picture_info_t header_info;
    ESP_ERROR_CHECK(jpeg_decoder_get_info(bit_stream, bit_stream_size, &header_info));
    uint32_t out_size = 0;
    ESP_ERROR_CHECK(jpeg_decoder_process(decoder_engine, &decode_cfg_rgb, bit_stream, bit_stream_size, out_buf, &out_size));

参考以下提示，可以更准确地使用该驱动程序：

1. 在上述代码中，应确保输出缓冲区 out_buf 满足驱动的对齐要求。可以通过 `jpeg_alloc_decoder_mem()` 函数来分配一个在大小和地址上都对齐的缓冲区。

2. 在 `jpeg_decoder_process()` 返回前， bit_stream 指向的输入内容不应有更改。该输入缓冲区既可以直接来自映射到 flash 的嵌入式数据，也可以来自其他在整个调用期间保持可读的内存区域。

3. 如果源 JPEG 使用 YUV420 或 YUV422 采样方式，解码后的输出图像尺寸可能会被补齐到 16 像素边界。例如，当可见图像大小为 1080*1920 时，解码器可能需要按 1088*1920 像素来分配输出缓冲区。这来自 JPEG 的块布局限制，因此请按补齐后的图像尺寸而不是仅按可见宽高准备足够的输出缓冲区内存。

### JPEG 编码器引擎

通过 `jpeg_new_encoder_engine()` 安装好 JPEG 编码器驱动程序后，ESP32-S31 就可以用 `jpeg_encoder_process()` 编码 JPEG 图片。借由可配置参数 `jpeg_encode_cfg_t`， `jpeg_encoder_process()` 能灵活地编码不同类型的图片：

该驱动程序支持的格式转换如下表所示：

原图格式 | 下采样法
--- | ---
RGB565/RGB888 | YUV444/YUV422/YUV420
GRAY | GRAY

可参考以下代码，将一张嵌入到固件中的 1280x720 原始图片编码为 JPEG：

    size_t raw_size_720p = EXAMPLE_WIDTH * EXAMPLE_HEIGHT * 3; /* 1280x720 bgr24 帧 */
    jpeg_encode_cfg_t enc_config = {
        .src_type = JPEG_ENCODE_IN_FORMAT_RGB888,
        .sub_sample = JPEG_DOWN_SAMPLING_YUV422,
        .image_quality = 80,
        .width = 1280,
        .height = 720,
        .pixel_reverse = false, // 是否反转输入图像的像素顺序，或像素顺序细节请参考技术参考手册
    };

    jpeg_encode_memory_alloc_cfg_t rx_mem_cfg = {
        .buffer_direction = JPEG_ENC_ALLOC_OUTPUT_BUFFER,
    };
    size_t jpg_buffer_size = 0;
    uint8_t *jpg_buf_720p = (uint8_t*)jpeg_alloc_encoder_mem(raw_size_720p / 10, &rx_mem_cfg, &jpg_buffer_size);
    if (jpg_buf_720p == NULL) {
        ESP_LOGE(TAG, "alloc jpg_buf_720p error");
        return;
    }

    /* 当前 JPEG 编码输入路径下，JPEG_ENCODE_IN_FORMAT_RGB888 实际要求
     * 原始字节按 BGR24 风格排列。只要数据在本次调用返回前保持可读，
     * 就可以直接从 flash 中映射出来的嵌入资源读取。 */
    ESP_ERROR_CHECK(jpeg_encoder_process(jpeg_handle, &enc_config, embedded_bgr24_start, raw_size_720p, jpg_buf_720p, jpg_buffer_size, &jpg_size_720p));

参考以下提示，可以更准确地使用该驱动程序：

1. 在上述代码中，应调用 `jpeg_alloc_encoder_mem()` 函数来分配 jpg_buf_720p，因为 JPEG 输出码流缓冲区需要满足驱动的对齐要求。

2. 在 `jpeg_encoder_process()` 返回前， embedded_bgr24_start 所指向的输入内容不应有更改。该输入缓冲区既可以来自嵌入到 flash 中的映射资源，也可以来自其他在整个调用期间保持可读的内存区域。

3. 对于 `JPEG_ENCODE_IN_FORMAT_RGB888`，当前驱动实际要求原始输入字节按 BGR24 风格排列。如果直接提供 RGB24 原始数据，则编码后的 JPEG 会出现红蓝通道互换。

4. 压缩比取决于所选择的 image_quality 和图像本身的内容。一般来说， image_quality 值越高，图像质量越好，相应的压缩比就越小。至于图像内容，则很难给出具体的指导方针，因此本文也就不再讨论。基准 JPEG 压缩比通常从 40:1 到 10:1 不等，请依实际情况而定。

### 性能概述

本节提供了解码器和编码器性能的一些测量数据。下表中呈现的数据是对随机选择的图片片段进行 50 次解码或编码的平均值。所有测试都在 360 MHz 的 CPU 频率以及 200 MHz 的 SPI RAM 时钟频率下进行。在此测试中，仅运行与 JPEG 相关的代码，不涉及其他模块（例如 USB 摄像头等）。

解码器和编码器都不会占用过多的 CPU，仅头部解析会消耗一定 CPU。与 JPEG 压缩相关的计算，如 DCT、量化、哈夫曼编码/解码等，完全由硬件完成。

#### JPEG 解码器性能

JPEG 高度 | JPEG 宽度 | 像素输入格式 [1] | 像素输出格式 [2] | 性能 (fps)
--- | --- | --- | --- | ---
1080 | 1920 | YUV422 | RGB888/RGB565 | 28
720 | 1280 | YUV422 | RGB888/RGB565 | 62
480 | 800 | YUV422 | RGB888/RGB565 | 138
480 | 320 | YUV422 | RGB888/RGB565 | 286
720 | 1280 | GRAY | GRAY | 96

[1]

已压缩图像格式

[2]

解压后图像格式

#### JPEG 编码器性能

JPEG 高度 | JPEG 宽度 | 像素输入格式 [3] | 像素输出格式 [4] | 性能 (fps)
--- | --- | --- | --- | ---
1080 | 1920 | RGB888 | YUV422 | 21
1080 | 1920 | RGB565 | YUV422 | 21
1080 | 1920 | RGB565 | YUV420 | 25
720 | 1280 | RGB565 | YUV420 | 62
720 | 1280 | RGB565 | YUV422 | 47
480 | 800 | RGB888 | YUV444 | 74
480 | 800 | RGB888 | YUV422 | 108
480 | 800 | RGB888 | YUV420 | 126
480 | 320 | RGB888 | YUV444 | 173
480 | 320 | RGB888 | YUV422 | 241
480 | 320 | RGB888 | YUV420 | 273
720 | 1280 | GRAY | GRAY | 92

[3]

原图格式

[4]

下采样法

### 不同颜色格式的像素存储布局

本指南中提到的编码器和解码器使用相同的未压缩原始图像格式 (RGB, YUV)。因此，本节中编码器和解码器不做单独讨论。以下格式的像素布局适用于编码器的输入方向和解码器的输出方向（如果支持）。具体的像素布局如图所示：

#### RGB888

下图中的每个小块表示一位。

RGB888 像素顺序

对于 RGB888，可以通过 `jpeg_decode_cfg_t::rgb_order` 将像素设置为 RGB 顺序。

RGB888 大端像素顺序

#### RGB565

下图中的每个小块表示一位。

RGB565 像素顺序

对于 RGB565，可以通过 `jpeg_decode_cfg_t::rgb_order` 将像素设置为 RGB 顺序。

RGB565 大端像素顺序

#### YUV444

下图中的每个小块表示一位。

YUV444 像素顺序

#### YUV422

下图中的每个小块表示一位。

YUV422 像素顺序

#### YUV420

下图中的每个小块表示一位。

YUV420 像素顺序

### 线程安全性

驱动程序能保证工厂函数 `jpeg_new_decoder_engine()`， `jpeg_decoder_get_info()`， `jpeg_decoder_process()`，以及 `jpeg_del_decoder_engine()` 是线程安全的，这意味着无需额外的锁保护，也可以从不同的 RTOS 任务中调用这些函数。

### 电源管理

当启用电源管理（即设置了 CONFIG_PM_ENABLE）时，系统需要调整或停止 JPEG 的源时钟以进入 Light-sleep 模式，这可能会改变 JPEG 解码器/编码器的处理过程，也可能会导致硬件计算出现意外。为防止以上问题出现，当 JPEG 编码器/解码器工作时，无法进入 Light-sleep 模式。

每当用户通过 JPEG 进行解码或编码（即调用 `jpeg_encoder_process()` 或 `jpeg_decoder_process()`）时，驱动程序会将电源管理设定为 `esp_pm_lock_type_t::ESP_PM_CPU_FREQ_MAX`，确保获取电源管理锁。一旦编码或解码完成，驱动程序将释放锁，则系统可以进入 Light-sleep 模式。

### 加密场景下的使用

JPEG 编解码器通过 2D-DMA 搬运数据，而 JPEG 编解码器 无法处理已加密的数据。因此在开启 PSRAM 加密时，需要让 JPEG 的输入/输出缓冲区位于非加密的内存区域，否则编解码会失败。

为支持加密场景，驱动程序做了如下处理：

- 当启用 `CONFIG_SPIRAM_ENC_EXEMPT` 时， `jpeg_alloc_decoder_mem()` 和 `jpeg_alloc_encoder_mem()` 会自动从非加密 PSRAM 区域（`MALLOC_CAP_SPIRAM_NO_ENC`）分配缓冲区。

- 分配的缓冲区会同时满足 cache 行对齐与 2D-DMA 的字节对齐要求。

使用时请注意：

1. 建议始终通过 `jpeg_alloc_encoder_mem()` / `jpeg_alloc_decoder_mem()` 分配缓冲区，以保证对齐与内存区域正确。

2. 非加密区的大小由 `CONFIG_SPIRAM_ENC_EXEMPT_SIZE` 决定。由于 JPEG 缓冲区大小取决于图像分辨率，无法自动预测，需根据实际处理的最大图像自行配置。若该区域不足，分配会失败并打印错误日志，提示增大 `CONFIG_SPIRAM_ENC_EXEMPT_SIZE`；同时注意该值不能大于等于实际 PSRAM 容量，否则非加密区会被禁用。

### Kconfig 选项

- CONFIG_JPEG_ENABLE_DEBUG_LOG 可启用调试日志，但会增加固件二进制大小。

## 维护者须知

驱动程序对硬件资源的使用情况及其依赖状况如下图所示：

JPEG 驱动程序文件结构

## 应用程序示例

- peripherals/jpeg/jpeg_decode 演示了如何使用 JPEG 硬件解码器解析一张嵌入式 JPEG，将其解码为 RGB888，通过 UART 输出 base64 原始结果，并使用 pytest 做回归校验。

- peripherals/jpeg/jpeg_encode 演示了如何使用 JPEG 硬件编码器对一张嵌入式 720p 原始图像进行编码，并通过 UART 输出 base64 JPEG，再用 pytest 做结果校验。

## API 参考

### Header File

- components/esp_driver_jpeg/include/driver/jpeg_decode.h

- This header file can be included with:

  >     #include "driver/jpeg_decode.h"

- This header file is a part of the API provided by the `esp_driver_jpeg` component. To declare that your component depends on `esp_driver_jpeg`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_jpeg

  > or

  >     PRIV_REQUIRES esp_driver_jpeg

### Functions

esp_err_t jpeg_new_decoder_engine(const jpeg_decode_engine_cfg_t *dec_eng_cfg, jpeg_decoder_handle_t *ret_decoder)

  Acquire a JPEG decode engine with the specified configuration.

  This function acquires a JPEG decode engine with the specified configuration. The configuration parameters are provided through the `dec_eng_cfg` structure, and the resulting JPEG decoder handle is returned through the `ret_decoder` pointer.

  参数:

    - dec_eng_cfg -- [in] Pointer to the JPEG decode engine configuration.

    - ret_decoder -- [out] Pointer to a variable that will receive the JPEG decoder handle.

  返回:

    - ESP_OK: JPEG decoder initialized successfully.

    - ESP_ERR_INVALID_ARG: JPEG decoder initialization failed because of invalid argument.

    - ESP_ERR_NO_MEM: Create JPEG decoder failed because of out of memory.

esp_err_t jpeg_decoder_get_info(const uint8_t *bit_stream, uint32_t stream_size, jpeg_decode_picture_info_t *picture_info)

  Helper function for getting information about a JPEG image.

  This function analyzes the provided JPEG image data and retrieves information about the image, such as its width, height. The image data is specified by the `bit_stream` pointer and the `stream_size` parameter. The resulting image information is returned through the `picture_info` structure.

  备注

  This function doesn't depend on any jpeg hardware, it helps user to know jpeg information from jpeg header. For example, user can get picture width and height via this function and malloc a reasonable size buffer for jpeg engine process.

  参数:

    - bit_stream -- [in] Pointer to the buffer containing the JPEG image data.

    - stream_size -- [in] Size of the JPEG image data in bytes. Note that parse beginning partial of picture also works, but the beginning partial should be enough given.

    - picture_info -- [out] Pointer to the structure that will receive the image information.

  返回:

    - ESP_OK: JPEG decoder get jpg image header successfully.

    - ESP_ERR_INVALID_ARG: JPEG decoder get header info failed because of invalid argument.

esp_err_t jpeg_decoder_process(jpeg_decoder_handle_t decoder_engine, const jpeg_decode_cfg_t *decode_cfg, const uint8_t *bit_stream, uint32_t stream_size, uint8_t *decode_outbuf, uint32_t outbuf_size, uint32_t *out_size)

  Process a JPEG image with the specified decoder instance.

  This function processes the provided JPEG image data using the specified JPEG decoder instance. The input JPEG image data is specified by the `bit_stream` pointer and the `stream_size` parameter. The resulting decoded image data is written to the `decode_outbuf` buffer, and the length of the output image data is returned through the `out_size` pointer.

  备注

  1.Please make sure that the content of `bit_stream` pointer cannot be modified until this function returns. 2.For JPEGs encoded with YUV420 or YUV422 sampling, the decoded output dimensions can be padded to 16-pixel boundaries by the JPEG block layout. Make sure `decode_outbuf` is large enough for that padded output size, not only for the visible width and height.

  参数:

    - decoder_engine -- [in] Handle of the JPEG decoder instance to use for processing.

    - decode_cfg -- [in] Config structure of decoder.

    - bit_stream -- [in] Pointer to the buffer containing the input JPEG image data.

    - stream_size -- [in] Size of the input JPEG image data in bytes.

    - decode_outbuf -- [in] Pointer to the buffer that will receive the decoded image data.

    - outbuf_size -- [in] The size of `decode_outbuf`

    - out_size -- [out] Pointer to a variable that will receive the length of the output image data.

  返回:

    - ESP_OK: JPEG decoder process successfully.

    - ESP_ERR_INVALID_ARG: JPEG decoder process failed because of invalid argument.

esp_err_t jpeg_del_decoder_engine(jpeg_decoder_handle_t decoder_engine)

  Release resources used by a JPEG decoder instance.

  This function releases the resources used by the specified JPEG decoder instance. The decoder instance is specified by the `decoder_engine` parameter.

  参数:

    decoder_engine -- Handle of the JPEG decoder instance to release resources for.

  返回:

    - ESP_OK: Delete JPEG decoder successfully.

    - ESP_ERR_INVALID_ARG: Delete JPEG decoder failed because of invalid argument.

void *jpeg_alloc_decoder_mem(size_t size, const jpeg_decode_memory_alloc_cfg_t *mem_cfg, size_t *allocated_size)

  A helper function to allocate memory space for JPEG decoder.

  参数:

    - size -- [in] The size of memory to allocate.

    - mem_cfg -- [in] Memory configuration for memory allocation

    - allocated_size -- [out] Actual allocated buffer size.

  返回:

    Pointer to the allocated memory space, or NULL if allocation fails.

### Structures

struct jpeg_decode_cfg_t

  Configuration parameters for a JPEG decoder image process.

  Public Members

  jpeg_dec_output_format_t output_format

    JPEG decoder output format

  jpeg_dec_rgb_element_order_t rgb_order

    JPEG decoder output order

  jpeg_yuv_rgb_conv_std_t conv_std

    JPEG decoder yuv->rgb standard

struct jpeg_decode_engine_cfg_t

  Configuration parameters for the JPEG decoder engine.

  Public Members

  int intr_priority

    JPEG interrupt priority, if set to 0, driver will select the default priority (1,2,3).

  int timeout_ms

    JPEG timeout threshold for handling a picture, should larger than valid decode time in ms. For example, for 30fps decode, this value must larger than 34. -1 means wait forever

  uint32_t allow_pd

    If set, the driver will backup/restore the JPEG registers before/after entering/exist sleep mode. By this approach, the system can power off JPEG's power domain. This can save power, but at the expense of more RAM being consumed

  struct jpeg_decode_engine_cfg_t flags

    JPEG engine configuration flags

struct jpeg_decode_picture_info_t

  Structure for jpeg decode header.

  Public Members

  uint32_t width

    Number of pixels in the horizontal direction

  uint32_t height

    Number of pixels in the vertical direction

  jpeg_down_sampling_type_t sample_method

    compressed JPEG picture sampling method

struct jpeg_decode_memory_alloc_cfg_t

  JPEG decoder memory allocation config.

  Public Members

  jpeg_dec_buffer_alloc_direction_t buffer_direction

    Buffer direction for jpeg decoder memory allocation

### Header File

- components/esp_driver_jpeg/include/driver/jpeg_encode.h

- This header file can be included with:

  >     #include "driver/jpeg_encode.h"

- This header file is a part of the API provided by the `esp_driver_jpeg` component. To declare that your component depends on `esp_driver_jpeg`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_jpeg

  > or

  >     PRIV_REQUIRES esp_driver_jpeg

### Functions

esp_err_t jpeg_new_encoder_engine(const jpeg_encode_engine_cfg_t *enc_eng_cfg, jpeg_encoder_handle_t *ret_encoder)

  Allocate JPEG encoder.

  参数:

    - enc_eng_cfg -- [in] config for jpeg encoder

    - ret_encoder -- [out] handle for jpeg encoder

  返回:

    - ESP_OK: JPEG encoder initialized successfully.

    - ESP_ERR_INVALID_ARG: JPEG encoder initialization failed because of invalid argument.

    - ESP_ERR_NO_MEM: Create JPEG encoder failed because of out of memory.

esp_err_t jpeg_encoder_process(jpeg_encoder_handle_t encoder_engine, const jpeg_encode_cfg_t *encode_cfg, const uint8_t *encode_inbuf, uint32_t inbuf_size, uint8_t *encode_outbuf, uint32_t outbuf_size, uint32_t *out_size)

  Process encoding of JPEG data using the specified encoder engine.

  This function processes the encoding of JPEG data using the provided encoder engine and configuration. It takes an input buffer containing the raw image data, performs encoding based on the configuration settings, and outputs the compressed bitstream.

  参数:

    - encoder_engine -- [in] Handle to the JPEG encoder engine to be used for encoding.

    - encode_cfg -- [in] Pointer to the configuration structure for the JPEG encoding process.

    - encode_inbuf -- [in] Pointer to the input buffer containing the raw image data.

    - inbuf_size -- [in] Size of the input buffer in bytes.

    - encode_outbuf -- [in] Pointer to the output buffer where the compressed bitstream will be stored.

    - outbuf_size -- [in] The size of output buffer.

    - out_size -- [out] Pointer to a variable where the size of the output bitstream will be stored.

  返回:

    - ESP_OK: JPEG encoder process successfully.

    - ESP_ERR_INVALID_ARG: JPEG encoder process failed because of invalid argument.

    - ESP_ERR_TIMEOUT: JPEG encoder process timeout.

esp_err_t jpeg_del_encoder_engine(jpeg_encoder_handle_t encoder_engine)

  Release resources used by a JPEG encoder instance.

  This function releases the resources used by the specified JPEG encoder instance. The encoder instance is specified by the `encoder_engine` parameter.

  参数:

    encoder_engine -- [in] Handle of the JPEG encoder instance to release resources for.

  返回:

    - ESP_OK: Delete JPEG encoder successfully.

    - ESP_ERR_INVALID_ARG: Delete JPEG encoder failed because of invalid argument.

void *jpeg_alloc_encoder_mem(size_t size, const jpeg_encode_memory_alloc_cfg_t *mem_cfg, size_t *allocated_size)

  A helper function to allocate memory space for JPEG encoder.

  参数:

    - size -- [in] The size of memory to allocate.

    - mem_cfg -- [in] Memory configuration for memory allocation

    - allocated_size -- [out] Actual allocated buffer size.

  返回:

    Pointer to the allocated memory space, or NULL if allocation fails.

### Structures

struct jpeg_encode_cfg_t

  JPEG encoder configure structure.

  Public Members

  uint32_t height

    Number of pixels in the horizontal direction

  uint32_t width

    Number of pixels in the vertical direction

  jpeg_enc_input_format_t src_type

    Source type of raw image to be encoded, see `jpeg_enc_src_type_t`

  jpeg_down_sampling_type_t sub_sample

    JPEG subsampling method

  uint32_t image_quality

    JPEG compressing quality, value from 1-100, higher value means higher quality

  bool pixel_reverse

    Whether to reverse the input pixel order, for detailed pixel order please refer to TRM

struct jpeg_encode_engine_cfg_t

  Configuration parameters for the JPEG encode engine.

  Public Members

  int intr_priority

    JPEG interrupt priority, if set to 0, driver will select the default priority (1,2,3).

  int timeout_ms

    JPEG timeout threshold for handling a picture, should larger than valid encode time in ms. For example, for 30fps encode, this value must larger than 34. -1 means wait forever

  uint32_t allow_pd

    If set, the driver will backup/restore the JPEG registers before/after entering/exist sleep mode. By this approach, the system can power off JPEG's power domain. This can save power, but at the expense of more RAM being consumed

  struct jpeg_encode_engine_cfg_t flags

    JPEG engine configuration flags

struct jpeg_encode_memory_alloc_cfg_t

  JPEG encoder memory allocation config.

  Public Members

  jpeg_enc_buffer_alloc_direction_t buffer_direction

    Buffer direction for jpeg encoder memory allocation

### Header File

- components/esp_driver_jpeg/include/driver/jpeg_types.h

- This header file can be included with:

  >     #include "driver/jpeg_types.h"

- This header file is a part of the API provided by the `esp_driver_jpeg` component. To declare that your component depends on `esp_driver_jpeg`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_jpeg

  > or

  >     PRIV_REQUIRES esp_driver_jpeg

### Type Definitions

typedef struct jpeg_decoder_t *jpeg_decoder_handle_t

  Type of jpeg decoder handle.

typedef struct jpeg_encoder_t *jpeg_encoder_handle_t

  Type of jpeg encoder handle.

### Enumerations

enum jpeg_dec_output_format_t

  Enumeration for jpeg output format.

  Values:

  enumerator JPEG_DECODE_OUT_FORMAT_RGB888

    output RGB888 format

  enumerator JPEG_DECODE_OUT_FORMAT_RGB565

    output RGB565 format

  enumerator JPEG_DECODE_OUT_FORMAT_GRAY

    output the gray picture

  enumerator JPEG_DECODE_OUT_FORMAT_YUV444

    output yuv444 format

  enumerator JPEG_DECODE_OUT_FORMAT_YUV422

    output yuv422 format

  enumerator JPEG_DECODE_OUT_FORMAT_YUV420

    output yuv420 format

enum jpeg_yuv_rgb_conv_std_t

  Enumeration for YUV and RGB conversion standard.

  Values:

  enumerator JPEG_YUV_RGB_CONV_STD_BT601

    BT601

  enumerator JPEG_YUV_RGB_CONV_STD_BT709

    BT709

enum jpeg_dec_rgb_element_order_t

  Enumeration for jpeg big/small endian output.

  Values:

  enumerator JPEG_DEC_RGB_ELEMENT_ORDER_BGR

    Output the color component in small endian

  enumerator JPEG_DEC_RGB_ELEMENT_ORDER_RGB

    Output the color component in big endian

enum jpeg_dec_buffer_alloc_direction_t

  Enumeration for jpeg decoder alloc buffer direction.

  Values:

  enumerator JPEG_DEC_ALLOC_INPUT_BUFFER

    Alloc the picture input buffer, (compressed format in decoder)

  enumerator JPEG_DEC_ALLOC_OUTPUT_BUFFER

    Alloc the picture output buffer, (decompressed format in decoder)

enum jpeg_enc_input_format_t

  Enumeration for jpeg input format.

  Values:

  enumerator JPEG_ENCODE_IN_FORMAT_RGB888

    input RGB888 format

  enumerator JPEG_ENCODE_IN_FORMAT_RGB565

    input RGB565 format

  enumerator JPEG_ENCODE_IN_FORMAT_GRAY

    input GRAY format

  enumerator JPEG_ENCODE_IN_FORMAT_YUV422

    input YUV422 format

  enumerator JPEG_ENCODE_IN_FORMAT_YUV444

    input YUV444 format

  enumerator JPEG_ENCODE_IN_FORMAT_YUV420

    input YUV420 format

enum jpeg_enc_buffer_alloc_direction_t

  Enumeration for jpeg encoder alloc buffer direction.

  Values:

  enumerator JPEG_ENC_ALLOC_INPUT_BUFFER

    Alloc the picture input buffer, (decompressed format in encoder)

  enumerator JPEG_ENC_ALLOC_OUTPUT_BUFFER

    Alloc the picture output buffer, (compressed format in encoder)

### Header File

- components/esp_hal_jpeg/include/hal/jpeg_types.h

- This header file can be included with:

  >     #include "hal/jpeg_types.h"

- This header file is a part of the API provided by the `esp_hal_jpeg` component. To declare that your component depends on `esp_hal_jpeg`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_hal_jpeg

  > or

  >     PRIV_REQUIRES esp_hal_jpeg

### Unions

union jpeg_huffman_table_info_t
  #include <jpeg_types.h>

  Structure for huffman information.

  Public Members

  uint8_t id

    Huffman table id.

  uint8_t type

    Huffman table type.

  struct jpeg_huffman_table_info_t
  uint8_t info

    Information of huffman table.

### Structures

struct jpeg_component_factor_t

  Structure for recording factor of component.

  Public Members

  uint32_t horizontal

    horizontal factor

  uint32_t vertical

    vertical factor

### Macros

JPEG_HUFFMAN_BITS_LEN_TABLE_LEN

JPEG_HUFFMAN_AC_VALUE_TABLE_LEN

JPEG_HUFFMAN_DC_VALUE_TABLE_LEN

JPEG_QUANTIZATION_TABLE_LEN

JPEG_COMPONENT_NUMBER_MAX

DHT_TC_NUM

DHT_TH_NUM

JPEG_DOWN_SAMPLING_NUM

### Enumerations

enum jpeg_codec_mode_t

  Enum for JPEG codec working mode.

  Values:

  enumerator JPEG_CODEC_ENCODER

    Encode mode.

  enumerator JPEG_CODEC_DECODER

    Decode mode.

enum jpeg_sample_mode_t

  Enum for JPEG sampling mode.

  Values:

  enumerator JPEG_SAMPLE_MODE_YUV444

    sample in YUV444

  enumerator JPEG_SAMPLE_MODE_YUV422

    sample in YUV422

  enumerator JPEG_SAMPLE_MODE_YUV420

    sample in YUV420

enum jpeg_down_sampling_type_t

  Enumeration for jpeg decoder sample methods.

  Values:

  enumerator JPEG_DOWN_SAMPLING_YUV444

    Sample by YUV444

  enumerator JPEG_DOWN_SAMPLING_YUV422

    Sample by YUV422

  enumerator JPEG_DOWN_SAMPLING_YUV420

    Sample by YUV420

  enumerator JPEG_DOWN_SAMPLING_GRAY

    Sample the gray picture

enum jpeg_enc_src_type_t

  JPEG encoder source formats.

  Values:

  enumerator JPEG_ENC_SRC_RGB888

    JPEG encoder source RGB888

  enumerator JPEG_ENC_SRC_YUV422

    JPEG encoder source YUV422

  enumerator JPEG_ENC_SRC_RGB565

    JPEG encoder source RGB565

  enumerator JPEG_ENC_SRC_YUV444

    JPEG encoder source YUV444

  enumerator JPEG_ENC_SRC_YUV420

    JPEG encoder source YUV420

  enumerator JPEG_ENC_SRC_GRAY

    JPEG encoder source GRAY

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。