[PATCH] drm: Document the alpha blending rules

[Daniel Vetter]

On Thu, Mar 22, 2018 at 11:14:17AM +0200, Ville Syrjala wrote:
> From: Ville Syrjälä <ville.syrjala at linux.intel.com>
> 
> Document the fact that the use of a framebuffer with alpha implies
> pre-multipled alpha blending, and that the crtc background color
> is assumed to be black.
> 
> Not sure drm_fourcc.h is the best place for the uapi docs, but
> couldn't think of anything better really.

I started to documented the plane blending rules in the docs for atomic
properties:

https://dri.freedesktop.org/docs/drm/gpu/drm-kms.html#plane-composition-properties

It already mentions that the background color is black:

"Note that all the property extensions described here apply either to the
plane or the CRTC (e.g. for the background color, which currently is not
exposed and assumed to be black)."

Iirc the alpha property patches will add more docs in this area and
clarify all the blending rules a bit more.

> Cc: Mario Kleiner <mario.kleiner.de at gmail.com>
> Cc: Stefan Schake <stschake at gmail.com>
> Cc: Eric Anholt <eric at anholt.net>
> Cc: Adrian Salido <salidoa at google.com>
> Cc: Sean Paul <seanpaul at chromium.org>
> Signed-off-by: Ville Syrjälä <ville.syrjala at linux.intel.com>
> ---
>  drivers/gpu/drm/drm_plane.c   | 6 ++++++
>  include/uapi/drm/drm_fourcc.h | 7 +++++++
>  2 files changed, 13 insertions(+)
> 
> diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c
> index 143041666096..21e3a560811d 100644
> --- a/drivers/gpu/drm/drm_plane.c
> +++ b/drivers/gpu/drm/drm_plane.c
> @@ -48,6 +48,12 @@
>   *
>   * The type of a plane is exposed in the immutable "type" enumeration property,
>   * which has one of the following values: "Overlay", "Primary", "Cursor".
> + *
> + * Use of a framebuffer with alpha implies that the plane will use
> + * pre-multiplied alpha blending: Dc = Sc + (1.0 - Sa) * Dc,
> + * where Sa is source alpha, Sc is source color, and Dc is destination
> + * color. The crtc background color below all the planes is assumed to
> + * be black.

Maybe we just need to add a sphinx link to the plane composition
properties section here? Since kerneldoc is just plain rst we can do this.

>   */
>  
>  static unsigned int drm_num_planes(struct drm_device *dev)
> diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
> index e04613d30a13..8b889a6adcd4 100644
> --- a/include/uapi/drm/drm_fourcc.h
> +++ b/include/uapi/drm/drm_fourcc.h
> @@ -35,6 +35,13 @@ extern "C" {
>  
>  #define DRM_FORMAT_BIG_ENDIAN (1<<31) /* format is big endian instead of little endian */
>  
> +/*
> + * Note that using any format with alpha (A) implies pre-multiplied
> + * alpha blending: Dc = Sc + (1.0 - Sa) * Dc, where Sa is source alpha,
> + * Sc is source color, and Dc is destination color. The crtc background
> + * color below all the planes is assumed to be black.
> + */

This sounds like perfect fodder for a DOC overview section for
drm_fourcc.[hc]. We already include the function docs into the overall
kerneldoc.
-Daniel

> +
>  /* color index */
>  #define DRM_FORMAT_C8		fourcc_code('C', '8', ' ', ' ') /* [7:0] C */
>  
> -- 
> 2.16.1
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch