[PATCH] drm: Document the alpha blending rules

[PATCH] drm: Document the alpha blending rules

[Ville Syrjala]

From: Ville Syrjälä <ville.syrjala@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.

Cc: Mario Kleiner <mario.kleiner.de@gmail.com>
Cc: Stefan Schake <stschake@gmail.com>
Cc: Eric Anholt <eric@anholt.net>
Cc: Adrian Salido <salidoa@google.com>
Cc: Sean Paul <seanpaul@chromium.org>
Signed-off-by: Ville Syrjälä <ville.syrjala@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.
  */
 
 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.
+ */
+
 /* color index */
 #define DRM_FORMAT_C8		fourcc_code('C', '8', ' ', ' ') /* [7:0] C */
 
-- 
2.16.1

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [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@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@gmail.com>
> Cc: Stefan Schake <stschake@gmail.com>
> Cc: Eric Anholt <eric@anholt.net>
> Cc: Adrian Salido <salidoa@google.com>
> Cc: Sean Paul <seanpaul@chromium.org>
> Signed-off-by: Ville Syrjälä <ville.syrjala@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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel