[PATCH v2] drm: Clarify DRM_MODE_REFLECT_X/Y documentation

Ville Syrjälä ville.syrjala at linux.intel.com
Tue Sep 11 16:18:00 UTC 2018


On Tue, Sep 11, 2018 at 04:48:42PM +0100, Alexandru-Cosmin Gheorghe wrote:
> On Tue, Sep 11, 2018 at 04:45:25PM +0300, Ville Syrjälä wrote:
> > On Tue, Sep 11, 2018 at 02:20:22PM +0100, Alexandru-Cosmin Gheorghe wrote:
> > > Hi Ville,
> > > 
> > > On Tue, Sep 11, 2018 at 03:27:09PM +0300, Ville Syrjälä wrote:
> > > > On Mon, Sep 10, 2018 at 06:29:46PM +0100, Alexandru Gheorghe wrote:
> > > > > DRM_MODE_REFLECT_X and DRM_MODE_REFLECT_Y meaning seems a bit unclear
> > > > > to me, so try to clarify that with a bit of ascii graphics.
> > > > > 
> > > > > Changes since v1:
> > > > >   - Move the ascii graphics in the kerneldoc where all plane
> > > > >     properties are already documented and make sure it's properly
> > > > >     rendered, suggestested by Daniel Vetter.
> > > > > 
> > > > > Signed-off-by: Alexandru Gheorghe <alexandru-cosmin.gheorghe at arm.com>
> > > > > ---
> > > > >  drivers/gpu/drm/drm_blend.c | 22 ++++++++++++++++++++++
> > > > >  include/uapi/drm/drm_mode.h |  3 ++-
> > > > >  2 files changed, 24 insertions(+), 1 deletion(-)
> > > > > 
> > > > > diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c
> > > > > index 402b62d3f072..92f75c5c93ac 100644
> > > > > --- a/drivers/gpu/drm/drm_blend.c
> > > > > +++ b/drivers/gpu/drm/drm_blend.c
> > > > > @@ -101,6 +101,28 @@
> > > > >   *	Without this property the rectangle is only scaled, but not rotated or
> > > > >   *	reflected.
> > > > >   *
> > > > > + *	Possbile values:
> > > > > + *
> > > > > + *	"rotate-<degrees>":
> > > > > + *		Signals that a drm plane is rotated <degrees> degrees in counter
> > > > > + *		clockwise direction.
> > > > > + *
> > > > > + *	"reflect-<axis>":
> > > > > + *		Signals that the contents of a drm plane is reflected along the
> > > > > + *		<axis> axis, in the same way as mirroring.
> > > > 
> > > > What does "mirroring" mean? Feels like a circular definition here.
> > > > 
> > > 
> > > That's why I added the pictures to make it more clear, what
> > > reflect-x/reflect-y means.
> > 
> > Sure. Doesn't really answer the quesiton I was asking. I propose just
> > dropping the ", in the same way as mirroring." part. It provides no
> > useful information that I can see.
> 
> I was hopping the picture answers to what exactly mirroring means in
> this context, I have nothing against dropping that part from the
> description.
> 
> > 
> > > 
> > > > Also the relationship between rotate and reflect is missing from these
> > > > docs. The order matters, and I do believe we have it specified in some
> > > > comment somewhere. Would be good to include it here as well.
> > > 
> > > That's already explained in the documentation for
> > > drm_plane_create_rotation_property(), which is already referred here.
> > > 
> > > If you think that stuff should be duplicate here as well, it will have
> > > to be done in another patch, because I already merged this patch in
> > > drm-misc-next.
> > 
> > I don't think having multiple different pieces of documentation for the
> > same thing is a particularly good thing.
> 
> How do you propose to group this information?

I guess just remove the duplicated information from the
drm_plane_create_rotation_property() docs. And maybe add a note there
to tell the reader where the description of the bits can be found?

> 
> > 
> > > 
> > > > 
> > > > > + *
> > > > > + *	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
> > > > > diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> > > > > index 8d67243952f4..d3e0fe31efc5 100644
> > > > > --- a/include/uapi/drm/drm_mode.h
> > > > > +++ b/include/uapi/drm/drm_mode.h
> > > > > @@ -186,8 +186,9 @@ extern "C" {
> > > > >  /*
> > > > >   * DRM_MODE_REFLECT_<axis>
> > > > >   *
> > > > > - * Signals that the contents of a drm plane is reflected in the <axis> axis,
> > > > > + * Signals that the contents of a drm plane is reflected along the <axis> axis,
> > > > >   * in the same way as mirroring.
> > > > > + * See kerneldoc chapter "Plane Composition Properties" for more details.
> > > > >   *
> > > > >   * This define is provided as a convenience, looking up the property id
> > > > >   * using the name->prop id lookup is the preferred method.
> > > > > -- 
> > > > > 2.18.0
> > > > > 
> > > > > _______________________________________________
> > > > > dri-devel mailing list
> > > > > dri-devel at lists.freedesktop.org
> > > > > https://lists.freedesktop.org/mailman/listinfo/dri-devel
> > > > 
> > > > -- 
> > > > Ville Syrjälä
> > > > Intel
> > > 
> > > -- 
> > > Cheers,
> > > Alex G
> > 
> > -- 
> > Ville Syrjälä
> > Intel
> 
> -- 
> Cheers,
> Alex G

-- 
Ville Syrjälä
Intel


More information about the dri-devel mailing list