On Sat, Mar 30, 2013 at 12:11 AM, <matthias.cla...@gmail.com> wrote: > From: Matthias Clasen <mcla...@redhat.com> > > Reword some paragraphs, and spell out 'file descriptor'. > --- > protocol/wayland.xml | 73 > +++++++++++++++++++++++++++++++++++----------------- > 1 file changed, 49 insertions(+), 24 deletions(-) > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml > index cc009eb..31d7ce8 100644 > --- a/protocol/wayland.xml > +++ b/protocol/wayland.xml > @@ -196,20 +196,21 @@ > The wl_shm_pool object encapsulates a piece of memory shared > between the compositor and client. Through the wl_shm_pool > object, the client can allocate shared memory wl_buffer objects. > - The objects will share the same underlying mapped memory. > - Reusing the mapped memory avoids the setup/teardown overhead and > - is useful when interactively resizing a surface or for many > - small buffers. > + All objects created through the same pool share the same > + underlying mapped memory. Reusing the mapped memory avoids the > + setup/teardown overhead and is useful when interactively resizing > + a surface or for many small buffers.
Perhaps "All wl_buffer objects" would be better > </description> > > <request name="create_buffer"> > - <description summary="create wl_buffer from pool"> > - Create a wl_buffer from the pool. The buffer is created a > - offset bytes into the pool and has width and height as > - specified. The stride arguments specifies the number of bytes > - from beginning of one row to the beginning of the next. The > - format is the pixel format of the buffer and must be one of > - those advertised through the wl_shm.format event. > + <description summary="create a buffer from the pool"> > + Create a wl_buffer object from the pool. Should go in summary > + > + The buffer is created offset bytes into the pool and has > + width and height as specified. The stride arguments specifies > + the number of bytes from beginning of one row to the beginning > + of the next. The format is the pixel format of the buffer and > + must be one of those advertised through the wl_shm.format event. > > A buffer will keep a reference to the pool it was created from > so it is valid to destroy the pool immediately after creating > @@ -226,15 +227,19 @@ > > <request name="destroy" type="destructor"> > <description summary="destroy the pool"> > - Destroy the pool. > + Destroy the shared memory pool. Summary > + > + The mmapped memory will be released when all > + buffers that have been created from this pool > + are gone. > </description> > </request> > > <request name="resize"> > <description summary="change the size of the pool mapping"> > This request will cause the server to remap the backing memory > - for the pool from the fd passed when the pool was creating but > - using the new size. > + for the pool from the file descriptor passed when the pool was > + created, but using the new size. > </description> > > <arg name="size" type="int"/> > @@ -243,26 +248,41 @@ > > <interface name="wl_shm" version="1"> > <description summary="shared memory support"> > - Support for shared memory buffers. > + A global singleton object that provides support for shared > + memory. > + > + Clients can create wl_shm_pool objects using the create_pool > + request. > + > + At connection setup time, the wl_shm object emits one or more > + format events to inform clients about the valid pixel formats > + that can be used for buffers. > </description> > > <enum name="error"> > - <entry name="invalid_format" value="0"/> > - <entry name="invalid_stride" value="1"/> > - <entry name="invalid_fd" value="2"/> > + <description summary="wl_shm error values"> > + These errors can be emitted in response to wl_shm requests. > + </description> > + <entry name="invalid_format" value="0" summary="buffer format is not > known"/> > + <entry name="invalid_stride" value="1" summary="invalid size or stride > during pool or buffer creation"/> > + <entry name="invalid_fd" value="2" summary="mmapping the file > descriptor failed"/> > </enum> > > <enum name="format"> > - <entry name="argb8888" value="0"/> > - <entry name="xrgb8888" value="1"/> > + <description summary="pixel formats"> > + This describes the memory layout of an individual pixel. > + </description> > + <entry name="argb8888" value="0" summary="32-bit ARGB format"/> > + <entry name="xrgb8888" value="1" summary="32-bit RGB format"/> > </enum> > > <request name="create_pool"> > <description summary="create a shm pool"> > - This creates wl_shm_pool object, which can be used to create > - shared memory based wl_buffer objects. The server will mmap > - size bytes of the passed fd, to use as backing memory for then > - pool. > + Create a new wl_shm_pool object. summary > + > + The pool can be used to create shared memory based buffer > + objects. The server will mmap size bytes of the passed file > + descriptor, to use as backing memory for the pool. > </description> > > <arg name="id" type="new_id" interface="wl_shm_pool"/> > @@ -271,6 +291,11 @@ > </request> > > <event name="format"> > + <description summary="pixel format description"> > + Informs the client about a valid pixel format that > + can be used for buffers. Known formats include > + argb8888 and xrgb8888. We don't want to put known formats here. Those will be documented in the formats enum. Documenting them here only makes for more documentation to keep up-to-date. > + </description> > <arg name="format" type="uint"/> > </event> > </interface> > -- > 1.8.1.4 > > _______________________________________________ > wayland-devel mailing list > wayland-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel