[PATCH v3 wayland 1/2] protocol: Add wl_surface.damage_buffer

[Pekka Paalanen]

On Fri, 20 Nov 2015 15:49:58 -0600
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.damage_buffer 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.damage_buffer request
> was another option.
> 
> This will eventually resolve:
> https://bugs.freedesktop.org/show_bug.cgi?id=78190
> by making the problem irrelevant.
> 
> Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
> ---
> 
> New change: Explain that damages can't be combined until commit
> 
> Also, copy the new wl_surface.damage text that doesn't require attach
> to be before damage
> 
> (enough text is new that I haven't carried over any RBs)
> 
>  protocol/wayland.xml | 48 ++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 46 insertions(+), 2 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 525e092..4d75f39 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.
> @@ -1109,6 +1109,10 @@
>  	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.
> +
> +	Alternatively, damage can be posted with wl_surface.damage_buffer
> +	which uses buffer co-ordinates instead of surface co-ordinates,
> +	and is probably the preferred and intuitive way of doing this.
>        </description>
>  
>        <arg name="x" type="int"/>
> @@ -1325,6 +1329,46 @@
>        </description>
>        <arg name="scale" type="int"/>
>      </request>
> +
> +    <!-- Version 4 additions -->
> +    <request name="damage_buffer" 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 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_buffer 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.  While this generally is more intuitive than surface
> +	co-ordinates, it is especially desirable when using wp_viewport
> +	or when a drawing library (like EGL) is unaware of buffer scale
> +	and buffer transform.
> +
> +	Since it is impossible to convert between buffer and surface
> +	co-ordinates until the late stages of wl_surface.commit,
> +	damage from wl_surface.damage and wl_surace.damage_buffer must
> +	be accumulated separately and only combined during
> +	wl_surface.commit.

Hi,

yeah, this is pretty good now.

The last paragraph is aimed at compositor writers, so it should mention
compositor or server.

"Late stages" is also a bit vague, I think we could be more explcit
there.

How about:

	Since it is impossible to convert between buffer and surface
	co-ordinates until all the possible parameters affecting the
	surface size and the buffer-surface mapping are known at
	wl_surface.commit time, damage from wl_surface.damage and
	wl_surface.damage_buffer must be accumulated separately in a
	compositor and combined during wl_surface.commit the earliest.

I'm also reserving the right to not combine the damages at commit but
later, which might perhaps be useful once the buffer queueing extension
is revived.

> +      </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">

But that's just minor adjustment of the wording. The definition looks
good.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151126/ab4d6142/attachment.sig>