[PATCH wayland v2] doc: Fill in high level description for Surfaces

[Pekka Paalanen]

On Fri, 12 Dec 2014 11:40:01 -0800
Bryce Harrington <bryce at osg.samsung.com> wrote:

> Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
>  doc/publican/sources/Protocol.xml |   34 ++++++++++++++++++++++++++++++----
>  1 file changed, 30 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> index b79b6be..9c6cb3b 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -282,13 +282,39 @@
>    <section id="sect-Protocol-Surface">
>      <title>Surfaces</title>
>      <para>
> -      Surfaces are created by the client.
> -      Clients don't know the global position of their surfaces, and
> +      A surface manages rectangular grids of pixels that clients create

I'd say a grid, there are not multiple.

> +      for displaying their content to the screen.  The surface keeps
> +      track of its location and size relative to whatever contains it
> +      (which might be just a parent surface), thus clients don't know

I'm not sure how "thus" follows here. These are just two unrelated
facts.

> +      the global position of their surfaces.  Importantly, clients
>        cannot access other clients surfaces.
>      </para>
>      <para>
> -      See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
> -      description.
> +      The data for the grid of pixels is stored in a wl_buffer object.

"Provided" rather than "stored".

> +      A displayable surface has one or more of these content buffers
> +      containing the content for the screen.  For example, a typical
> +      surface maintains a pair of these buffers that are swapped between

I'd like to reword this somehow. The coupling between surfaces and
buffers is much more loose. How about:

"One or more of these content buffers are needed to give and keep
updating the contents of a surface. For example, typically a client
maintains a pair of wl_buffers for each wl_surface. The pair of buffers
are swapped between..."

> +      the client and the compositor.  Once the client has finished
> +      writing pixels, it 'commits' the buffer; this permits the
> +      compositor to access the buffer and read the pixels.  When the
> +      compositor is finished with a buffer, it releases it back to the
> +      client.  This way, the client can begin writing the next buffer
> +      while the compositor is processing the current one.

"using" rather than "processing"?

> +    </para>
> +    <para>
> +      The actual processing behavior in practice can vary from one
> +      backend to the next, and really is a renderer implementation
> +      detail.  In particular, the display of the pixels on the screen
> +      can happen after an unpredictable amount of time.  For example,
> +      GL/RPi renderers with SHM-based buffers copy into a shadow buffer
> +      and so will display instantly, whereas GL buffers on the GL
> +      renderer do a blit for final presentation on the next
> +      attach/commit, and DRM/atomic backends do it sometime later since
> +      they promote the buffer directly to scanout.

You are thinking about Weston specifically here, while Wayland doc
should be more generic. Other compositors might not have backends or
renderers as a concept. I think it would be sufficient to be more
vague: varies from compositor to compositor, may vary even at runtime,
and is a compositor implementation detail.

"display instantly" is false. Everything will always wait for the
commit before it is displayed. When it will actually be displayed is
just "as soon as possible", preferably without tearing. No need to say
anything more specific.

The copying can indeed happen at any time, multiple times, or not at all
if the compositor can sample directly from the wl_buffer's storage.

Key point here is that once a wl_buffer has been attached and
committed, it is reserved by the server. While the wl_buffer is
reserved by the server, the server can read its contents at any time.
Only after the server releases the wl_buffer, it is race-free for the
client to draw into it again.

> +    </para>
> +    <para>
> +      See <xref linkend="protocol-spec-interface-wl_surface"/> for the
> +      protocol description.
>      </para>
>    </section>
>    <section id="sect-Protocol-Input">

Sorry for the nitpicking, I hope it's for the better and not just
different. :-)

Maybe you could also say something about how surfaces are used as
targets for input? That you can't usually get input if you don't have a
visible surface.


Thanks,
pq