[PATCH] doc: Fill in high level description for Surfaces
bryce at osg.samsung.com
Sat Dec 13 06:51:47 AEDT 2014
Sorry, sorry, sorry for the misfire! Please ignore this patch.
(and thanks for patchwork!)
On Fri, Dec 12, 2014 at 11:38:58AM -0800, Bryce Harrington 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">
> - 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
> - description.
> + 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.
> + </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.
> + </para>
> + <para>
> + See <xref linkend="protocol-spec-interface-wl_surface"/> for the
> + protocol description.
> <section id="sect-Protocol-Input">
More information about the Patchwork