[PATCH wayland v2] doc: Fill in high level description for Surfaces
bryce at osg.samsung.com
Fri Dec 12 11:40:01 PST 2014
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
@@ -282,13 +282,39 @@
- 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
+ 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
+ the global position of their surfaces. Importantly, clients
cannot access other clients surfaces.
- See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
+ The data for the grid of pixels is stored in a wl_buffer object.
+ 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
+ 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.
+ 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.
+ See <xref linkend="protocol-spec-interface-wl_surface"/> for the
+ protocol description.
More information about the wayland-devel