[PATCH wayland 2/2] protocol: Refine wl_surface.commit text

[Pekka Paalanen]

On Fri, 20 Nov 2015 15:49:59 -0600
Derek Foreman <derekf at osg.samsung.com> wrote:

> The order of operations during wl_surface.commit hasn't been clarified
> since wp_viewport, wl_surface.set_buffer_transform and
> wl_surface.set_buffer_scale were added.
> 
> Explain that any state that changes co-ordinates is applied first, and
> that unchanged co-ordinate altering state is held over from previous
> commits.
> 
> Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
> ---
> 
> Instead of putting this in the damage_buffer commit I figured I'd
> try to keep it separate.  I think we can paint this bike shed
> independently, and don't need to hold up the weston damage_buffer
> implementation for it?
> 
> I'll happily squash the two patches if that's unreasonable.

Hi Derek,

no, keeping them separate is good.

>  protocol/wayland.xml | 15 ++++++++++-----
>  1 file changed, 10 insertions(+), 5 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 4d75f39..3cd440f 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1229,11 +1229,16 @@
>  	state. After commit, the new pending state is as documented for each
>  	related request.
>  
> -	On commit, a pending wl_buffer is applied first, all other state
> -	second. This means that all coordinates in double-buffered state are
> -	relative to the new wl_buffer coming into use, except for
> -	wl_surface.attach itself. If there is no pending wl_buffer, the
> -	coordinates are relative to the current surface contents.
> +	On commit, a pending wl_buffer is applied first.  State which
> +	affects the buffer to surface co-ordinate conversion (such as
> +	wp_viewport or buffer scale and transform) should be applied next.

> +	These bits of state are carried over from the previous commit if
> +	the current commit doesn't replace them.

Is this not already said for the requests that change those parameters,
along with the default value?

> +
> +	All other state follows. This means that all coordinates in
> +	double-buffered state are relative to the new wl_buffer and
> +	its associated transformations, except for wl_surface.attach
> +	itself.

Yes... the dx,dy of attach are curious. They are defined in surface
coordinates, but it talks about buffers, because talking about a new
surface made no sense. Maybe it should have talked about moving the
surface, but OTOH we don't want dx,dy to be abused for moving surfaces
but used only for moving the top-left corner due to resize.

>  
>  	All requests that need a commit to become effective are documented
>  	to affect double-buffered state.

I'm not sure if the text here is clear enough. What happens on commit
is the following:

1. The position of the surface's top-left corner gets determined by
   taking the old position and adding dx,dy from wl_surface.attach
   to it. The dx,dy are given in (old) surface coordinates.

2. The surface contents are assigned from the wl_buffer (take a
   busy-ref on the wl_buffer).

3. The surface-buffer transformation is determined from all parameters
   affecting it.

4. The surface size is determined from the surface-buffer
   transformation and the buffer size.

5. Damage, opaque, and input regions are clipped to the surface size.

6. wl_surface.frame and presentation.feedback callbacks are scheduled.


Looking at Weston's code, it doesn't go exactly in this order, but the
interactions are the same:
 
- The dx,dy or surface position are not affected by the surface-buffer
  transformation.

- Surface size depends on the surface-buffer transformation and
  buffer size.

- Regions are clipped to the resulting surface size, not the old size.


Now, I wrote most of the above offhand, so if something in the spec or
implementations contradicts this, it would be nice to point out.

How to put this all in the spec...


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/da7c2ce7/attachment.sig>