On Wed, 17 Apr 2024 00:30:58 +0200 Louis Chauvet <louis.chauvet@xxxxxxxxxxx> wrote: > Le 15/04/24 - 14:36, Pekka Paalanen a écrit : > > On Tue, 09 Apr 2024 12:04:06 +0200 > > Louis Chauvet <louis.chauvet@xxxxxxxxxxx> wrote: > > > > > The expected behavior of the rotation property was not very clear. Add > > > more examples to explain what is the expected result. > > > > > > Signed-off-by: Louis Chauvet <louis.chauvet@xxxxxxxxxxx> > > > --- > > > drivers/gpu/drm/drm_blend.c | 52 +++++++++++++++++++++++++++++++++------------ > > > 1 file changed, 38 insertions(+), 14 deletions(-) > > > > > > diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c > > > index 8d4b317eb9d7..6fbb8730d8b0 100644 > > > --- a/drivers/gpu/drm/drm_blend.c > > > +++ b/drivers/gpu/drm/drm_blend.c > > > @@ -104,6 +104,9 @@ > > > * Without this property the rectangle is only scaled, but not rotated or > > > * reflected. > > > * > > > + * See drm_plane_create_rotation_property() for details about the expected rotation and > > > + * reflection behavior. > > > > I think internal function docs should be referring to UAPI docs, and > > not vice versa. Internal functions can change, but UAPI cannot. > > > > > + * > > > * Possbile values: > > > * > > > * "rotate-<degrees>": > > > @@ -114,18 +117,6 @@ > > > * Signals that the contents of a drm plane is reflected along the > > > * <axis> axis, in the same way as mirroring. > > > * > > > - * reflect-x:: > > > - * > > > - * |o | | o| > > > - * | | -> | | > > > - * | v| |v | > > > - * > > > - * reflect-y:: > > > - * > > > - * |o | | ^| > > > - * | | -> | | > > > - * | v| |o | > > > - * > > > * zpos: > > > * Z position is set up with drm_plane_create_zpos_immutable_property() and > > > * drm_plane_create_zpos_property(). It controls the visibility of overlapping > > > @@ -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. > > > > When going in which direction? Is the first image the FB source > > rectangle contents, and the second image what the plane looks like in > > CRTC frame of reference? > > The first is the FB source, the second is the expected result on the CRTC > output. > > I will add a sentence before the schemas: > > * Here are some examples of rotation and reflections, on the left it is > * the content of the source frame buffer, on the right is the expected > * result on the CRTC output. > > > > > > + * > > > + * 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). > > > */ > > > int drm_plane_create_rotation_property(struct drm_plane *plane, > > > unsigned int rotation, > > > > > > > These are definitely improvements. I think they should just be in the > > UAPI section rather than implementation details. > > So, somewhere in [1]? It feel strange because this is in the `GPU Driver > Developer’s Guide` section, not a `UAPI interfaces`. The whole kernel documentation layout is a big mess. I *still* spend ages trying to find the pages I know exist. https://docs.kernel.org/gpu/drm-kms.html#plane-composition-properties is where properties are documented for userspace developers to look at. Let's see... I'm cheating and looking what hierarchy I need to follow to find the place I am at: The Linux Kernel -> Subsystems -> Human Interfaces: GPU Driver Developer's Guide -> Kernel Mode Setting (KMS) <- oops, don't click that, take a step back -> Kernel Mode Setting (KMS): KMS properties <- oops, don't click that, take a step back -> Kernel Mode Setting (KMS): KMS properties: Plane Composition Properties So yeah, UAPI docs are under graphics driver developer's guide, inside human interface subsystems. Thanks, pq > [1]: https://dri.freedesktop.org/docs/drm/gpu/drm-uapi.html > > Thanks, > Louis Chauvet > > > Disclaimer again to everyone else: I cannot tell if this is the correct > > documentation or its inverse. > > > > > > Thanks, > > pq > > >
Attachment:
pgpKw5SgC6uyE.pgp
Description: OpenPGP digital signature
