1 \documentclass{article}
2 \title{Region layering}
6 \usepackage{graphicx,amsmath}
10 \section{Introduction}
12 When regions overlap in time, we need to decide which one should be
18 Each region on a playlist is on a \emph{layer}. All overlapping regions
19 are on a unique layer, and when overlaps exist the highest-layered
20 region is played. This is illustrated in Figure~\ref{fig:basic-layering}.
24 \includegraphics{basic-layering.pdf}
26 \caption{Basic region layering}
27 \label{fig:basic-layering}
30 Here we see that region $A$ overlaps $B$, $B$ overlaps $C$, and
31 $D$ overlaps nothing. There are several ways in which these regions
32 could be arranged; in the drawing, $A$ is on layer~2, $B$ on layer~1,
33 $C$ and $D$ on layer~0. If this area is played back, region $A$ will
34 play in its entirety, followed by the end part of region $B$, followed
35 by the end part of region $C$, followed by the whole of region $D$.
36 This follows the basic rule that, at any given point, the region on
37 the highest layer will be played.
40 \section{Which layer does a region go on?}
42 The logic to decide which layer a region goes onto is somewhat complicated.
43 This section describes it in hand-wavey and more technical terms.
46 \subsection{Hand-wavey description}
48 A playlist maintains an internal \emph{layering order} for regions. This order
49 is not directly visible in Ardour, but it's useful to understand it
50 nonetheless. Figure~\ref{fig:layering-order-1} gives a rough idea of what this
55 \includegraphics{layering-order-1.pdf}
57 \caption{Layering order}
58 \label{fig:layering-order-1}
61 Here we see 6 regions; as the layering order value increases, the region will
62 be placed on a higher layer.
64 Every time any region is moved, added or edited, a \emph{relayer} occurs. This
65 collapses the regions down into layers. For our example, this would result in
66 the arrangement in Figure~\ref{fig:layering-order-2}.
70 \includegraphics{layering-order-2.pdf}
73 \label{fig:layering-order-2}
76 The relayer operation takes each region, in the layering order, and puts it
77 on the lowest possible layer that it can be on without overlap.
80 \subsubsection{Layering order}
82 Given that arrangement, the remaining question is how the layering order is
83 arrived at. The rules are as follows:
87 \item When a region is added to a playlist, it goes above the current highest
88 region in the layering order.
90 \item In `overlaid' track mode, moving or editing regions does not change the
91 layering order. Hence, moving regions about will maintain their position in
92 the layering order. Changing overlaps may change the \emph{layer} that the
93 region ends up on, but not the order in which they will be layered.
95 \item In `stacked' track mode, moving regions places the region on the layer
96 that they are dropped on. This is achieved by modifying the layering order
97 for the region that is moved, so that when the relayer operation happens the
98 region ends up on the desired layer.
100 \item When regions are `raised' or `lowered' in the stack, the layering order
101 is modified to achieve the desired layer change.
105 The upshot of all this is that regions should maintain their expected layering
106 order, unless that order is explicitly change using `stacked' mode or by
107 explicit layering commands like `raise' or `lower'.
111 \subsection{Technical description}
113 Each region on a playlist has three layering-related properties: its current
114 layer $c$ (an integer) and its layering index $i$ (also an integer). It also
115 has an \emph{optional} pending layer $p$ which is fractional.
117 Whenever a region is added, moved, trimmed, etc.\ we run a \emph{relayer}. This
121 \item Take a list of all regions and remove those who have a value for $p$.
122 \item Sort the remainder in ascending order of $i$.
123 \item Insert the regions which have a value for $p$ in the correct place in the
124 list by comparing $c$ of those in the list to $p$ of the inserted region.
125 \item Iterate over the resulting list, putting each region on the lowest available
126 layer, setting its current layer $c$, and clearing $p$.
127 \item If any region had a pending layer, iterate through the region list again
128 giving each region a new layering index $i$ ascending from 0.
131 The pending layer $p$ is set up in the following situations:
133 \item When a region is added to the playlist, $p$ is set to $\infty$.
134 \item When a region is raised to the top of the playlist, $p$ is set to $\infty$.
135 \item When a region is raised one step in the playlist, $p$ is set to $c + 1.5$.
136 \item When a region is lowered to the bottom of the playlist, $p$ is set to $-0.5$.
137 \item When a region is lowered one step int the playlist, $p$ is set to $c - 1.5$.
138 \item When a region is explicitly put between layers $A$ and $B$ in `stacked'
139 mode, $p$ is set to $(A + B) / 2$.
142 The idea of this approach is that the layering indices $i$ are used to keep a
143 current state of the stack, and this state is used to maintain region
144 relationships. Setting $p$ will alter these relationships, after which the
145 layering indices $i$ are updated to reflect the new status quo.
147 It is not sufficient to use current layer $c$ as the state of the stack.
148 Consider two overlapping regions $P$ and $Q$, with $P$ on layer~0 and $Q$ on
149 layer~1. Now raise $P$ to the top of the stack, so that $Q$ is on layer~0 and
150 $P$ on layer~1. Move $P$ away from $Q$ (in overlaid mode) so that both regions
151 are on layer~0. Now drag $P$ back over $Q$. One would expect $P$ to return to
152 the top of the stack, since it was explicitly raised earlier. However, if the
153 relayer operation were to compare $c$ for each region, they would be identical;
154 the information that $P$ was once higher than $Q$ has been lost.
157 \section{Stacked mode}
159 When a track is being displayed in \emph{stacked} mode, regions are spread out
160 vertically to indicate their layering, like in Figure~\ref{fig:stacked}.
164 \includegraphics[scale=0.5]{stacked.png}
166 \caption{A track in stacked mode}
170 In this mode, layering is performed \emph{explicitly}. In other words, the
171 user's immediate actions decide which layer a region should be put on. When a
172 region move drag is started in stacked mode, the regions separate further out
173 vertically, to leave space between each layer, as shown in
174 Figure~\ref{fig:stacked-drag}.
178 \includegraphics[scale=0.5]{stacked-drag.png}
180 \caption{A track in stacked mode during a drag}
181 \label{fig:stacked-drag}
184 The region(s) being dragged can then be dropped in any location, horizontally
185 and vertically, and the regions will be layered accordingly.
188 \section{Overlaid mode}
190 When a track is being displayed in \emph{overlaid} mode, regions are
191 displayed on top of one another, like in Figure~\ref{fig:overlaid}.
195 \includegraphics[scale=0.5]{overlaid.png}
197 \caption{A track in overlaid mode}
201 In this mode, drags of regions maintain the same \emph{layer ordering}, even if the layers may