Re: [PATCH 13/21] docs: Improve wl_surface protocol docs
Looks good! --Jason Ekstrand On Mar 30, 2013 12:24 AM, wrote: > From: Matthias Clasen > > Use NULL consistently. And add some more information in a few > places. > --- > protocol/wayland.xml | 123 > +-- > 1 file changed, 69 insertions(+), 54 deletions(-) > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml > index a3599f0..3e674f3 100644 > --- a/protocol/wayland.xml > +++ b/protocol/wayland.xml > @@ -874,48 +874,54 @@ > > > > - A surface. This is an image that is displayed on the screen. > + A surface is a rectangular area that is displayed on the screen. >It has a location, size and pixel contents. > + > + Surfaces are also used for some special purposes, e.g. as > + cursor images for pointers, drag icons, etc. > > > > > - Deletes the surface and invalidates its object id. > + Deletes the surface and invalidates its object ID. > > > > > > - Set the contents of a buffer into this surface. The x and y > - arguments specify the location of the new pending buffer's upper > - left corner, relative to the current buffer's upper left corner. In > - other words, the x and y, and the width and height of the wl_buffer > - together define in which directions the surface's size changes. > + Set a buffer as the content of this surface. > + > + The x and y arguments specify the location of the new pending > + buffer's upper left corner, relative to the current buffer's > + upper left corner. In other words, the x and y, and the width > + and height of the wl_buffer together define in which directions > + the surface's size changes. > > Surface contents are double-buffered state, see wl_surface.commit. > > The initial surface contents are void; there is no content. > - wl_surface.attach assigns the given wl_buffer as the pending > wl_buffer. > - wl_surface.commit makes the pending wl_buffer the new > + wl_surface.attach assigns the given wl_buffer as the pending > + wl_buffer. wl_surface.commit makes the pending wl_buffer the new > surface contents, and the size of the surface becomes the size of > - the wl_buffer. After commit, there is no pending buffer until the > - next attach. > + the wl_buffer, as described above. After commit, there is no > + pending buffer until the next attach. > > Committing a pending wl_buffer allows the compositor to read the > - pixels in the wl_buffer. The compositor may access the pixels at > any > - time after the wl_surface.commit request. When the compositor will > - not access the pixels anymore, it will send the wl_buffer.release > - event. Only after receiving wl_buffer.release, the client may > re-use > - the wl_buffer. A wl_buffer, that has been attached and then > replaced > - by another attach instead of committed, will not receive a release > - event, and is not used by the compositor. > - > - Destroying the wl_buffer after wl_buffer.release does not change > the > - surface contents. However, if the client destroys the wl_buffer > - before receiving wl_buffer.release, the surface contents become > - undefined immediately. > - > - Only if wl_surface.attach is sent with a nil wl_buffer, the > + pixels in the wl_buffer. The compositor may access the pixels at > + any time after the wl_surface.commit request. When the compositor > + will not access the pixels anymore, it will send the > + wl_buffer.release event. Only after receiving wl_buffer.release, > + the client may re-use the wl_buffer. A wl_buffer that has been > + attached and then replaced by another attach instead of committed > + will not receive a release event, and is not used by the > + compositor. > + > + Destroying the wl_buffer after wl_buffer.release does not change > + the surface contents. However, if the client destroys the > + wl_buffer before receiving wl_buffer.release, the surface > + contents become undefined immediately. > + > + Only if wl_surface.attach is sent with a NULL wl_buffer, the > following wl_surface.commit will remove the surface content. > > > @@ -928,18 +934,20 @@ > > This request is used to describe the regions where the pending > buffer is different from the current surface contents, and where > - the surface therefore needs to be repainted. The pending buffer > must > - be set by wl_surface.attach before sending damage. The compositor > - ignores the parts of the damage that fall outside of the surface. > + the surface therefore needs to be repainted. The pending buffer > + must be set by wl_surface.attach before sending damage. The > + compositor ignores the parts
[PATCH 13/21] docs: Improve wl_surface protocol docs
From: Matthias Clasen Use NULL consistently. And add some more information in a few places. --- protocol/wayland.xml | 123 +-- 1 file changed, 69 insertions(+), 54 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index a3599f0..3e674f3 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -874,48 +874,54 @@ - A surface. This is an image that is displayed on the screen. + A surface is a rectangular area that is displayed on the screen. It has a location, size and pixel contents. + + Surfaces are also used for some special purposes, e.g. as + cursor images for pointers, drag icons, etc. - Deletes the surface and invalidates its object id. + Deletes the surface and invalidates its object ID. - Set the contents of a buffer into this surface. The x and y - arguments specify the location of the new pending buffer's upper - left corner, relative to the current buffer's upper left corner. In - other words, the x and y, and the width and height of the wl_buffer - together define in which directions the surface's size changes. + Set a buffer as the content of this surface. + + The x and y arguments specify the location of the new pending + buffer's upper left corner, relative to the current buffer's + upper left corner. In other words, the x and y, and the width + and height of the wl_buffer together define in which directions + the surface's size changes. Surface contents are double-buffered state, see wl_surface.commit. The initial surface contents are void; there is no content. - wl_surface.attach assigns the given wl_buffer as the pending wl_buffer. - wl_surface.commit makes the pending wl_buffer the new + wl_surface.attach assigns the given wl_buffer as the pending + wl_buffer. wl_surface.commit makes the pending wl_buffer the new surface contents, and the size of the surface becomes the size of - the wl_buffer. After commit, there is no pending buffer until the - next attach. + the wl_buffer, as described above. After commit, there is no + pending buffer until the next attach. Committing a pending wl_buffer allows the compositor to read the - pixels in the wl_buffer. The compositor may access the pixels at any - time after the wl_surface.commit request. When the compositor will - not access the pixels anymore, it will send the wl_buffer.release - event. Only after receiving wl_buffer.release, the client may re-use - the wl_buffer. A wl_buffer, that has been attached and then replaced - by another attach instead of committed, will not receive a release - event, and is not used by the compositor. - - Destroying the wl_buffer after wl_buffer.release does not change the - surface contents. However, if the client destroys the wl_buffer - before receiving wl_buffer.release, the surface contents become - undefined immediately. - - Only if wl_surface.attach is sent with a nil wl_buffer, the + pixels in the wl_buffer. The compositor may access the pixels at + any time after the wl_surface.commit request. When the compositor + will not access the pixels anymore, it will send the + wl_buffer.release event. Only after receiving wl_buffer.release, + the client may re-use the wl_buffer. A wl_buffer that has been + attached and then replaced by another attach instead of committed + will not receive a release event, and is not used by the + compositor. + + Destroying the wl_buffer after wl_buffer.release does not change + the surface contents. However, if the client destroys the + wl_buffer before receiving wl_buffer.release, the surface + contents become undefined immediately. + + Only if wl_surface.attach is sent with a NULL wl_buffer, the following wl_surface.commit will remove the surface content. @@ -928,18 +934,20 @@ This request is used to describe the regions where the pending buffer is different from the current surface contents, and where - the surface therefore needs to be repainted. The pending buffer must - be set by wl_surface.attach before sending damage. The compositor - ignores the parts of the damage that fall outside of the surface. + the surface therefore needs to be repainted. The pending buffer + must be set by wl_surface.attach before sending damage. The + compositor ignores the parts of the damage that fall outside of + the surface. Damage is double-buffered state, see wl_surface.commit. The initial value for pending damage is empty: no damage. - wl_surface.damage adds pending damage: the new pending damage is the
