[PATCH v1 1/6] drm/vblank: Add intro to documentation

[Thomas Zimmermann]

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 at ravnborg.org>
> Co-developed-by: Lyude Paul <lyude at redhat.com>
> Cc: Lyude Paul <lyude at redhat.com>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
> Cc: Maxime Ripard <mripard at kernel.org>
> Cc: Thomas Zimmermann <tzimmermann at suse.de>
> Cc: David Airlie <airlied at 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 at suse.de>

Best regards
Thomas

-- 
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Maxfeldstr. 5, 90409 Nürnberg, Germany
(HRB 36809, AG Nürnberg)
Geschäftsführer: Felix Imendörffer

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20200330/44b8de34/attachment.sig>