From: Sam Ravnborg <sam@ravnborg.org>
To: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Neil Armstrong <narmstrong@baylibre.com>,
David Airlie <airlied@linux.ie>,
Liviu Dudau <liviu.dudau@arm.com>,
dri-devel@lists.freedesktop.org,
Andrzej Hajda <a.hajda@samsung.com>,
Nirmoy Das <nirmoy.das@amd.com>,
Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
Mihail Atanassov <Mihail.Atanassov@arm.com>,
Emil Velikov <emil.velikov@collabora.com>,
David Francis <David.Francis@amd.com>,
James Qian Wang <james.qian.wang@arm.com>,
Jonas Karlman <jonas@kwiboo.se>,
Mikita Lipski <mikita.lipski@amd.com>,
Jernej Skrabec <jernej.skrabec@siol.net>,
Andrzej Pietrasiewicz <andrzej.p@collabora.com>,
Boris Brezillon <boris.brezillon@collabora.com>,
Alex Deucher <alexander.deucher@amd.com>
Subject: Re: [PATCH v1 1/6] drm/vblank: Add intro to documentation
Date: Mon, 30 Mar 2020 20:56:33 +0200 [thread overview]
Message-ID: <20200330185633.GA7594@ravnborg.org> (raw)
In-Reply-To: <b1347cb6-0116-16de-1602-d57c6069b7ea@suse.de>
Hi Thomas.
On Mon, Mar 30, 2020 at 01:29:16PM +0200, Thomas Zimmermann wrote:
> Hi Sam and Lyude,
>
> thanks for improving the documentation. Below are a few points that I'd
> found more understandable. I'm no native speaker, though.
>
> Am 28.03.20 um 14:20 schrieb Sam Ravnborg:
> > Lyude Paul wrote a very good intro to vblank here:
> > https://lore.kernel.org/dri-devel/faf63d8a9ed23c16af69762f59d0dca6b2bf085f.camel@redhat.com/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27
> >
> > Add this to the intro chapter in drm_vblank.c so others
> > can benefit from it too.
> >
> > Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
> > Co-developed-by: Lyude Paul <lyude@redhat.com>
> > Cc: Lyude Paul <lyude@redhat.com>
> > Cc: Daniel Vetter <daniel@ffwll.ch>
> > Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> > Cc: Maxime Ripard <mripard@kernel.org>
> > Cc: Thomas Zimmermann <tzimmermann@suse.de>
> > Cc: David Airlie <airlied@linux.ie>
> > ---
> > drivers/gpu/drm/drm_vblank.c | 15 +++++++++++++++
> > 1 file changed, 15 insertions(+)
> >
> > diff --git a/drivers/gpu/drm/drm_vblank.c b/drivers/gpu/drm/drm_vblank.c
> > index bcf346b3e486..95cac22d59d1 100644
> > --- a/drivers/gpu/drm/drm_vblank.c
> > +++ b/drivers/gpu/drm/drm_vblank.c
> > @@ -41,6 +41,21 @@
> > /**
> > * DOC: vblank handling
> > *
> > + * From the perspective of a computer, every time a computer monitor displays
>
> Possibly change from dative case to genitive:
>
> "From the computer's perspective," ...
>
> > + * a new frame it's done by "scanning out" the display image from top to
> > + * bottom, one row of pixels at a time. which row of pixels we're on is
>
> s/which/Which
>
> The text changes from third person (the computer) to first person
> (we're). Makes it harder to read. I'd remove both, "we" and "computer",
> and speak of display hardware or scanout engine.
>
> > + * referred to as the scanline.
>
> I'd say a scanline is any of them. Maybe say "current scanline"?
>
> > + * Additionally, there's usually a couple of extra scanlines which we
>
> "In addition to the display's visible area, there's usually a couple of
> extra scanlines that" ...
>
> > + * scan out, but aren't actually displayed on the screen (these sometimes
> > + * get used by HDMI audio and friends, but that's another story).
> > + * The period where we're on these scanlines is referred to as the vblank.
>
> I'd replace vblank with "vertical blanking period." That term is
> required in the next paragraph.
>
> The time when the hardware operates on these invisible scanlines is
> referred to as vertical blanking period, or simply vblank.
>
> > + *
> > + * On a lot of display hardware, programming needs to take effect during the
> > + * vertical blanking period so that settings like gamma, what frame we're
>
> "we" again
>
> > + * scanning out, etc. can be safely changed without showing visual tearing
> > + * on the screen. In some unforgiving hardware, some of this programming has
> > + * to both start and end in the same vblank - vertical blanking.
> > + *
> > * Vertical blanking plays a major role in graphics rendering. To achieve
> > * tear-free display, users must synchronize page flips and/or rendering to
> > * vertical blanking. The DRM API offers ioctls to perform page flips
> >
>
> In any case
>
> Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Thanks for the detailed feedabck - I have tried to reword it so it
better fits the context and have taking into account your suggetions.
See other mail for the updated patch.
Sam
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2020-03-30 18:56 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-28 13:20 [PATCH v1 0/6] drm: kernel-doc stuff Sam Ravnborg
2020-03-28 13:20 ` [PATCH v1 1/6] drm/vblank: Add intro to documentation Sam Ravnborg
2020-03-30 11:29 ` Thomas Zimmermann
2020-03-30 18:56 ` Sam Ravnborg [this message]
2020-03-30 18:57 ` [PATCH v2 " Sam Ravnborg
2020-03-30 21:51 ` Lyude Paul
2020-03-31 6:14 ` Thomas Zimmermann
2020-03-31 7:55 ` Daniel Vetter
2020-03-28 13:20 ` [PATCH v1 2/6] drm/fb: fix kernel-doc in drm_framebuffer.h Sam Ravnborg
2020-03-30 11:35 ` Andrzej Pietrasiewicz
2020-03-30 19:02 ` Sam Ravnborg
2020-03-28 13:20 ` [PATCH v1 3/6] drm/sched: fix kernel-doc in gpu_scheduler.h Sam Ravnborg
2020-03-31 7:54 ` Daniel Vetter
2020-04-05 20:38 ` Sam Ravnborg
2020-03-28 13:20 ` [PATCH v1 4/6] drm: writeback: document callbacks Sam Ravnborg
2020-03-31 7:53 ` Daniel Vetter
2020-04-05 22:56 ` Laurent Pinchart
2020-03-28 13:20 ` [PATCH v1 5/6] drm/dp_mst: add kernel-doc for drm_dp_mst_port.fec_capable Sam Ravnborg
2020-03-30 15:01 ` Lyude Paul
2020-03-30 19:05 ` Sam Ravnborg
2020-03-28 13:20 ` [PATCH v1 6/6] drm/bridge: fix kernel-doc warning in panel.c Sam Ravnborg
2020-03-31 7:48 ` Daniel Vetter
2020-04-05 20:37 ` Sam Ravnborg
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200330185633.GA7594@ravnborg.org \
--to=sam@ravnborg.org \
--cc=David.Francis@amd.com \
--cc=Mihail.Atanassov@arm.com \
--cc=a.hajda@samsung.com \
--cc=airlied@linux.ie \
--cc=alexander.deucher@amd.com \
--cc=andrzej.p@collabora.com \
--cc=boris.brezillon@collabora.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=emil.velikov@collabora.com \
--cc=james.qian.wang@arm.com \
--cc=jernej.skrabec@siol.net \
--cc=jonas@kwiboo.se \
--cc=laurent.pinchart@ideasonboard.com \
--cc=liviu.dudau@arm.com \
--cc=mikita.lipski@amd.com \
--cc=narmstrong@baylibre.com \
--cc=nirmoy.das@amd.com \
--cc=tzimmermann@suse.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).