Received-SPF: pass (google.com: domain of linux-kernel+bounces-145354-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
Date: Mon, 15 Apr 2024 21:28:22 +0700
From: Bagas Sanjaya <bagasdotme@gmail.com>
To: Louis Chauvet <louis.chauvet@bootlin.com>,
	Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
	Maxime Ripard <mripard@kernel.org>,
	Thomas Zimmermann <tzimmermann@suse.de>,
	David Airlie <airlied@gmail.com>, Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org,
	seanpaul@google.com, marcheu@google.com, nicolejadeyee@google.com,
	pekka.paalanen@collabora.com, thomas.petazzoni@bootlin.com
Subject: Re: [PATCH 2/3] drm: drm_blend.c: Improve
 drm_plane_create_rotation_property kernel doc
Message-ID: <Zh05hqtB9owzjjez@archie.me>
References: <20240409-google-drm-doc-v1-0-033d55cc8250@bootlin.com>
 <20240409-google-drm-doc-v1-2-033d55cc8250@bootlin.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="j3zP2GZ4OPkidsR1"
Content-Disposition: inline
In-Reply-To: <20240409-google-drm-doc-v1-2-033d55cc8250@bootlin.com>


--j3zP2GZ4OPkidsR1
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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 dire=
ction,
>   * 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 samp=
led from
> - * the source rectangle, before scaling it to fit the destination rectan=
gle.
> + * rotation.
> + *
> + * Here are some examples of rotation and reflections:
> + *
> + * |o  +|  REFLECT_X  |+  o|
> + * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
> + * |    |             |    |
> + *
> + * |o   |  REFLECT_Y  |+   |
> + * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
> + * |+   |             |o   |
> + *
> + * |o  +|  ROTATE_90  |+   |
> + * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
> + * |    |             |o   |
> + *
> + * |o   |  ROTATE_180 |   +|
> + * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
> + * |+   |             |   o|
> + *
> + * |o   |  ROTATE_270 |+  o|
> + * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
> + * |+   |             |    |
> + *
> + * 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_REF=
LECT_X is:
> + *
> + * |o  +|  REFLECT_X  |+  o|  ROTATE_90  |o   |
> + * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |  =3D=3D=3D=3D=3D=3D=3D=3D> =
 |    |
> + * |    |             |    |             |+   |
> + *
> + * It is not possible to pass multiple rotation at the same time. (i.e R=
OTATE_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: Un=
defined substitution referenced: "o +".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:265: ERROR: Un=
defined substitution referenced: "+ o".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:273: ERROR: Un=
defined substitution referenced: "o +".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:277: ERROR: Un=
defined substitution referenced: "o | ROTATE_180 | +".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:277: ERROR: Un=
defined substitution referenced: "+ | | o".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:281: ERROR: Un=
defined substitution referenced: "o | ROTATE_270 |+ o".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:290: ERROR: Un=
defined substitution referenced: "o +".
Documentation/gpu/drm-kms:389: ./drivers/gpu/drm/drm_blend.c:290: ERROR: Un=
defined 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 be=
fore
  * rotation.
  *
- * Here are some examples of rotation and reflections:
+ * Here are some examples of rotation and reflections::
  *
- * |o  +|  REFLECT_X  |+  o|
- * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
- * |    |             |    |
+ *	|o  +|  REFLECT_X  |+  o|
+ *	|    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
+ *	|    |             |    |
  *
- * |o   |  REFLECT_Y  |+   |
- * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
- * |+   |             |o   |
+ *	|o   |  REFLECT_Y  |+   |
+ *	|    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
+ *	|+   |             |o   |
  *
- * |o  +|  ROTATE_90  |+   |
- * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
- * |    |             |o   |
+ *	|o  +|  ROTATE_90  |+   |
+ *	|    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
+ *	|    |             |o   |
  *
- * |o   |  ROTATE_180 |   +|
- * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
- * |+   |             |   o|
+ *	|o   |  ROTATE_180 |   +|
+ *	|    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
+ *	|+   |             |   o|
  *
- * |o   |  ROTATE_270 |+  o|
- * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
- * |+   |             |    |
+ *	|o   |  ROTATE_270 |+  o|
+ *	|    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |
+ *	|+   |             |    |
  *
  * Rotation and reflection can be combined to handle more situations. In t=
his condition, the
  * reflection is applied first and the rotation in second.
  *
- * For example the expected result for DRM_MODE_ROTATE_90 | DRM_MODE_REFLE=
CT_X is:
+ * For example the expected result for DRM_MODE_ROTATE_90 | DRM_MODE_REFLE=
CT_X is::
  *
- * |o  +|  REFLECT_X  |+  o|  ROTATE_90  |o   |
- * |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |=
    |
- * |    |             |    |             |+   |
+ *	|o  +|  REFLECT_X  |+  o|  ROTATE_90  |o   |
+ *	|    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |    |  =3D=3D=3D=3D=3D=3D=3D=3D>  |=
    |
+ *	|    |             |    |             |+   |
  *
  * It is not possible to pass multiple rotation at the same time. (i.e ROT=
ATE_90 | ROTATE_180 is
  * not the same as ROTATE_270 and is not accepted).

Thanks.

--=20
An old man doll... just what I always wanted! - Clara

--j3zP2GZ4OPkidsR1
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYKAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCZh05hgAKCRD2uYlJVVFO
o1ViAQCpYUwFBWA1VJ9hNZykmFyvVHFiqufi3AfxQWmolU+5WgD/QCeVancsmMRC
Xu+Tf5kfiNJTrMQwSlF/2Dxr+StGagc=
=91C7
-----END PGP SIGNATURE-----

--j3zP2GZ4OPkidsR1--