[PATCH 4/4] Documentation/gpu/amdgpu/amdgpu_dm: add DM docs for pixel blend mode

Wed Jul 20 22:56:44 UTC 2022

On 07/17, Tales Lelo da Aparecida wrote:
> On 16/07/2022 19:25, Melissa Wen wrote:
> > AMD GPU display manager (DM) maps DRM pixel blend modes (None,
> > Pre-multiplied, Coverage) to MPC hw blocks through blend configuration
> > options. Describe relevant elements and how to set and test them to get
> > the expected DRM blend mode on DCN hw.
> > 
> > Signed-off-by: Melissa Wen <mwen at igalia.com>
> > ---
> >   .../gpu/amdgpu/display/display-manager.rst    | 98 +++++++++++++++++++
> >   Documentation/gpu/drm-kms.rst                 |  2 +
> >   2 files changed, 100 insertions(+)
> > 
> > diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst
> > index 8960a5f1fa66..7a495ed1f69e 100644
> > --- a/Documentation/gpu/amdgpu/display/display-manager.rst
> > +++ b/Documentation/gpu/amdgpu/display/display-manager.rst
> > @@ -84,3 +84,101 @@ families below.
> >   **DCN 3.0 family color caps and mapping**
> >   .. kernel-figure:: dcn3_cm_drm_current.svg
> > +
> > +Blend Mode Properties
> > +=====================
> > +
> > +Pixel blend mode is a DRM plane composition property of :c:type:`drm_plane` used to
> > +describes how pixels from a foreground plane (fg) are composited with the
> > +background plane (bg). Here, we present main concepts of DRM blend mode to help
> > +to understand how this property is mapped to AMD DC interface. See more about
> > +this DRM property and the alpha blending equations in :ref:`DRM Plane
> > +Composition Properties <plane_composition_properties>`.
> > +
> > +Basically, a blend mode sets the alpha blending equation for plane
> > +composition that fits the mode in which the alpha channel affects the state of
> > +pixel color values and, therefore, the resulted pixel color. For
> > +example, consider the following elements of the alpha blending equation:
> > +
> > +- *fg.rgb*: Each of the RGB component values from the foreground's pixel.
> > +- *fg.alpha*: Alpha component value from the foreground's pixel.
> > +- *bg.rgb*: Each of the RGB component values from the background.
> > +- *plane_alpha*: Plane alpha value set by the **plane "alpha" property**, see
> > +  more in `DRM Plane Composition Properties <plane_composition_properties>`.
> 
> You forgot to use :ref: in here.
> 
> > +
> > +in the basic alpha blending equation::
> > +
> > +   out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb
> > +
> > +the alpha channel value of each pixel in a plane is ignored and only the plane
> > +alpha affects the resulted pixel color values.
> > +
> > +DRM has three blend mode to define the blend formula in the plane composition:
> > +
> > +* **None**: Blend formula that ignores the pixel alpha.
> > +
> > +* **Pre-multiplied**: Blend formula that assumes the pixel color values in a
> > +  plane was already pre-multiplied by its own alpha channel before storage.
> > +
> > +* **Coverage**: Blend formula that assumes the pixel color values were not
> > +  pre-multiplied with the alpha channel values.
> > +
> > +and pre-multiplied is the default pixel blend mode, that means, when no blend
> > +mode property is created or defined, DRM considers the plane's pixels has
> > +pre-multiplied color values. On IGT GPU tools, the kms_plane_alpha_blend test
> > +provides a set of subtests to verify plane alpha and blend mode properties.
> > +
> > +The DRM blend mode and its elements are then mapped by AMDGPU display manager
> > +(DM) to program the blending configuration of the Multiple Pipe/Plane Combined
> > +(MPC), as follows:
> > +
> > +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
> > +   :doc: mpc-overview
> > +
> > +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
> > +   :functions: mpcc_blnd_cfg
> > +
> > +Therefore, the blending configuration for a single MPCC instance on the MPC
> > +tree is defined by :c:type:`mpcc_blnd_cfg`, where
> > +:c:type:`pre_multiplied_alpha` is the alpha pre-multiplied mode flag used to
> > +set :c:type:`MPCC_ALPHA_MULTIPLIED_MODE`. It controls whether alpha is
> > +multiplied (true/false), being only true for DRM pre-multiplied blend mode.
> > +:c:type:`mpcc_alpha_blend_mode` defines the alpha blend mode regarding pixel
> > +alpha and plane alpha values. It sets one of the three modes for
> > +:c:type:`MPCC_ALPHA_BLND_MODE`, as described below.
> > +
> > +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
> > +   :functions: mpcc_alpha_blend_mode
> > +
> > +DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM
> > +blend formula, as follows:
> > +
> > +* *MPC pixel alpha* matches *DRM fg.alpha* as the alpha component value
> > +  from the plane's pixel
> > +* *MPC global alpha* matches *DRM plane_alpha* when the pixel alpha should
> > +  be ignored and, therefore, pixel values are not pre-multiplied
> > +* *MPC global gain* assumes *MPC global alpha* value when both *DRM
> > +  fg.alpha* and *DRM plane_alpha* participate in the blend equation
> > +
> > +In short, *fg.alpha* is ignored by selecting
> > +:c:type:`MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA`. On the other hand, (plane_alpha *
> > +fg.alpha) component becomes available by selecting
> > +:c:type:`MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN`. And the
> > +:c:type:`MPCC_ALPHA_MULTIPLIED_MODE` defines if the pixel color values are
> > +pre-multiplied by alpha or not.
> > +
> > +Blend configuration flow
> > +------------------------
> > +
> > +The alpha blending equation is configured from DRM to DC interface by the
> > +following path:
> > +
> > +1. When updating a :c:type:`drm_plane_state <drm_plane_state>`, DM calls
> > +   :c:type:`fill_blending_from_plane_state()` that maps
> > +   :c:type:`drm_plane_state <drm_plane_state>` attributes to
> > +   :c:type:`dc_plane_info <dc_plane_info>` struct to be handled in the
> > +   OS-agnostic component (DC).
> > +
> > +2. On DC interface, :c:type:`struct mpcc_blnd_cfg <mpcc_blnd_cfg>` programs the
> > +   MPCC blend configuration considering the :c:type:`dc_plane_info
> > +   <dc_plane_info>` input from DPP.
> > diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> > index d14bf1c35d7e..7ec9dbe18b65 100644
> > --- a/Documentation/gpu/drm-kms.rst
> > +++ b/Documentation/gpu/drm-kms.rst
> > @@ -532,6 +532,8 @@ Standard Plane Properties
> >   .. kernel-doc:: drivers/gpu/drm/drm_plane.c
> >      :doc: standard plane properties
> > +.. _plane_composition_properties:
> > +
> >   Plane Composition Properties
> >   ----------------------------
> 
> From a beginner's perspective, the changes from this series are readable,
> but I cannot tell if there are any technical mistakes. So,
> regarding readability and rendering htmldocs, apart from the nits I've
> raised, this whole series is
> 
> Reviewed-by: Tales Aparecida <tales.aparecida at gmail.com>
> 
> Thanks for the patch series, Melissa,

Hi Tales,

Thanks for taking a look at this series and reviewing it carefully.
Again, I'll address your comments in the next version.

Best Regards,

Melissa

> Tales Aparecida
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20220720/2e856c42/attachment.sig>