mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2026-04-23 06:46:52 -04: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 refers to a sub-surface which is a child of T1, and SS2 refers to a sub-surface
which is a child of SS1. which is a child of SS1.
**Legend** ### Legend
![](images/content-updates/content-update-legend.png) ![](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 ![](images/content-updates/simple-desynchronized-state-1.png)
desynchronized content update (DCU) _1_.
![](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 ![](images/content-updates/simple-desynchronized-state-2.png)
_1_ itself. DCU _1_ and thus the candidate DAG does not have any constraints and
can be applied.
![](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 ![](images/content-updates/simple-desynchronized-state-4.png)
can't be applied because it contains a constraint.
![](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 ![](images/content-updates/simple-desynchronized-state-5.png)
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-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 ![](images/content-updates/simple-desynchronized-state-6.png)
atomitcally (either only _2_, or _2_ and _3_).
**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 ![](images/content-updates/simple-synchronized-state-2.png)
queue, which is not reachable. This creates a dependency from SCU _2_ to SCU
_1_.
![](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 ![](images/content-updates/simple-synchronized-state-3.png)
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-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 ![](images/content-updates/simple-synchronized-state-4.png)
and it can be applied.
![](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 ![](images/content-updates/sync-subsurf-case1-2.png)
DAG of CU _1_ does not contain constraints and can be applied
![](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 ![](images/content-updates/sync-subsurf-case1-3.png)
_buffer-sync_ constrain
![](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 ![](images/content-updates/sync-subsurf-case1-4.png)
DAG of _6_ does not contain CUs with constraints and can be applied.
![](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 ![](images/content-updates/sync-subsurf-case1-5.png)
without a new CU.
**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 ![](images/content-updates/sync-subsurf-case2-2.png)
no CU with constraints and can be applied in any order
![](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 ![](images/content-updates/sync-to-desync-subsurf-1.png)
_4_ contains a constraint
![](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 ![](images/content-updates/sync-to-desync-subsurf-2.png)
desynchronized. SCU _2_ is reachable by DCU _4_ so nothing changes.
![](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 ![](images/content-updates/sync-to-desync-subsurf-3.png)
Synchronized CU, it is not a candidate
**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 ![](images/content-updates/sync-to-desync-transition-2.png)
DCU because it is not reachable from a DCU
![](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 ![](images/content-updates/sync-to-desync-transition-3.png)
DCUs because they are not reachable from a DCU. SCU _1_ does not change because
it is reachable by DCU _2_.