# LISA JPEG 硬件解码示例

## 功能说明

演示如何使用 LISA JPEG 组件，将实际的 600×600 baseline JPEG 图片通过芯片 JPEG 硬件解码为 RGB565。示例完成解码器初始化、PSRAM 输出缓冲区配置、单帧解码、耗时统计、结果尺寸检查和资源释放。

## 硬件连接

无需外部连接，JPEG 解码使用芯片内部 JPEG、GPDMA 和缓存资源。

## 示例内容

1. 使用 `samples/media/jpeg_turbo/jpeg_turbo_demo` 中的 `NASA-clean.jpg`，图片为 600×600 baseline JPEG，大小为 29382 字节。
2. 从 PSRAM 分配 720000 字节的 RGB565 输出缓冲区。
3. 配置硬件解码输出格式为 RGB565，缩放比例为 1:1。
4. 调用 `lisa_jpeg_decoder_init()` 初始化解码器。
5. 调用 `lisa_jpeg_decode()` 完成单帧解码，打印硬件解码耗时并检查输出尺寸。
6. 调用 `lisa_jpeg_decoder_deinit()` 释放解码器资源。

## 编译

```{eval-rst}
.. include:: /sample_build.rst
```

## 烧录

```{eval-rst}
.. include:: /sample_flash.rst
```

## 预期输出

```text
I/lisa_jpeg_sample LISA JPEG hardware decode sample
I/lisa_jpeg_sample Input JPEG: NASA-clean.jpg, 29382 bytes, expected 600 x 600
I/lisa_jpeg_sample Hardware JPEG decode time: 92006 us
I/lisa_jpeg_sample Hardware JPEG decode completed successfully
I/lisa_jpeg_sample Image dimensions: 600 x 600, first RGB565 pixel: 0x0000
```

以上耗时来自 arcs_evb 的一次实板运行，具体数值会随系统时钟和运行状态变化。自动测试以 `Hardware JPEG decode completed successfully` 作为成功判据，并通过尺寸检查确认输出为 600×600 RGB565 图像。

## 核心 API

| API | 说明 |
| --- | --- |
| `lisa_jpeg_decoder_init()` | 按输出格式、缩放比例和 DMA 通道配置初始化硬件解码器 |
| `lisa_jpeg_decode()` | 解码一帧内存中的 JPEG 数据并返回输出宽高 |
| `lisa_jpeg_decoder_deinit()` | 释放解码器内部缓冲区和 DMA 资源 |

## 关键代码

```c
lisa_jpeg_decoder_t decoder = {0};
uint16_t *rgb565_output = psram_malloc_align(32, 600 * 600 * 2);
lisa_jpeg_decode_cfg_t cfg = {
    .scale = LISA_JPEG_SCALE_NONE,
    .out_format = LISA_JPEG_PIXEL_FORMAT_RGB565,
    .gpdma_in_ch = gp_dma_ch5,
    .gpdma_out_ch = gp_dma_ch4,
    .full_frame_dma = LISA_JPEG_FULL_FRAME_DMA_ENABLE,
    .dma2d_strip_mcu_rows = 1U,
    .dma2d_ch = dma_2d_ch9,
};

ret = lisa_jpeg_decoder_init(&decoder, &cfg);
if (ret == 0) {
    uint32_t start_us = SysTick_Time();
    ret = lisa_jpeg_decode(&decoder,
                           sample_jpeg,
                           sample_jpeg_len,
                           (uint8_t *)rgb565_output,
                           600 * 600 * 2,
                           &width,
                           &height);
    uint32_t elapsed_us = SysTick_Time() - start_us;
    LOGI("Hardware JPEG decode time: %u us", elapsed_us);
    lisa_jpeg_decoder_deinit(&decoder);
}
psram_free(rgb565_output);
```

## 配置说明

```kconfig
CONFIG_LISA_JPEG=y
CONFIG_LISA_JPEG_DECODER_RGB565_ONLY=y
CONFIG_LISA_JPEG_DECODE_GPDMA_IN_CH=5
CONFIG_LISA_JPEG_DECODE_GPDMA_OUT_CH=4
CONFIG_LISA_JPEG_DECODE_DMA2D_CH=9
CONFIG_PSRAM_HEAP_SIZE=0x400000
```

## 注意事项

1. **JPEG 类型**: 当前硬件解析器支持 baseline JPEG（SOF0），不支持 progressive JPEG（SOF2）。
2. **输出容量**: RGB565 输出缓冲区容量至少为 `width * height * 2` 字节，本示例从 PSRAM 分配 720000 字节。
3. **缩放限制**: RGB565 输出仅支持 1:1 解码，不支持缩放。
4. **DMA 通道**: GPDMA 输入、输出通道必须不同，并且不能与其他外设同时占用。
5. **资源释放**: 初始化成功后，无论解码是否成功，都应调用 `lisa_jpeg_decoder_deinit()`。