[PATCH 13/21] docs: Improve wl_surface protocol docs

Jason Ekstrand jason at jlekstrand.net
Mon Apr 1 09:41:12 PDT 2013


Looks good!
--Jason Ekstrand
On Mar 30, 2013 12:24 AM, <matthias.clasen at gmail.com> wrote:

> From: Matthias Clasen <mclasen at redhat.com>
>
> 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 @@
>
>    <interface name="wl_surface" version="2">
>      <description summary="an onscreen surface">
> -      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.
>      </description>
>
>      <request name="destroy" type="destructor">
>        <description summary="delete surface">
> -       Deletes the surface and invalidates its object id.
> +       Deletes the surface and invalidates its object ID.
>        </description>
>      </request>
>
>      <request name="attach">
>        <description summary="set the surface contents">
> -       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.
>        </description>
>
> @@ -928,18 +934,20 @@
>        <description summary="mark part of the surface damaged">
>         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
> -       union of old pending damage and the given rectangle.
> -       wl_surface.commit assigns pending damage as the current damage, and
> -       clears pending damage. The server will clear the current damage as
> -       it repaints the surface.
> +       wl_surface.damage adds pending damage: the new pending damage
> +       is the union of old pending damage and the given rectangle.
> +
> +       wl_surface.commit assigns pending damage as the current damage,
> +       and clears pending damage. The server will clear the current
> +       damage as it repaints the surface.
>        </description>
>
>        <arg name="x" type="int"/>
> @@ -972,11 +980,14 @@
>      <request name="set_opaque_region">
>        <description summary="set opaque region">
>         This request sets the region of the surface that contains
> -       opaque content.  The opaque region is an optimization hint for
> -       the compositor that lets it optimize out redrawing of content
> -       behind opaque regions.  Setting an opaque region is not
> -       required for correct behaviour, but marking transparent
> -       content as opaque will result in repaint artifacts.
> +       opaque content.
> +
> +       The opaque region is an optimization hint for the compositor
> +       that lets it optimize out redrawing of content behind opaque
> +       regions.  Setting an opaque region is not required for correct
> +       behaviour, but marking transparent content as opaque will result
> +       in repaint artifacts.
> +
>         The compositor ignores the parts of the opaque region that fall
>         outside of the surface.
>
> @@ -984,11 +995,11 @@
>
>         wl_surface.set_opaque_region changes the pending opaque region.
>         wl_surface.commit copies the pending region to the current region.
> -       Otherwise the pending and current regions are never changed.
> +       Otherwise, the pending and current regions are never changed.
>
>         The initial value for opaque region is empty. Setting the pending
>         opaque region has copy semantics, and the wl_region object can be
> -       destroyed immediately. A nil wl_region causes the pending opaque
> +       destroyed immediately. A NULL wl_region causes the pending opaque
>         region to be set to empty.
>        </description>
>
> @@ -998,10 +1009,11 @@
>      <request name="set_input_region">
>        <description summary="set input region">
>         This request sets the region of the surface that can receive
> -       pointer and touch events. Input events happening outside of
> -       this region will try the next surface in the server surface
> -       stack. The compositor ignores the parts of the input region that
> -       fall outside of the surface.
> +       pointer and touch events.
> +
> +       Input events happening outside of this region will try the next
> +       surface in the server surface stack. The compositor ignores the
> +       parts of the input region that fall outside of the surface.
>
>         Input region is double-buffered state, see wl_surface.commit.
>
> @@ -1011,10 +1023,11 @@
>         except cursor and icon surfaces are special cases, see
>         wl_pointer.set_cursor and wl_data_device.start_drag.
>
> -       The initial value for input region is infinite. That means the
> whole
> -       surface will accept input. Setting the pending input region has
> copy
> -       semantics, and the wl_region object can be destroyed immediately. A
> -       nil wl_region causes the input region to be set to infinite.
> +       The initial value for input region is infinite. That means the
> +       whole surface will accept input. Setting the pending input region
> +       has copy semantics, and the wl_region object can be destroyed
> +       immediately. A NULL wl_region causes the input region to be set
> +       to infinite.
>        </description>
>
>        <arg name="region" type="object" interface="wl_region"
> allow-null="true"/>
> @@ -1044,18 +1057,20 @@
>
>      <event name="enter">
>        <description summary="surface enters an output">
> -        This is emitted whenever a surface's creation, movement, or
> resizing
> -        results in some part of it being within the scanout region of an
> -        output.
> +       This is emitted whenever a surface's creation, movement, or
> resizing
> +       results in some part of it being within the scanout region of an
> +       output.
> +
> +       Note that a surface may be overlapping with zero or more outputs.
>        </description>
>        <arg name="output" type="object" interface="wl_output"/>
>      </event>
>
>      <event name="leave">
>        <description summary="surface leaves an output">
> -        This is emitted whenever a surface's creation, movement, or
> resizing
> -        results in it no longer having any part of it within the scanout
> region
> -        of an output.
> +       This is emitted whenever a surface's creation, movement, or
> resizing
> +       results in it no longer having any part of it within the scanout
> region
> +       of an output.
>        </description>
>        <arg name="output" type="object" interface="wl_output"/>
>      </event>
> --
> 1.8.1.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130401/7e6982b0/attachment-0001.html>


More information about the wayland-devel mailing list