doc: Fill in high level description for Surfaces

Submitted by Bryce Harrington on Dec. 11, 2014, 2:04 a.m.

Details

Message ID 1418263462-5146-1-git-send-email-bryce@osg.samsung.com
State Superseded
Delegated to: Bryce Harrington
Headers show

Not browsing as part of any series.

Commit Message

Bryce Harrington Dec. 11, 2014, 2:04 a.m.
Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
---
 doc/publican/sources/Protocol.xml |   20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

Patch hide | download patch | download mbox

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index b79b6be..2e48a7c 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -282,13 +282,23 @@ 
   <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
-      cannot access other clients surfaces.
+      A surface manages a rectangular grid of pixels that clients create
+      for displaying their content to the screen.  Clients don't know
+      the global position of their surfaces, and cannot access other
+      clients surfaces.
     </para>
     <para>
-      See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
-      description.
+      A surface has a pair of content buffers that 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.
+    </para>
+    <para>
+      See <xref linkend="protocol-spec-interface-wl_surface"/> for the
+      protocol description.
     </para>
   </section>
   <section id="sect-Protocol-Input">

Comments

2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com>:
>
> Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
> ---
>  doc/publican/sources/Protocol.xml |   20 +++++++++++++++-----
>  1 file changed, 15 insertions(+), 5 deletions(-)
>
> diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> index b79b6be..2e48a7c 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -282,13 +282,23 @@
>    <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
> -      cannot access other clients surfaces.
> +      A surface manages a rectangular grid of pixels that clients create
> +      for displaying their content to the screen.  Clients don't know
> +      the global position of their surfaces, and cannot access other
> +      clients surfaces.
>      </para>
>      <para>
> -      See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
> -      description.
> +      A surface has a pair of content buffers that are swapped between

Uhm, a surface can actually use more than two buffers, that depends on
the client only. For shm buffers, if the compositor supports it, a
surface can even be single buffered without creating artifacts.

> +      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.
> +    </para>
> +    <para>
> +      See <xref linkend="protocol-spec-interface-wl_surface"/> for the
> +      protocol description.
>      </para>
>    </section>
>    <section id="sect-Protocol-Input">
> --
> 1.7.9.5
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Hi,

On Thursday, December 11, 2014, Giulio Camuffo <giuliocamuffo@gmail.com>
wrote:

> 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com
> <javascript:;>>:
> > +      A surface manages a rectangular grid of pixels that clients create
> > +      for displaying their content to the screen.  Clients don't know
> > +      the global position of their surfaces, and cannot access other
> > +      clients surfaces.


It would be good to make the linkage to wl_buffers clear, i.e. that
surfaces do not have intrinsic storage of their own.


> > +      A surface has a pair of content buffers that are swapped between
>
> Uhm, a surface can actually use more than two buffers, that depends on
> the client only. For shm buffers, if the compositor supports it, a
> surface can even be single buffered without creating artifacts.


Yeah, that was my first thought on reading this.


> > +      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.
>

It might also be nice to clarify that this can happen at any time:
instantly (i.e. copying into a shadow buffer, such as SHM buffers on GL/RPi
renderers), immediately on the next attach/commit (i.e. a renderer with no
scanout promotion that does a blit for final presentation, such as GL
buffers on GL renderer), or sometime later (buffer promoted directly to
scanout, such as a DRM/atomic backend). But ideally without reference to
those specific cases, as they're really just implementation details that
can change.

Thanks a lot for doing this! Are you planning to do others?

Cheers,
Daniel
On Thu, Dec 11, 2014 at 09:49:28AM +0000, Daniel Stone wrote:
> Hi,
> 
> On Thursday, December 11, 2014, Giulio Camuffo <giuliocamuffo@gmail.com>
> wrote:
> 
> > 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com
> > <javascript:;>>:
> > > +      A surface manages a rectangular grid of pixels that clients create
> > > +      for displaying their content to the screen.  Clients don't know
> > > +      the global position of their surfaces, and cannot access other
> > > +      clients surfaces.
> 
> 
> It would be good to make the linkage to wl_buffers clear, i.e. that
> surfaces do not have intrinsic storage of their own.
> 
> 
> > > +      A surface has a pair of content buffers that are swapped between
> >
> > Uhm, a surface can actually use more than two buffers, that depends on
> > the client only. For shm buffers, if the compositor supports it, a
> > surface can even be single buffered without creating artifacts.
> 
> 
> Yeah, that was my first thought on reading this.
> 
> 
> > > +      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.
> >
> 
> It might also be nice to clarify that this can happen at any time:
> instantly (i.e. copying into a shadow buffer, such as SHM buffers on GL/RPi
> renderers), immediately on the next attach/commit (i.e. a renderer with no
> scanout promotion that does a blit for final presentation, such as GL
> buffers on GL renderer), or sometime later (buffer promoted directly to
> scanout, such as a DRM/atomic backend). But ideally without reference to
> those specific cases, as they're really just implementation details that
> can change.
> 
> Thanks a lot for doing this! Are you planning to do others?

