← Back to branch summary

~ubuntu-branches/ubuntu/utopic/ardour3/utopic

« back to all changes in this revision

Viewing changes to doc/layering/layering.tex

  • Committer: Package Import Robot
  • Author(s): Felipe Sateler
  • Date: 2013-09-21 19:05:02 UTC
  • Revision ID: package-import@ubuntu.com-20130921190502-8gsftrku6jnzhd7v
Tags: upstream-3.4~dfsg
Import upstream version 3.4~dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
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}