[RFC wayland] protocol: Add wl_surface.buffer_damage

[Jasper St. Pierre]

To help clear things up, I think we should deprecate the
wl_surface.damage request and document that the coordinates are
effectively undefined -- for legacy reasons, if you see
wl_surface.damage, it should be considered a damage for the entire
surface.

On Fri, Nov 6, 2015 at 10:55 AM, Derek Foreman <derekf at osg.samsung.com> wrote:
> wl_surface.damage uses surface local co-ordinates.
>
> Buffer scale and buffer transforms came along, and EGL surfaces
> have no understanding of them.
>
> Theoretically, clients pass damage rectangles - in Y-inverted surface
> co-ordinates) to EGLSwapBuffersWithDamage, and the EGL implementation
> passed them on to wayland.  However, for this to work the EGL
> implementation must be able to flip those rectangles into the space
> the compositor is expecting, but it's unable to do so because it
> doesn't know the height of the transformed buffer.
>
> So, currently, EGLSwapBuffersWithDamage is unusable and EGLSwapBuffers
> has to pass (0,0) - (INT32_MAX, INT32_MAX) damage to function.
>
> wl_surface.buffer_damage allows damage to be registered on a surface
> in buffer co-ordinates, avoiding this problem.
>
> Credit where it's due, these ideas are not entirely my own:
> Over a year ago the idea of changing damage co-ordinates to buffer
> co-ordinates was suggested (by Jason Ekstrand), and it was at least
> partially rejected and abandoned.  At the time it was also suggested
> (by Pekka Paalanen) that adding a new wl_surface.buffer_damage request
> was another option.
>
> Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
> ---
>
> Necro-posting on:
> http://lists.freedesktop.org/archives/wayland-devel/2014-February/013440.html
> and
> http://lists.freedesktop.org/archives/wayland-devel/2014-February/013442.html
>
> This came up on IRC again the other day, and it's still an unsolved problem...
> I'm posting this as RFC to see if anyone's interested in it - I'll do an
> implementation if we can get an agreement on the protocol text.
>
>  protocol/wayland.xml | 44 ++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 42 insertions(+), 2 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 9c22d45..1cb2f66 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -176,7 +176,7 @@
>      </event>
>    </interface>
>
> -  <interface name="wl_compositor" version="3">
> +  <interface name="wl_compositor" version="4">
>      <description summary="the compositor singleton">
>        A compositor.  This object is a singleton global.  The
>        compositor is in charge of combining the contents of multiple
> @@ -986,7 +986,7 @@
>      </event>
>    </interface>
>
> -  <interface name="wl_surface" version="3">
> +  <interface name="wl_surface" version="4">
>      <description summary="an onscreen surface">
>        A surface is a rectangular area that is displayed on the screen.
>        It has a location, size and pixel contents.
> @@ -1327,6 +1327,46 @@
>        </description>
>        <arg name="scale" type="int"/>
>      </request>
> +
> +    <!-- Version 4 additions -->
> +    <request name="buffer_damage" since="4">
> +      <description summary="mark part of the surface damaged using buffer co-ordinates">
> +       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.
> +
> +       Damage is double-buffered state, see wl_surface.commit.
> +
> +       The damage rectangle is specified in buffer coordinates.
> +
> +       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.
> +
> +       This request differs from wl_surface.damage in only one way - it
> +       takes damage in buffer co-ordinates instead of surface local
> +       co-ordinates.  This is desirable because EGL implementations
> +       are unaware of buffer scale and buffer transform and can only
> +       provide damage in buffer co-ordinates.  Damage in buffer
> +       co-ordinates is required for EGLSwapBuffersWithDamage to work
> +       efficiently.
> +
> +       Mixing wl_surface.buffer_damage and wl_surface.damage requests
> +       on the same surface will result in undefined behaviour.
> +      </description>
> +
> +      <arg name="x" type="int"/>
> +      <arg name="y" type="int"/>
> +      <arg name="width" type="int"/>
> +      <arg name="height" type="int"/>
> +    </request>
>     </interface>
>
>    <interface name="wl_seat" version="5">
> --
> 2.6.1
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel



-- 
  Jasper