From 7fa05cee81baa909de2ffc191434c393a55fc5c6 Mon Sep 17 00:00:00 2001 From: Song Ruo Jing Date: Fri, 17 Oct 2025 19:10:48 +0800 Subject: [PATCH] docs(ppa): add a note about bilinear scaling algorithm in PPA SRM Closes https://github.com/espressif/esp-idf/issues/17531 --- docs/en/api-reference/peripherals/ppa.rst | 4 + docs/zh_CN/api-reference/peripherals/ppa.rst | 157 ++++++++++++++++++- 2 files changed, 160 insertions(+), 1 deletion(-) diff --git a/docs/en/api-reference/peripherals/ppa.rst b/docs/en/api-reference/peripherals/ppa.rst index e108558839..b17a844b19 100644 --- a/docs/en/api-reference/peripherals/ppa.rst +++ b/docs/en/api-reference/peripherals/ppa.rst @@ -92,6 +92,10 @@ Some notes to avoid confusion in configuring :cpp:type:`ppa_srm_oper_config_t`: - Output block's width/height is totally determined by the input block's width/height, scaling factor, and rotation angle, so output block's width/height does not need to be configured. However, please make sure the output block can fit at the offset location in the output picture. - If the color mode of the input or output picture is ``PPA_SRM_COLOR_MODE_YUV420``, then its ``pic_w``, ``pic_h``, ``block_w``, ``block_h``, ``block_offset_x``, ``block_offset_y`` fields must be even. +.. note:: + + The PPA SRM internally uses bilinear scaling algorithm to process. Therefore, it may cause chromatic aberration and loss of contrast at the edges in a scaled picture. + Blend ~~~~~ diff --git a/docs/zh_CN/api-reference/peripherals/ppa.rst b/docs/zh_CN/api-reference/peripherals/ppa.rst index 80c3ffb369..e2d5b23ceb 100644 --- a/docs/zh_CN/api-reference/peripherals/ppa.rst +++ b/docs/zh_CN/api-reference/peripherals/ppa.rst @@ -1 +1,156 @@ -.. include:: ../../../en/api-reference/peripherals/ppa.rst +像素处理加速器 (PPA) +==================== + +简介 +---- + +{IDF_TARGET_NAME} 含有像素处理加速器 (PPA) 模块，用于实现图像旋转、缩放、镜像和叠加等图像算法的硬件加速。 + +术语表 +------ + +与 PPA 驱动程序相关的术语可参见下表及下图。 + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - 术语 + - 定义 + * - 图片 (pic) + - 存储在系统内存中的完整图像。 + * - 块 + - 从图片中裁剪出的一部分，其最大尺寸等于整个图片。 + * - 像素 + - 在 PPA 环境中使用的单位。 + * - PPA 操作 + - 图像算法加速的类型，包括缩放-旋转-镜像 (SRM)、叠加和填充。 + * - PPA 客户端 + - 执行 PPA 操作的主体。通常，每个 PPA 客户端由特定任务持有。 + * - PPA 事务 + - 来自 PPA 客户端的一次 PPA 操作请求即为一次 PPA 事务。 + +.. figure:: ../../../_static/diagrams/ppa/pic_blk_concept.png + :align: center + :alt: PPA 图片/块术语 + + PPA 图片/块术语 + +功能概述 +-------- + +以下部分详细介绍了 PPA 驱动程序的设计： + +- :ref:`ppa-client-registration` - 涵盖如何注册 PPA 客户端来执行一切 PPA 操作。 +- :ref:`ppa-register-callback` - 涵盖如何将用户特定代码挂接到 PPA 驱动程序事件回调函数。 +- :ref:`ppa-perform-operation` - 涵盖如何执行 PPA 操作。 +- :ref:`ppa-thread-safety`- 涵盖在线程安全方面使用 PPA 操作 API 的情况。 +- :ref:`ppa-performance-overview` - 涵盖 PPA 操作的性能。 + +.. _ppa-client-registration: + +注册 PPA 客户端 +^^^^^^^^^^^^^^^ + +执行 PPA 操作的请求由 PPA 客户端发出。因此，在进行 PPA 操作之前应先注册 PPA 客户端。调用 :cpp:func:`ppa_register_client` 函数注册一个新客户端。使用 :cpp:type:`ppa_client_config_t` 结构体来指定客户端的属性。 + +- :cpp:member:`ppa_client_config_t::oper_type` - 每种 PPA 操作类型对应一个 PPA 客户端类型，已注册的 PPA 客户端只能请求一种特定类型的 PPA 操作。 +- :cpp:member:`ppa_client_config_t::max_pending_trans_num` - 决定客户端可以持有的最大 PPA 事务挂起数量。 + +建议为每个任务注册一个独立的 PPA 客户端。例如，一个应用程序包含两个任务：任务 A 需要使用 PPA SRM 和 PPA 填充功能，则应在该任务中注册一个 PPA SRM 客户端和一个 PPA 填充客户端；而任务 B 也需要使用 PPA SRM 功能，那么在任务 B 中应再注册一个 PPA SRM 客户端。 + +如果任务不再需要执行 PPA 操作，可以调用 :cpp:func:`ppa_unregister_client` 函数注销相应的 PPA 客户端。 + +.. _ppa-register-callback: + +注册 PPA 事件回调函数 +^^^^^^^^^^^^^^^^^^^^^ + +当某个事件发生时（例如，完成一个 PPA 事务时），CPU 会通过中断接收到该事件的通知。如果需要在特定事件发生时调用某些特定函数，可以通过调用 :cpp:func:`ppa_client_register_event_callbacks` 为该事件注册回调函数。这在选择 ``PPA_TRANS_MODE_NON_BLOCKING`` 模式来执行 PPA 操作时特别有用。需要注意的是，虽然事件回调函数与 PPA 客户端绑定，但用户上下文是在调用 PPA 操作 API 时按事务提供的，这使事件回调函数能被更灵活得运用。 + +已注册的回调函数在中断上下文中被调用，因此，要遵循中断服务程序 (ISR) 的一般规则。 + +.. _ppa-perform-operation: + +执行 PPA 操作 +^^^^^^^^^^^^^ + +注册好 PPA 客户端，就可以用返回的 :cpp:type:`ppa_client_handle_t` 来请求执行 PPA 操作。 + +PPA 操作包括： + +缩放、旋转、镜像 (SRM) +~~~~~~~~~~~~~~~~~~~~~~ + +调用 :cpp:func:`ppa_do_scale_rotate_mirror` 对图片内部的目标块执行缩放、旋转、镜像中的一个或多个操作。 + +注意以下几点事项，避免在配置 :cpp:type:`ppa_srm_oper_config_t` 时产生混淆： + +.. list:: + + - 执行 SRM 操作时，:cpp:member:`ppa_in_pic_blk_config_t::buffer` 和 :cpp:member:`ppa_out_pic_blk_config_t::buffer` 必须是指向不同图片 buffer 的指针。 + - :cpp:member:`ppa_srm_oper_config_t::scale_x` 和 :cpp:member:`ppa_srm_oper_config_t::scale_y` 的精度将被截断为 1/16 的步长。 + - 输出块的宽度/高度完全由输入块的宽度/高度、缩放因子和旋转角度决定，因此无需配置输出块的宽度/高度。但请确保输出块可以适应输出图片中的偏移位置。 + - 如果输入或输出图片的色彩模式为 ``PPA_SRM_COLOR_MODE_YUV420``，那么其 ``pic_w``、``pic_h``、``block_w``、``block_h``、``block_offset_x`` 以及 ``block_offset_y`` 字段必须为偶数。 + +.. note:: + + PPA SRM 内部使用双线性缩放算法进行处理。因此，缩放后的图片边缘可能会出现色差和对比度损失。 + +叠加 +~~~~ + +调用 :cpp:func:`ppa_do_blend` 将前景 (FG) 和背景 (BG) 图片的两个目标块进行叠加。 + +叠加遵循一般的 Alpha Blending 公式： + +:math:`A_{out} = A_b + A_f - A_b \times A_f` + +:math:`C_{out} = (C_b \times A_b \times (1 - A_f) + C_f \times A_f) / (A_b + A_f - A_b \times A_f)` + +其中 :math:`A_b` 是背景层的 Alpha 通道，:math:`A_f` 是前景层的 Alpha 通道，:math:`C_b` 对应背景层的 R、G、B 分量，:math:`C_f` 对应前景层的 R、G、B 分量。 + +注意，此公式对 FG 和 BG 的处理是不对称的。当 :math:`A_f = 1` 时， :math:`C_{out} = C_f`，:math:`A_{out} = 1`，这意味着如果 FG 图片的色彩模式为 ``PPA_BLEND_COLOR_MODE_RGB565`` 或 ``PPA_BLEND_COLOR_MODE_RGB888``，PPA 硬件会填充 Alpha 值为 255（即 :math:`A_f = 1`），叠加结果将与 FG 块相同。 + +如果将 :cpp:member:`ppa_blend_oper_config_t::bg_ck_en` 或 :cpp:member:`ppa_blend_oper_config_t::fg_ck_en` 设置为 ``true``，则色键（color-key，也叫 Chroma-key）范围内的像素不会按照正常 Alpha Blending 流程输出。请查看 **{IDF_TARGET_NAME} 技术参考手册** > **像素处理加速器 (PPA)** > **功能描述** > **图层叠加 (BLEND)** [`PDF <{IDF_TARGET_TRM_EN_URL}#ppa>`__] 了解详细规则。 + +注意以下几点事项，避免在配置 :cpp:type:`ppa_blend_oper_config_t` 时产生混淆： + +.. list:: + + - 执行叠加操作时，:cpp:member:`ppa_out_pic_blk_config_t::buffer` 与输入的 :cpp:member:`ppa_in_pic_blk_config_t::buffer` 之一可以是指向相同图片 buffer 的指针。 + - FG 和 BG 的块宽度/高度应相同，输出块的宽度/高度值应与之一致。 + - 如果输入图片的色彩模式为 ``PPA_BLEND_COLOR_MODE_A4``，那么其 ``block_w`` 和 ``block_offset_x`` 字段必须为偶数。 + +填充 +~~~~ + +调用 :cpp:func:`ppa_do_fill` 填充图片内部的目标块。 + +:cpp:type:`ppa_trans_mode_t` 为可配置字段，适用于所有 PPA 操作 API。可以配置该字段，在调用 PPA 操作 API 时等待操作完成后再返回，或者在事务推送到内部队列后立即返回。 + +.. _ppa-thread-safety: + +线程安全 +^^^^^^^^^ + +在以下情境中调用 PPA 操作 API，PPA 驱动程序可确保线程安全： + +.. list:: + + - 同一任务中不同类型的客户端之间 + - 不同任务中同一类型的客户端之间 + - 不同任务中不同类型的客户端之间 + +.. _ppa-performance-overview: + +性能概述 +^^^^^^^^^ + +PPA 操作作用于输入图片的目标块。因此，完成一次 PPA 事务所需的时间与块中的数据量成正比。整个图片的大小对性能没有影响。更重要的是，如果图片位于 PSRAM，则 PPA 的性能高度依赖于 PSRAM 的带宽。若有多个外设同时读写 PSRAM，则 PPA 操作的性能将大大降低。 + +API 参考 +-------- + +.. include-build-file:: inc/ppa.inc +.. include-build-file:: inc/ppa_types.inc