I'm a documentation nerd so will certainly be sending more patches like
this.

But my motivation here is rather mercenary - I was trying to understand
what surfaces can do as I revamp the headless testing patchset, and
noticed the documentation was particularly sparse on this.  So the
feedback is useful to help me better understand this object.

Thanks both to you and Giulio.  I'll review and revise the docs changes.

Bryce
On Thu, Dec 11, 2014 at 10:28:25AM +0200, Giulio Camuffo wrote:
> 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com>:
> >
> > Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
> > ---
> >  doc/publican/sources/Protocol.xml |   20 +++++++++++++++-----
> >  1 file changed, 15 insertions(+), 5 deletions(-)
> >
> > diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> > index b79b6be..2e48a7c 100644
> > --- a/doc/publican/sources/Protocol.xml
> > +++ b/doc/publican/sources/Protocol.xml
> > @@ -282,13 +282,23 @@
> >    <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
> > -      cannot access other clients surfaces.
> > +      A surface manages a rectangular grid of pixels that clients create
> > +      for displaying their content to the screen.  Clients don't know
> > +      the global position of their surfaces, and cannot access other
> > +      clients surfaces.
> >      </para>
> >      <para>
> > -      See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
> > -      description.
> > +      A surface has a pair of content buffers that are swapped between
> 
> Uhm, a surface can actually use more than two buffers, that depends on
> the client only. For shm buffers, if the compositor supports it, a
> surface can even be single buffered without creating artifacts.

Good to know.  I'll soften the language a bit:

      A surface has one or more content buffers containing the data for                                             
      the screen.  A typical surface maintains a pair (or more) of                                                  
      buffers that are swapped between the client and the compositor.

I don't know that we need to be any more detailed then this.  The purpose
of the high level docs should be to just introduce the concepts, and
leave the details to the reference docs, which look quite thorough in
this case.

Thanks for reviewing!

Bryce 
> > +      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.
> > +    </para>
> > +    <para>
> > +      See <xref linkend="protocol-spec-interface-wl_surface"/> for the
> > +      protocol description.
> >      </para>
> >    </section>
> >    <section id="sect-Protocol-Input">
> > --
> > 1.7.9.5
> >
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel@lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
On Thu, Dec 11, 2014 at 09:49:28AM +0000, Daniel Stone wrote:
> Hi,
> 
> On Thursday, December 11, 2014, Giulio Camuffo <giuliocamuffo@gmail.com>
> wrote:
> 
> > 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com
> > <javascript:;>>:
> > > +      A surface manages a rectangular grid of pixels that clients create
> > > +      for displaying their content to the screen.  Clients don't know
> > > +      the global position of their surfaces, and cannot access other
> > > +      clients surfaces.
> 
> 
> It would be good to make the linkage to wl_buffers clear, i.e. that
> surfaces do not have intrinsic storage of their own.
> 
> 
> > > +      A surface has a pair of content buffers that are swapped between
> >
> > Uhm, a surface can actually use more than two buffers, that depends on
> > the client only. For shm buffers, if the compositor supports it, a
> > surface can even be single buffered without creating artifacts.
> 
> 
> Yeah, that was my first thought on reading this.

The reference docs for wl_surface::attach say,

 Surface contents are double-buffered state, see wl_surface.commit. 

Most of the other wl_surface requests similarly mention double-buffered
surfaces.  Nothing there discusses single-buffers, and nothing describes
a multi-buffered state, although wl_surface::commit includes this
(rather ambiguous) statement:

 Other interfaces may add further double-buffered surface state. 

