mainnika/weston
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

protocol: improve sub-surface spec wording

Browse Source 
Mention, that sub-surfaces are not clipped to the parent.
Be more accurate on surface commit vs. apply state.
Mention the initial stacking order.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
This commit is contained in:
Pekka Paalanen
2013-05-17 16:46:03 +03:00
committed by Kristian Høgsberg
parent eb1e13044f
commit 419e2bae92
1 changed files with 17 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol/subsurface.xml
+17 -10
View File
@@ -85,7 +85,10 @@
<interface name="wl_subsurface" version="1"> <interface name="wl_subsurface" version="1">
<description summary="sub-surface interface to a wl_surface"> <description summary="sub-surface interface to a wl_surface">
An additional interface to a wl_surface object, which has been 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 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 and the parent surface is mapped. The order of which one happens
@@ -97,8 +100,8 @@
depends on the sub-surface's mode. The possible modes are depends on the sub-surface's mode. The possible modes are
synchronized and desynchronized, see methods synchronized and desynchronized, see methods
wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized
mode caches wl_surface state to be applied on the next parent mode caches the wl_surface state to be applied when the parent's
surface's commit, and desynchronized mode applies the pending state gets applied, and desynchronized mode applies the pending
wl_surface state directly. A sub-surface is initially in the wl_surface state directly. A sub-surface is initially in the
synchronized mode. synchronized mode.
@@ -111,15 +114,15 @@
wl_surface state is applied, regardless of the sub-surface's mode. wl_surface state is applied, regardless of the sub-surface's mode.
As the exception, set_sync and set_desync are effective immediately. 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. 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 Even if a sub-surface is in desynchronized mode, it will behave as
in synchronized mode, if its parent surface behaves as in in synchronized mode, if its parent surface behaves as in
synchronized mode. This rule is applied recursively throughout the synchronized mode. This rule is applied recursively throughout the
tree of surfaces. This means, that one can set a sub-surface into tree of surfaces. This means, that one can set a sub-surface into
synchronized mode, and then assume that all its child sub-surfaces synchronized mode, and then assume that all its child and grand-child
are synchronized, too, without explicitly setting them. sub-surfaces are synchronized, too, without explicitly setting them.
If the wl_surface associated with the wl_subsurface is destroyed, the If the wl_surface associated with the wl_subsurface is destroyed, the
wl_subsurface object becomes inert. Note, that destroying either object wl_subsurface object becomes inert. Note, that destroying either object
@@ -151,7 +154,9 @@
<description summary="reposition the sub-surface"> <description summary="reposition the sub-surface">
This schedules a sub-surface position change. This schedules a sub-surface position change.
The sub-surface will be moved so, that its origin (top-left 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 next wl_surface.commit on the parent surface will reset
the sub-surface's position to the scheduled coordinates. the sub-surface's position to the scheduled coordinates.
@@ -174,6 +179,9 @@
The z-order is double-buffered state, and will be applied on the The z-order is double-buffered state, and will be applied on the
next commit of the parent surface. next commit of the parent surface.
See wl_surface.commit and wl_subcompositor.get_subsurface. 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> </description>
<arg name="sibling" type="object" interface="wl_surface" <arg name="sibling" type="object" interface="wl_surface"
@@ -198,9 +206,8 @@
In synchronized mode, wl_surface.commit on a sub-surface will In synchronized mode, wl_surface.commit on a sub-surface will
accumulate the committed state in a cache, but the state will accumulate the committed state in a cache, but the state will
not be applied and hence will not change the compositor output. not be applied and hence will not change the compositor output.
The cached state is applied to the sub-surface when The cached state is applied to the sub-surface immediately after
wl_surface.commit is called on the parent surface, after the the parent surface's state is applied. This ensures atomic
parent surface's own state is applied. This ensures atomic
updates of the parent and all its synchronized sub-surfaces. updates of the parent and all its synchronized sub-surfaces.
Applying the cached state will invalidate the cache, so further Applying the cached state will invalidate the cache, so further
parent surface commits do not (re-)apply old state. parent surface commits do not (re-)apply old state.