mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2026-03-05 01:41:08 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: turn captions into third-level headers in book

Browse source 
Signed-off-by: Julian Orth <ju.orth@gmail.com>
This commit is contained in:
Julian Orth 2026-02-02 11:25:59 +01:00
parent bc7a55a134
commit 4897da68e6
1 changed files with 81 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

162
doc/book/src/Content_Updates.md
View file

@ -73,142 +73,142 @@ In all the examples below, the surface T1 refers to a toplevel surface, SS1
refers to a sub-surface which is a child of T1, and SS2 refers to a sub-surface
which is a child of SS1.
**Legend**
### Legend
![](images/content-updates/content-update-legend.png)
**Simple Desynchronized Case**
### Simple Desynchronized Case
![](images/content-updates/simple-desynchronized-state-1.png)
1. SS2 is effectively desynchronized and commits. This results in the
desynchronized content update (DCU) _1_.
SS2 is effectively desynchronized and commits. This results in the
desynchronized content update (DCU) _1_.
![](images/content-updates/simple-desynchronized-state-1.png)
![](images/content-updates/simple-desynchronized-state-2.png)
2. DCU _1_ is a candidate, and the candidate DAG reachable from DCU _1_ is only DCU
_1_ itself. DCU _1_ and thus the candidate DAG does not have any constraints and
can be applied.
DCU _1_ is a candidate, and the candidate DAG reachable from DCU _1_ is only DCU
_1_ itself. DCU _1_ and thus the candidate DAG does not have any constraints and
can be applied.
![](images/content-updates/simple-desynchronized-state-2.png)
![](images/content-updates/simple-desynchronized-state-3.png)
3. The content updates of the candidate DAG get applied to the surface atomically.
The content updates of the candidate DAG get applied to the surface atomically.
![](images/content-updates/simple-desynchronized-state-3.png)
![](images/content-updates/simple-desynchronized-state-4.png)
4. T1 commits a DCU with a _buffer-sync_ constraint. It is a candidate but its DAG
can't be applied because it contains a constraint.
T1 commits a DCU with a _buffer-sync_ constraint. It is a candidate but its DAG
can't be applied because it contains a constraint.
![](images/content-updates/simple-desynchronized-state-4.png)
![](images/content-updates/simple-desynchronized-state-5.png)
5. T1 commits another CU (DCU _3_) which is added at the end of the queue, with a
dependency to the previous CU (DCU _2_). Both DCU _2_ and DCU _3_ are
candidates, but both DAGs contain DCU _2_ with a constraint, and can't be
applied.
T1 commits another CU (DCU _3_) which is added at the end of the queue, with a
dependency to the previous CU (DCU _2_). Both DCU _2_ and DCU _3_ are
candidates, but both DAGs contain DCU _2_ with a constraint, and can't be
applied.
![](images/content-updates/simple-desynchronized-state-5.png)
![](images/content-updates/simple-desynchronized-state-6.png)
6. When the constraint gets cleared, both DAGs can be applied to the surface
atomitcally (either only _2_, or _2_ and _3_).
When the constraint gets cleared, both DAGs can be applied to the surface
atomitcally (either only _2_, or _2_ and _3_).
![](images/content-updates/simple-desynchronized-state-6.png)
**Simple Synchronized Case**
### Simple Synchronized Case
![](images/content-updates/simple-synchronized-state-1.png)
1. SS1 and SS2 are effectively synchronized. SS2 commits SCU _1_.
SS1 and SS2 are effectively synchronized. SS2 commits SCU _1_.
![](images/content-updates/simple-synchronized-state-1.png)
![](images/content-updates/simple-synchronized-state-2.png)
2. SS1 commits SCU _2_. The direct child surfaces SS2 has the last SCU _1_ in its
queue, which is not reachable. This creates a dependency from SCU _2_ to SCU
_1_.
SS1 commits SCU _2_. The direct child surfaces SS2 has the last SCU _1_ in its
queue, which is not reachable. This creates a dependency from SCU _2_ to SCU
_1_.
![](images/content-updates/simple-synchronized-state-2.png)
![](images/content-updates/simple-synchronized-state-3.png)
3. SS1 commits SCU _3_. The direct child surfaces SS2 has the last SCU _1_ in its
queue, which is already reachable by SCU _2_. No dependency to SCU _1_ is
created. A dependency to the previous CU of the same queue (SCU _2_) is created.
SS1 commits SCU _3_. The direct child surfaces SS2 has the last SCU _1_ in its
queue, which is already reachable by SCU _2_. No dependency to SCU _1_ is
created. A dependency to the previous CU of the same queue (SCU _2_) is created.
![](images/content-updates/simple-synchronized-state-3.png)
![](images/content-updates/simple-synchronized-state-4.png)
4. T1 commit DCU _4_. It is a candidate, its DAG does not contain any constraint
and it can be applied.
T1 commit DCU _4_. It is a candidate, its DAG does not contain any constraint
and it can be applied.
![](images/content-updates/simple-synchronized-state-4.png)
![](images/content-updates/simple-synchronized-state-5.png)
5. The DAG gets applied to the surfaces atomically.
The DAG gets applied to the surfaces atomically.
![](images/content-updates/simple-synchronized-state-5.png)
**Complex Synchronized Subsurface Case 1**
### Complex Synchronized Subsurface Case 1
![](images/content-updates/sync-subsurf-case1-1.png)
1. Every DCU (_1_ and _6_) contain CUs with constraints in their candidate DAG
Every DCU (_1_ and _6_) contain CUs with constraints in their candidate DAG
![](images/content-updates/sync-subsurf-case1-1.png)
![](images/content-updates/sync-subsurf-case1-2.png)
2. Waiting until the _buffer-sync_ constrain on CU _1_ is cleared, the candidate
DAG of CU _1_ does not contain constraints and can be applied
Waiting until the _buffer-sync_ constrain on CU _1_ is cleared, the candidate
DAG of CU _1_ does not contain constraints and can be applied
![](images/content-updates/sync-subsurf-case1-2.png)
![](images/content-updates/sync-subsurf-case1-3.png)
3. That leaves the candidate DAG of CU _6_ which still contains another CU with a
_buffer-sync_ constrain
That leaves the candidate DAG of CU _6_ which still contains another CU with a
_buffer-sync_ constrain
![](images/content-updates/sync-subsurf-case1-3.png)
![](images/content-updates/sync-subsurf-case1-4.png)
4. Waiting until the _buffer-sync_ constrain on CU _6_ is cleared, the candidate
DAG of _6_ does not contain CUs with constraints and can be applied.
Waiting until the _buffer-sync_ constrain on CU _6_ is cleared, the candidate
DAG of _6_ does not contain CUs with constraints and can be applied.
![](images/content-updates/sync-subsurf-case1-4.png)
![](images/content-updates/sync-subsurf-case1-5.png)
5. There is no DCU left and no constraint remaining. Nothing more can be applied
without a new CU.
There is no DCU left and no constraint remaining. Nothing more can be applied
without a new CU.
![](images/content-updates/sync-subsurf-case1-5.png)
**Complex Synchronized Subsurface Case 2**
### Complex Synchronized Subsurface Case 2
![](images/content-updates/sync-subsurf-case2-1.png)
1. Both DCUs (_1_ and _6_) have a reachable DAG containing CU _1_ with a constraint
Both DCUs (_1_ and _6_) have a reachable DAG containing CU _1_ with a constraint
![](images/content-updates/sync-subsurf-case2-1.png)
![](images/content-updates/sync-subsurf-case2-2.png)
2. Waiting until the _buffer-sync_ constrain on _1_ is cleared, both DAGs contain
no CU with constraints and can be applied in any order
Waiting until the _buffer-sync_ constrain on _1_ is cleared, both DAGs contain
no CU with constraints and can be applied in any order
![](images/content-updates/sync-subsurf-case2-2.png)
![](images/content-updates/sync-subsurf-case2-3.png)
3. That leaves the same state as in the previous case
That leaves the same state as in the previous case
![](images/content-updates/sync-subsurf-case2-3.png)
**Synchronized to Desynchronized Subsurface**
### Synchronized to Desynchronized Subsurface
![](images/content-updates/sync-to-desync-subsurf-1.png)
1. There is one DCU (_4_) with its reachable DAG that cannot be applied because CU
_4_ contains a constraint
There is one DCU (_4_) with its reachable DAG that cannot be applied because CU
_4_ contains a constraint
![](images/content-updates/sync-to-desync-subsurf-1.png)
![](images/content-updates/sync-to-desync-subsurf-2.png)
2. Surface _SS1_ transitions from effectively synchronized to effectively
desynchronized. SCU _2_ is reachable by DCU _4_ so nothing changes.
Surface _SS1_ transitions from effectively synchronized to effectively
desynchronized. SCU _2_ is reachable by DCU _4_ so nothing changes.
![](images/content-updates/sync-to-desync-subsurf-2.png)
![](images/content-updates/sync-to-desync-subsurf-3.png)
3. Surface _SS1_ provides a new DCU (_5_) but because the CU before (_2_) is a
Synchronized CU, it is not a candidate
Surface _SS1_ provides a new DCU (_5_) but because the CU before (_2_) is a
Synchronized CU, it is not a candidate
![](images/content-updates/sync-to-desync-subsurf-3.png)
**Synchronized to Desynchronized Transition**
### Synchronized to Desynchronized Transition
![](images/content-updates/sync-to-desync-transition-1.png)
1. There are four SCUs and all surfaces are effectively synchronized.
There are four SCUs and all surfaces are effectively synchronized.
![](images/content-updates/sync-to-desync-transition-1.png)
![](images/content-updates/sync-to-desync-transition-2.png)
2. Surface _SS1_ transitions to effectively desynchronized and SCU _2_ becomes a
DCU because it is not reachable from a DCU
Surface _SS1_ transitions to effectively desynchronized and SCU _2_ becomes a
DCU because it is not reachable from a DCU
![](images/content-updates/sync-to-desync-transition-2.png)
![](images/content-updates/sync-to-desync-transition-3.png)
3. Surface _SS2_ transitions to effectively desynchronized. SCUs _3_ and _4_ become
DCUs because they are not reachable from a DCU. SCU _1_ does not change because
it is reachable by DCU _2_.
Surface _SS2_ transitions to effectively desynchronized. SCUs _3_ and _4_ become
DCUs because they are not reachable from a DCU. SCU _1_ does not change because
it is reachable by DCU _2_.
![](images/content-updates/sync-to-desync-transition-3.png)