doc/layering/layering.tex

   1 \documentclass{article}
   2 \title{Region layering}
   3 \author{}
   4 \date{}
   5
   6 \usepackage{graphicx,amsmath}
   7 \begin{document}
   8 \maketitle
   9
  10 \section{Introduction}
  11
  12 When regions overlap in time, we need to decide which one should be
  13 played.
  14
  15
  16 \section{Layers}
  17
  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}.
  21
  22 \begin{figure}[ht]
  23 \begin{center}
  24 \includegraphics{basic-layering.pdf}
  25 \end{center}
  26 \caption{Basic region layering}
  27 \label{fig:basic-layering}
  28 \end{figure}
  29
  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.
  38
  39
  40 \section{Which layer does a region go on?}
  41
  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.
  44
  45
  46 \subsection{Hand-wavey description}
  47
  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
  51 means.
  52
  53 \begin{figure}[ht]
  54 \begin{center}
  55 \includegraphics{layering-order-1.pdf}
  56 \end{center}
  57 \caption{Layering order}
  58 \label{fig:layering-order-1}
  59 \end{figure}
  60
  61 Here we see 6 regions; as the layering order value increases, the region will
  62 be placed on a higher layer.
  63
  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}.
  67
  68 \begin{figure}[ht]
  69 \begin{center}
  70 \includegraphics{layering-order-2.pdf}
  71 \end{center}
  72 \caption{Layering}
  73 \label{fig:layering-order-2}
  74 \end{figure}
  75
  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.
  78
  79
  80 \subsubsection{Layering order}
  81
  82 Given that arrangement, the remaining question is how the layering order is
  83 arrived at.  The rules are as follows:
  84
  85 \begin{itemize}
  86
  87 \item When a region is added to a playlist, it goes above the current highest
  88   region in the layering order.
  89
  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.
  94
  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.
  99
 100 \item When regions are `raised' or `lowered' in the stack, the layering order
 101   is modified to achieve the desired layer change.
 102
 103 \end{itemize}
 104
 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'.
 108
 109
 110
 111 \subsection{Technical description}
 112
 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.
 116
 117 Whenever a region is added, moved, trimmed, etc.\ we run a \emph{relayer}.  This
 118 does the following:
 119
 120 \begin{enumerate}
 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.
 129 \end{enumerate}
 130
 131 The pending layer $p$ is set up in the following situations:
 132 \begin{enumerate}
 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$.
 140 \end{enumerate}
 141
 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.
 146
 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.
 155
 156
 157 \section{Stacked mode}
 158
 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}.
 161
 162 \begin{figure}[ht]
 163 \begin{center}
 164 \includegraphics[scale=0.5]{stacked.png}
 165 \end{center}
 166 \caption{A track in stacked mode}
 167 \label{fig:stacked}
 168 \end{figure}
 169
 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}.
 175
 176 \begin{figure}[ht]
 177 \begin{center}
 178 \includegraphics[scale=0.5]{stacked-drag.png}
 179 \end{center}
 180 \caption{A track in stacked mode during a drag}
 181 \label{fig:stacked-drag}
 182 \end{figure}
 183
 184 The region(s) being dragged can then be dropped in any location, horizontally
 185 and vertically, and the regions will be layered accordingly.
 186
 187
 188 \section{Overlaid mode}
 189
 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}.
 192
 193 \begin{figure}[ht]
 194 \begin{center}
 195 \includegraphics[scale=0.5]{overlaid.png}
 196 \end{center}
 197 \caption{A track in overlaid mode}
 198 \label{fig:overlaid}
 199 \end{figure}
 200
 201 In this mode, drags of regions maintain the same \emph{layer ordering}, even if the layers may
 202 change.
 203
 204 \end{document}