Re: [PATCH 2/3] drm: drm_blend.c: Improve drm_plane_create_rotation_property kernel doc

Louis Chauvet
2024-04-16T22:31:06Z

Le 15/04/24 - 21:28, Bagas Sanjaya a écrit :
> On Tue, Apr 09, 2024 at 12:04:06PM +0200, Louis Chauvet wrote:
> > @@ -266,8 +257,41 @@ EXPORT_SYMBOL(drm_plane_create_alpha_property);
> > *
> > * Rotation is the specified amount in degrees in counter clockwise direction,
> > * the X and Y axis are within the source rectangle, i.e. the X/Y axis before
> > - * rotation. After reflection, the rotation is applied to the image sampled from
> > - * the source rectangle, before scaling it to fit the destination rectangle.
> > + * rotation.
> > + *
> > + * Here are some examples of rotation and reflections:
> > + *
> > + * |o +| REFLECT_X |+ o|
> > + * | | ========> | |
> > + * | | | |
> > + *
> > + * |o | REFLECT_Y |+ |
> > + * | | ========> | |
> > + * |+ | |o |
> > + *
> > + * |o +| ROTATE_90 |+ |
> > + * | | ========> | |
> > + * | | |o |
> > + *
> > + * |o | ROTATE_180 | +|
> > + * | | ========> | |
> > + * |+ | | o|
> > + *
> > + * |o | ROTATE_270 |+ o|
> > + * | | ========> | |
> > + * |+ | | |
> > + *
> > + * Rotation and reflection can be combined to handle more situations. In this condition, the
> > + * reflection is applied first and the rotation in second.
> > + *
> > + * For example the expected result for DRM_MODE_ROTATE_90 | DRM_MODE_REFLECT_X is:
> > + *
> > + * |o +| REFLECT_X |+ o| ROTATE_90 |o |
> > + * | | ========> | | ========> | |
> > + * | | | | |+ |
> > + *
> > + * It is not possible to pass multiple rotation at the same time. (i.e ROTATE_90 | ROTATE_180 is
> > + * not the same as ROTATE_270 and is not accepted).
>
> Sphinx reports htmldocs warnings on these transformation diagrams:
>
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:265: ERROR: Undefined substitution referenced: "o +".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:265: ERROR: Undefined substitution referenced: "+ o".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:273: ERROR: Undefined substitution referenced: "o +".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:277: ERROR: Undefined substitution referenced: "o | ROTATE_180 | +".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:277: ERROR: Undefined substitution referenced: "+ | | o".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:281: ERROR: Undefined substitution referenced: "o | ROTATE_270 |+ o".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:290: ERROR: Undefined substitution referenced: "o +".
> Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:290: ERROR: Undefined substitution referenced: "+ o".
>
> I have to wrap them in literal blocks:
>
> ---- >8 ----
> diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c
> index 6fbb8730d8b022..f2cbf8d8efbbbc 100644
> --- a/drivers/gpu/drm/drm_blend.c
> +++ b/drivers/gpu/drm/drm_blend.c
> @@ -259,36 +259,36 @@ EXPORT_SYMBOL(drm_plane_create_alpha_property);
> * the X and Y axis are within the source rectangle, i.e. the X/Y axis before
> * rotation.
> *
> - * Here are some examples of rotation and reflections:
> + * Here are some examples of rotation and reflections::
> *
> - * |o +| REFLECT_X |+ o|
> - * | | ========> | |
> - * | | | |
> + * |o +| REFLECT_X |+ o|
> + * | | ========> | |
> + * | | | |
> *
> - * |o | REFLECT_Y |+ |
> - * | | ========> | |
> - * |+ | |o |
> + * |o | REFLECT_Y |+ |
> + * | | ========> | |
> + * |+ | |o |
> *
> - * |o +| ROTATE_90 |+ |
> - * | | ========> | |
> - * | | |o |
> + * |o +| ROTATE_90 |+ |
> + * | | ========> | |
> + * | | |o |
> *
> - * |o | ROTATE_180 | +|
> - * | | ========> | |
> - * |+ | | o|
> + * |o | ROTATE_180 | +|
> + * | | ========> | |
> + * |+ | | o|
> *
> - * |o | ROTATE_270 |+ o|
> - * | | ========> | |
> - * |+ | | |
> + * |o | ROTATE_270 |+ o|
> + * | | ========> | |
> + * |+ | | |
> *
> * Rotation and reflection can be combined to handle more situations. In this condition, the
> * reflection is applied first and the rotation in second.
> *
> - * For example the expected result for DRM_MODE_ROTATE_90 | DRM_MODE_REFLECT_X is:
> + * For example the expected result for DRM_MODE_ROTATE_90 | DRM_MODE_REFLECT_X is::
> *
> - * |o +| REFLECT_X |+ o| ROTATE_90 |o |
> - * | | ========> | | ========> | |
> - * | | | | |+ |
> + * |o +| REFLECT_X |+ o| ROTATE_90 |o |
> + * | | ========> | | ========> | |
> + * | | | | |+ |
> *
> * It is not possible to pass multiple rotation at the same time. (i.e ROTATE_90 | ROTATE_180 is
> * not the same as ROTATE_270 and is not accepted).
>
> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara

It will be fixed in the next version, thanks!

Louis Chauvet

--
Louis Chauvet, Bootlin
Embedded Linux and Kernel engineering