[PATCH weston 1/6] protocol: improve sub-surface spec wording

[Kristian Høgsberg]

On Mon, May 20, 2013 at 08:33:53AM +0300, Pekka Paalanen wrote:
> On Fri, 17 May 2013 16:20:48 -0400
> Kristian Høgsberg <hoegsberg at gmail.com> wrote:
> 
> > On Fri, May 17, 2013 at 04:46:03PM +0300, ppaalanen at gmail.com wrote:
> > > From: Pekka Paalanen <ppaalanen at gmail.com>
> > > 
> > > Mention, that sub-surfaces are not clipped to the parent.
> > > Be more accurate on surface commit vs. apply state.
> > > Mention the initial stacking order.
> > 
> > That looks good, applied.
> 
> Hmm, I see the other patches, but not this particular patch in upstream
> master. What happened?

Yeah, good question... upstream now.

Kristian


> Thanks,
> pq
> 
> > 
> > > Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> > > ---
> > >  protocol/subsurface.xml | 27 +++++++++++++++++----------
> > >  1 file changed, 17 insertions(+), 10 deletions(-)
> > > 
> > > diff --git a/protocol/subsurface.xml b/protocol/subsurface.xml
> > > index 60b4002..71dc1e9 100644
> > > --- a/protocol/subsurface.xml
> > > +++ b/protocol/subsurface.xml
> > > @@ -87,7 +87,10 @@
> > >    <interface name="wl_subsurface" version="1">
> > >      <description summary="sub-surface interface to a wl_surface">
> > >        An additional interface to a wl_surface object, which has been
> > > -      made a sub-surface. A sub-surface has one parent surface.
> > > +      made a sub-surface. A sub-surface has one parent surface. A
> > > +      sub-surface's size and position are not limited to that of the parent.
> > > +      Particularly, a sub-surface is not automatically clipped to its
> > > +      parent's area.
> > >  
> > >        A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
> > >        and the parent surface is mapped. The order of which one happens
> > > @@ -99,8 +102,8 @@
> > >        depends on the sub-surface's mode. The possible modes are
> > >        synchronized and desynchronized, see methods
> > >        wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized
> > > -      mode caches wl_surface state to be applied on the next parent
> > > -      surface's commit, and desynchronized mode applies the pending
> > > +      mode caches the wl_surface state to be applied when the parent's
> > > +      state gets applied, and desynchronized mode applies the pending
> > >        wl_surface state directly. A sub-surface is initially in the
> > >        synchronized mode.
> > >  
> > > @@ -113,15 +116,15 @@
> > >        wl_surface state is applied, regardless of the sub-surface's mode.
> > >        As the exception, set_sync and set_desync are effective immediately.
> > >  
> > > -      The main surface can thought to be always in desynchronized mode,
> > > +      The main surface can be thought to be always in desynchronized mode,
> > >        since it does not have a parent in the sub-surfaces sense.
> > >  
> > >        Even if a sub-surface is in desynchronized mode, it will behave as
> > >        in synchronized mode, if its parent surface behaves as in
> > >        synchronized mode. This rule is applied recursively throughout the
> > >        tree of surfaces. This means, that one can set a sub-surface into
> > > -      synchronized mode, and then assume that all its child sub-surfaces
> > > -      are synchronized, too, without explicitly setting them.
> > > +      synchronized mode, and then assume that all its child and grand-child
> > > +      sub-surfaces are synchronized, too, without explicitly setting them.
> > >  
> > >        If the wl_surface associated with the wl_subsurface is destroyed, the
> > >        wl_subsurface object becomes inert. Note, that destroying either object
> > > @@ -153,7 +156,9 @@
> > >        <description summary="reposition the sub-surface">
> > >  	This schedules a sub-surface position change.
> > >  	The sub-surface will be moved so, that its origin (top-left
> > > -	corner pixel) will be at the location x, y of the parent surface.
> > > +	corner pixel) will be at the location x, y of the parent surface
> > > +	coordinate system. The coordinates are not restricted to the parent
> > > +	surface area. Negative values are allowed.
> > >  
> > >  	The next wl_surface.commit on the parent surface will reset
> > >  	the sub-surface's position to the scheduled coordinates.
> > > @@ -176,6 +181,9 @@
> > >  	The z-order is double-buffered state, and will be applied on the
> > >  	next commit of the parent surface.
> > >  	See wl_surface.commit and wl_subcompositor.get_subsurface.
> > > +
> > > +	A new sub-surface is initially added as the top-most in the stack
> > > +	of its siblings and parent.
> > >        </description>
> > >  
> > >        <arg name="sibling" type="object" interface="wl_surface"
> > > @@ -200,9 +208,8 @@
> > >  	In synchronized mode, wl_surface.commit on a sub-surface will
> > >  	accumulate the committed state in a cache, but the state will
> > >  	not be applied and hence will not change the compositor output.
> > > -	The cached state is applied to the sub-surface when
> > > -	wl_surface.commit is called on the parent surface, after the
> > > -	parent surface's own state is applied. This ensures atomic
> > > +	The cached state is applied to the sub-surface immediately after
> > > +	the parent surface's state is applied. This ensures atomic
> > >  	updates of the parent and all its synchronized sub-surfaces.
> > >  	Applying the cached state will invalidate the cache, so further
> > >  	parent surface commits do not (re-)apply old state.
> > > -- 
> > > 1.8.1.5
> > > 
>