mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-11-27 06:59:51 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Improve wl_shm and wl_shm_pool protocol docs

Browse source 
Reword some paragraphs, and spell out 'file descriptor'.
This commit is contained in:
Matthias Clasen 2013-03-30 01:11:36 -04:00 • committed by Kristian Høgsberg
parent c84155d475
commit b02e58c718
1 changed files with 49 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

73
protocol/wayland.xml
View file

@ -196,20 +196,21 @@
The wl_shm_pool object encapsulates a piece of memory shared The wl_shm_pool object encapsulates a piece of memory shared
between the compositor and client. Through the wl_shm_pool between the compositor and client. Through the wl_shm_pool
object, the client can allocate shared memory wl_buffer objects. object, the client can allocate shared memory wl_buffer objects.
The objects will share the same underlying mapped memory. All objects created through the same pool share the same
Reusing the mapped memory avoids the setup/teardown overhead and underlying mapped memory. Reusing the mapped memory avoids the
is useful when interactively resizing a surface or for many setup/teardown overhead and is useful when interactively resizing
small buffers. a surface or for many small buffers.
</description> </description>
<request name="create_buffer"> <request name="create_buffer">
<description summary="create wl_buffer from pool"> <description summary="create a buffer from the pool">
Create a wl_buffer from the pool. The buffer is created a Create a wl_buffer object from the pool.
offset bytes into the pool and has width and height as
specified. The stride arguments specifies the number of bytes The buffer is created offset bytes into the pool and has
from beginning of one row to the beginning of the next. The width and height as specified. The stride arguments specifies
format is the pixel format of the buffer and must be one of the number of bytes from beginning of one row to the beginning
those advertised through the wl_shm.format event. 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 A buffer will keep a reference to the pool it was created from
so it is valid to destroy the pool immediately after creating so it is valid to destroy the pool immediately after creating
@ -226,15 +227,19 @@
<request name="destroy" type="destructor"> <request name="destroy" type="destructor">
<description summary="destroy the pool"> <description summary="destroy the pool">
Destroy the pool. Destroy the shared memory pool.
The mmapped memory will be released when all
buffers that have been created from this pool
are gone.
</description> </description>
</request> </request>
<request name="resize"> <request name="resize">
<description summary="change the size of the pool mapping"> <description summary="change the size of the pool mapping">
This request will cause the server to remap the backing memory This request will cause the server to remap the backing memory
for the pool from the fd passed when the pool was creating but for the pool from the file descriptor passed when the pool was
using the new size. created, but using the new size.
</description> </description>
<arg name="size" type="int"/> <arg name="size" type="int"/>
@ -243,26 +248,41 @@
<interface name="wl_shm" version="1"> <interface name="wl_shm" version="1">
<description summary="shared memory support"> <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> </description>
<enum name="error"> <enum name="error">
<entry name="invalid_format" value="0"/> <description summary="wl_shm error values">
<entry name="invalid_stride" value="1"/> These errors can be emitted in response to wl_shm requests.
<entry name="invalid_fd" value="2"/> </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>
<enum name="format"> <enum name="format">
<entry name="argb8888" value="0"/> <description summary="pixel formats">
<entry name="xrgb8888" value="1"/> 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> </enum>
<request name="create_pool"> <request name="create_pool">
<description summary="create a shm pool"> <description summary="create a shm pool">
This creates wl_shm_pool object, which can be used to create Create a new wl_shm_pool object.
shared memory based wl_buffer objects. The server will mmap
size bytes of the passed fd, to use as backing memory for then The pool can be used to create shared memory based buffer
pool. objects. The server will mmap size bytes of the passed file
descriptor, to use as backing memory for the pool.
</description> </description>
<arg name="id" type="new_id" interface="wl_shm_pool"/> <arg name="id" type="new_id" interface="wl_shm_pool"/>
@ -271,6 +291,11 @@
</request> </request>
<event name="format"> <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.
</description>
<arg name="format" type="uint"/> <arg name="format" type="uint"/>
</event> </event>
</interface> </interface>