(Whatever this actually means, it probably should be elaborated on.)

It's possible I've missed something or I'm just dumb, but if >2 buffers
is a thing that should be documented to users, then I'd expect the
reference docs to cover it.

> > > +      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.
> >
> 
> It might also be nice to clarify that this can happen at any time:
> instantly (i.e. copying into a shadow buffer, such as SHM buffers on GL/RPi
> renderers), immediately on the next attach/commit (i.e. a renderer with no
> scanout promotion that does a blit for final presentation, such as GL
> buffers on GL renderer), or sometime later (buffer promoted directly to
> scanout, such as a DRM/atomic backend). But ideally without reference to
> those specific cases, as they're really just implementation details that
> can change.

Alright, I've rephrased this - hopefully not butchering the meaning in
the process.  Please review my updated patch, which i'll post directly.

Thanks for the review (and explanations of how things work!)

Bryce
2014-12-12 21:37 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com>:
> On Thu, Dec 11, 2014 at 09:49:28AM +0000, Daniel Stone wrote:
>> Hi,
>>
>> On Thursday, December 11, 2014, Giulio Camuffo <giuliocamuffo@gmail.com>
>> wrote:
>>
>> > 2014-12-11 4:04 GMT+02:00 Bryce Harrington <bryce@osg.samsung.com
>> > <javascript:;>>:
>> > > +      A surface manages a rectangular grid of pixels that clients create
>> > > +      for displaying their content to the screen.  Clients don't know
>> > > +      the global position of their surfaces, and cannot access other
>> > > +      clients surfaces.
>>
>>
>> It would be good to make the linkage to wl_buffers clear, i.e. that
>> surfaces do not have intrinsic storage of their own.
>>
>>
>> > > +      A surface has a pair of content buffers that are swapped between
>> >
>> > Uhm, a surface can actually use more than two buffers, that depends on
>> > the client only. For shm buffers, if the compositor supports it, a
>> > surface can even be single buffered without creating artifacts.
>>
>>
>> Yeah, that was my first thought on reading this.
>
> The reference docs for wl_surface::attach say,
>
>  Surface contents are double-buffered state, see wl_surface.commit.
>

This means that state such as the buffer set with the attach request
is double buffered, that is it becomes the active state after a
commit(). It doesn't mean the surface has two buffers, the state is
double buffered, not the buffer. You can attach a different buffer
each time, or prerender an animation completely upfront and then feed
the compositor all the buffers you have one by one, that is a client
choice only.

> Most of the other wl_surface requests similarly mention double-buffered
> surfaces.  Nothing there discusses single-buffers, and nothing describes
> a multi-buffered state, although wl_surface::commit includes this
> (rather ambiguous) statement:
>
>  Other interfaces may add further double-buffered surface state.
>
> (Whatever this actually means, it probably should be elaborated on.)

It means other protocol extensions may add more state that becomes
active when the user calls commit(). As an example, i think the
geometry set in xdg_shell with xdg_surface.set_window_geometry is
double buffered.

>
> It's possible I've missed something or I'm just dumb, but if >2 buffers
> is a thing that should be documented to users, then I'd expect the
> reference docs to cover it.
>
>> > > +      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.
>> >
>>
>> It might also be nice to clarify that this can happen at any time:
>> instantly (i.e. copying into a shadow buffer, such as SHM buffers on GL/RPi
>> renderers), immediately on the next attach/commit (i.e. a renderer with no
>> scanout promotion that does a blit for final presentation, such as GL
>> buffers on GL renderer), or sometime later (buffer promoted directly to
>> scanout, such as a DRM/atomic backend). But ideally without reference to
>> those specific cases, as they're really just implementation details that
>> can change.
>
> Alright, I've rephrased this - hopefully not butchering the meaning in
> the process.  Please review my updated patch, which i'll post directly.
>
> Thanks for the review (and explanations of how things work!)
>
> Bryce
I think talking about a surface having multiple buffers is misleading.

A wl_surface only knows about one buffer after commit: the last buffer 
attached to it. The wording being proposed here makes it sound like the 
surface keeps track of the previous buffer and expects or requires it to 
be used in the next attach.

