1 files changed, 150 insertions, 0 deletions
diff --git a/doc/layering/layering.tex b/doc/layering/layering.tex
new file mode 100644
index 0000000000..317aaeae43
--- /dev/null
+++ b/doc/layering/layering.tex
@@ -0,0 +1,150 @@
+\documentclass{article}
+\title{Region Layering}
+\author{}
+\date{}
+
+\usepackage{graphicx}
+\begin{document}
+\maketitle
+
+\section{Introduction}
+
+When regions overlap in time, we need to decide which one should be
+played.  Ardour has a few options to set how this decision is made.
+
+
+\subsection{Layers}
+
+Each region on a playlist is on a \emph{layer}.  All overlapping regions
+are on a unique layer, and when overlaps exist the highest-layered
+region is played.  This is illustrated in Figure~\ref{fig:basic-layering}.
+
+\begin{figure}[ht]
+\begin{center}
+\includegraphics{basic-layering.pdf}
+\end{center}
+\caption{Basic region layering}
+\label{fig:basic-layering}
+\end{figure}
+
+Here we see that region $A$ overlaps $B$, $B$ overlaps $C$, and
+$D$ overlaps nothing.  There are several ways in which these regions
+could be arranged; in the drawing, $A$ is on layer~2, $B$ on layer~1,
+$C$ and $D$ on layer~0.  If this area is played back, region $A$ will
+play in its entirety, followed by the end part of region $B$, followed
+by the end part of region $C$, followed by the whole of region $D$.
+This follows the basic rule that, at any given point, the region on
+the highest layer will be played.
+
+
+\section{Choice of layering}
+
+There are two main decisions to be made with regards to how a playlist should be layered:
+
+\begin{itemize}
+\item Given overlapping regions, what order should they be layered in?
+\item When should layering be changed?
+\end{itemize}
+
+
+\subsection{Layering order}
+
+Ardour provides three-and-a-half ways to decide on the order in which
+regions are layered.  The most basic choice is:
+
+\begin{itemize}
+\item \emph{Later is higher} --- regions which are later in time will
+  be on higher layers.
+\item \emph{Most recently added is higher} --- regions which were more
+  recently added to the playlist will be on higher layers.
+\item \emph{Most recently edited or added is higher} --- regions which
+  were more recently edited or added to the playlist will be on
+  higher layers.
+\end{itemize}
+
+This choice can be set per-session from the \emph{Session Properties} dialogue
+box.
+
+\subsubsection{Explicit ordering}
+
+There are also cases when none of these rules should apply.  If, for
+example, you want to put a given region at the top of the stack (on
+the highest layer), this is possible using the region `raise to top'
+command.  Following such a command (called an `explicit layering'),
+the regions on the playlist may no longer obey any of the standard
+ordering rules.
+
+This situation also arises when editing tracks using the `stacked' layer mode.
+In this mode, almost all layering is explicit.  When starting a region drag,
+the other regions on a track spread apart vertically to allow the dragged
+region to be dropped in any position within the region stack.  The normal
+layering rules will only be followed if a region is dropped on top of another;
+in all other cases, explicit layering will be used to put the region wherever
+it was dropped.
+
+\subsection{When to update layering}
+
+There are two distinct approaches to updating layering:
+
+\begin{itemize}
+\item Update whenever any region edit is performed.
+\item Update only when a region is edited such that a new overlap has been set up.
+\end{itemize}
+
+The approach to use is optional, and can be set in \emph{Session Properties}.
+
+This decision only has consequences when an explicit layering command has
+been used.  Consider the case in Figure~\ref{fig:explicit-layering1}.
+
+\begin{figure}[ht]
+\begin{center}
+\includegraphics{explicit-layering1.pdf}
+\end{center}
+\caption{Explicit layering: stage 1}
+\label{fig:explicit-layering1}
+\end{figure}
+
+Given that arrangement, imagine that we perform a `raise to top' on region $C$.
+This results in the arrangement in Figure~\ref{fig:explicit-layering2}.
+
+\begin{figure}[ht]
+\begin{center}
+\includegraphics{explicit-layering2.pdf}
+\end{center}
+\caption{Explicit layering: stage 2}
+\label{fig:explicit-layering2}
+\end{figure}
+
+Imagine now that region $C$ is moved very slightly to the left, so
+that it still overlaps both $A$ and $B$.  If we are updating whenever
+any region edit is performed, this will result in a relayer; the
+regions' arrangement will go back to that in
+Figure~\ref{fig:explicit-layering1}.
+
+If, on the other hand, we only relayer when a new overlap is set up,
+the region layering will remain as in
+Figure~\ref{fig:explicit-layering2}.  Before the edit, regions $A$,
+$B$ and $C$ overlapped; after the edit, the situation is the same, so
+no relayering is performed.
+
+Another, more complex, example is shown in Figure~\ref{fig:tricky-explicit-layering}.
+
+\begin{figure}[ht]
+\begin{center}
+\includegraphics{tricky-explicit-layering.pdf}
+\end{center}
+\caption{More complex explicit layering}
+\label{fig:tricky-explicit-layering}
+\end{figure}
+
+% XXX: this makes no sense
+
+Here, imagine that $C$ has been moved to the top of the stack with an explicit
+`raise to top' command.  Now consider an extension of $C$ so that its
+right-hand edge overlaps $D$.  If we are relayering only on new overlaps, this
+case presents one new overlap (that of $C$ with $D$).  In this case, $C$ is
+moved according to the current layering rules so that it is correct with
+respect to $D$.  In addition, $A$ and $B$ are re-layered so that the relation
+of $C$ to $A$ and $B$ is preserved.
+
+\end{document}