I think the problem with the docs right now is that a lot of wl_surface 
requests say "foo is double-buffered state, see wl_surface.commit". The 
word double-buffered unfortunately immediately makes people think only 
about pixel buffers, even though in fact it is other data that is being 
double-buffered.

I would avoid the use of the term "double buffered". Possible 
alternative: "The change does not happen until the next 
wl_surface.commit." All current talk about double-buffering in commit 
should use words like "deferred" or "pending" instead.
Hi,

On Friday, December 12, 2014, Bill Spitzak <spitzak@gmail.com> wrote:

> I think talking about a surface having multiple buffers is misleading.
>
> A wl_surface only knows about one buffer after commit: the last buffer
> attached to it. The wording being proposed here makes it sound like the
> surface keeps track of the previous buffer and expects or requires it to be
> used in the next attach.


This is technically true, but I think helpful for the introduction.


> I think the problem with the docs right now is that a lot of wl_surface
> requests say "foo is double-buffered state, see wl_surface.commit". The
> word double-buffered unfortunately immediately makes people think only
> about pixel buffers, even though in fact it is other data that is being
> double-buffered.
>
> I would avoid the use of the term "double buffered". Possible alternative:
> "The change does not happen until the next wl_surface.commit." All current
> talk about double-buffering in commit should use words like "deferred" or
> "pending" instead.
>

Or 'latched'. Either way, I think 'double-buffered' referring to the
surface state updated on commit has to go.

Cheers,
Danirl
On Fri, 12 Dec 2014 20:29:29 +0000
Daniel Stone <daniel@fooishbar.org> wrote:

> Hi,
> 
> On Friday, December 12, 2014, Bill Spitzak <spitzak@gmail.com> wrote:
> 
> > I think talking about a surface having multiple buffers is misleading.
> >
> > A wl_surface only knows about one buffer after commit: the last buffer
> > attached to it. The wording being proposed here makes it sound like the
> > surface keeps track of the previous buffer and expects or requires it to be
> > used in the next attach.
> 
> 
> This is technically true, but I think helpful for the introduction.
> 
> 
> > I think the problem with the docs right now is that a lot of wl_surface
> > requests say "foo is double-buffered state, see wl_surface.commit". The
> > word double-buffered unfortunately immediately makes people think only
> > about pixel buffers, even though in fact it is other data that is being
> > double-buffered.
> >
> > I would avoid the use of the term "double buffered". Possible alternative:
> > "The change does not happen until the next wl_surface.commit." All current
> > talk about double-buffering in commit should use words like "deferred" or
> > "pending" instead.
> >
> 
> Or 'latched'. Either way, I think 'double-buffered' referring to the
> surface state updated on commit has to go.

I would be fine with that change. I started using the "double-buffered
state" term when nothing better came to my mind. After all, display
hardware can have double-buffered registers, etc. Yes, a latch.

All I want is that there is a single term which we use consistenly to
mean that wl_surface.foo(x) only readies the foo=x assignment in the
server, and the wl_surface.commit() actually makes it happen atomically
with all the other similar state for this wl_surface.


Thanks,
pq
On 12/19/2014 04:25 AM, Pekka Paalanen wrote:
> On Fri, 12 Dec 2014 20:29:29 +0000
> Daniel Stone <daniel@fooishbar.org> wrote:
> 
>> Hi,
>>
>> On Friday, December 12, 2014, Bill Spitzak <spitzak@gmail.com> wrote:
>>

...

>>> I would avoid the use of the term "double buffered". Possible alternative:
>>> "The change does not happen until the next wl_surface.commit." All current
>>> talk about double-buffering in commit should use words like "deferred" or
>>> "pending" instead.
>>>
>>
>> Or 'latched'. Either way, I think 'double-buffered' referring to the
>> surface state updated on commit has to go.
> 
> I would be fine with that change. I started using the "double-buffered
> state" term when nothing better came to my mind. After all, display
> hardware can have double-buffered registers, etc. Yes, a latch.
> 
> All I want is that there is a single term which we use consistenly to
> mean that wl_surface.foo(x) only readies the foo=x assignment in the
> server, and the wl_surface.commit() actually makes it happen atomically
> with all the other similar state for this wl_surface.
> 

In general that sounds like the general use case for "transaction" and
"commit" as terms. So we might have "Foo is added to the pending state
transaction".