From b1775149307a157444c516693ad6b98a404ef1b2 Mon Sep 17 00:00:00 2001 From: Carl Hetherington Date: Thu, 29 Dec 2011 22:14:15 +0000 Subject: Revert internals of the last layering-related commit, and go back a slightly-cleaned-up version of how it was before. Remove all layering modes; only option now is add-is-higher. Move-add-higher could easily be re-added if anyone uses it. git-svn-id: svn://localhost/ardour2/branches/3.0@11111 d708f5d6-7413-0410-9779-e7cbd77b26cf --- doc/layering/build.sh | 3 +- doc/layering/explicit-layering1.svg | 322 ----------------------------- doc/layering/explicit-layering2.svg | 322 ----------------------------- doc/layering/layering-order-1.svg | 201 +++++++++++++++++++ doc/layering/layering-order-2.svg | 240 ++++++++++++++++++++++ doc/layering/layering.tex | 206 ++++++++++++------- doc/layering/tricky-explicit-layering.svg | 323 ------------------------------ 7 files changed, 573 insertions(+), 1044 deletions(-) delete mode 100644 doc/layering/explicit-layering1.svg delete mode 100644 doc/layering/explicit-layering2.svg create mode 100644 doc/layering/layering-order-1.svg create mode 100644 doc/layering/layering-order-2.svg delete mode 100644 doc/layering/tricky-explicit-layering.svg (limited to 'doc') diff --git a/doc/layering/build.sh b/doc/layering/build.sh index 5abaaa5721..ad8d95e7ba 100644 --- a/doc/layering/build.sh +++ b/doc/layering/build.sh @@ -1,6 +1,7 @@ #!/bin/sh -for f in basic-layering explicit-layering1 explicit-layering2 tricky-explicit-layering; do +for f in basic-layering layering-order-1 layering-order-2; do + echo "$f" inkscape -z --export-area-drawing -f $f.svg --export-pdf $f.pdf done diff --git a/doc/layering/explicit-layering1.svg b/doc/layering/explicit-layering1.svg deleted file mode 100644 index 2a5c921ce7..0000000000 --- a/doc/layering/explicit-layering1.svg +++ /dev/null @@ -1,322 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - time - - - - - A - B - C - D - - layer - - 0 - - 1 - - 2 - - diff --git a/doc/layering/explicit-layering2.svg b/doc/layering/explicit-layering2.svg deleted file mode 100644 index 4f71a40eb9..0000000000 --- a/doc/layering/explicit-layering2.svg +++ /dev/null @@ -1,322 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - time - - - - - A - B - C - D - - layer - - 0 - - 1 - - 2 - - diff --git a/doc/layering/layering-order-1.svg b/doc/layering/layering-order-1.svg new file mode 100644 index 0000000000..25e329c0f4 --- /dev/null +++ b/doc/layering/layering-order-1.svg @@ -0,0 +1,201 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + 0 + 1 + 2 + 3 + 4 + 5 + + increasinglayeringorder + + diff --git a/doc/layering/layering-order-2.svg b/doc/layering/layering-order-2.svg new file mode 100644 index 0000000000..b4164444ba --- /dev/null +++ b/doc/layering/layering-order-2.svg @@ -0,0 +1,240 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + 0 + + + + 1 + + + + 2 + + + + + + 3 + + + + + 4 + + + + + + + + + 5 + + + + + + increasinglayer + + diff --git a/doc/layering/layering.tex b/doc/layering/layering.tex index 317aaeae43..35670cbfde 100644 --- a/doc/layering/layering.tex +++ b/doc/layering/layering.tex @@ -1,19 +1,19 @@ \documentclass{article} -\title{Region Layering} +\title{Region layering} \author{} \date{} -\usepackage{graphicx} +\usepackage{graphicx,amsmath} \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. +played. -\subsection{Layers} +\section{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 @@ -37,114 +37,168 @@ This follows the basic rule that, at any given point, the region on the highest layer will be played. -\section{Choice of layering} +\section{Which layer does a region go on?} -There are two main decisions to be made with regards to how a playlist should be layered: +The logic to decide which layer a region goes onto is somewhat complicated. +This section describes it in hand-wavey and more technical terms. -\begin{itemize} -\item Given overlapping regions, what order should they be layered in? -\item When should layering be changed? -\end{itemize} +\subsection{Hand-wavey description} -\subsection{Layering order} +A playlist maintains an internal \emph{layering order} for regions. This order +is not directly visible in Ardour, but it's useful to understand it +nonetheless. Figure~\ref{fig:layering-order-1} gives a rough idea of what this +means. -Ardour provides three-and-a-half ways to decide on the order in which -regions are layered. The most basic choice is: +\begin{figure}[ht] +\begin{center} +\includegraphics{layering-order-1.pdf} +\end{center} +\caption{Layering order} +\label{fig:layering-order-1} +\end{figure} -\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} +Here we see 6 regions; as the layering order value increases, the region will +be placed on a higher layer. -This choice can be set per-session from the \emph{Session Properties} dialogue -box. +Every time any region is moved, added or edited, a \emph{relayer} occurs. This +collapses the regions down into layers. For our example, this would result in +the arrangement in Figure~\ref{fig:layering-order-2}. -\subsubsection{Explicit ordering} +\begin{figure}[ht] +\begin{center} +\includegraphics{layering-order-2.pdf} +\end{center} +\caption{Layering} +\label{fig:layering-order-2} +\end{figure} -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. +The relayer operation takes each region, in the layering order, and puts it +on the lowest possible layer that it can be on without overlap. -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} +\subsubsection{Layering order} -There are two distinct approaches to updating layering: +Given that arrangement, the remaining question is how the layering order is +arrived at. The rules are as follows: \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. + +\item When a region is added to a playlist, it goes above the current highest + region in the layering order. + +\item In `overlaid' track mode, moving or editing regions does not change the + layering order. Hence, moving regions about will maintain their position in + the layering order. Changing overlaps may change the \emph{layer} that the + region ends up on, but not the order in which they will be layered. + +\item In `stacked' track mode, moving regions places the region on the layer + that they are dropped on. This is achieved by modifying the layering order + for the region that is moved, so that when the relayer operation happens the + region ends up on the desired layer. + +\item When regions are `raised' or `lowered' in the stack, the layering order + is modified to achieve the desired layer change. + \end{itemize} -The approach to use is optional, and can be set in \emph{Session Properties}. +The upshot of all this is that regions should maintain their expected layering +order, unless that order is explicitly change using `stacked' mode or by +explicit layering commands like `raise' or `lower'. + + + +\subsection{Technical description} + +Each region on a playlist has three layering-related properties: its current +layer $c$ (an integer) and its layering index $i$ (also an integer). It also +has an \emph{optional} pending layer $p$ which is fractional. + +Whenever a region is added, moved, trimmed, etc.\ we run a \emph{relayer}. This +does the following: + +\begin{enumerate} +\item Take a list of all regions and remove those who have a value for $p$. +\item Sort the remainder in ascending order of $i$. +\item Insert the regions which have a value for $p$ in the correct place in the + list by comparing $c$ of those in the list to $p$ of the inserted region. +\item Iterate over the resulting list, putting each region on the lowest available + layer, setting its current layer $c$, and clearing $p$. +\item If any region had a pending layer, iterate through the region list again + giving each region a new layering index $i$ ascending from 0. +\end{enumerate} -This decision only has consequences when an explicit layering command has -been used. Consider the case in Figure~\ref{fig:explicit-layering1}. +The pending layer $p$ is set up in the following situations: +\begin{enumerate} +\item When a region is added to the playlist, $p$ is set to $\infty$. +\item When a region is raised to the top of the playlist, $p$ is set to $\infty$. +\item When a region is raised one step in the playlist, $p$ is set to $c + 1.5$. +\item When a region is lowered to the bottom of the playlist, $p$ is set to $-0.5$. +\item When a region is lowered one step int the playlist, $p$ is set to $c - 1.5$. +\item When a region is explicitly put between layers $A$ and $B$ in `stacked' + mode, $p$ is set to $(A + B) / 2$. +\end{enumerate} + +The idea of this approach is that the layering indices $i$ are used to keep a +current state of the stack, and this state is used to maintain region +relationships. Setting $p$ will alter these relationships, after which the +layering indices $i$ are updated to reflect the new status quo. + +It is not sufficient to use current layer $c$ as the state of the stack. +Consider two overlapping regions $P$ and $Q$, with $P$ on layer~0 and $Q$ on +layer~1. Now raise $P$ to the top of the stack, so that $Q$ is on layer~0 and +$P$ on layer~1. Move $P$ away from $Q$ (in overlaid mode) so that both regions +are on layer~0. Now drag $P$ back over $Q$. One would expect $P$ to return to +the top of the stack, since it was explicitly raised earlier. However, if the +relayer operation were to compare $c$ for each region, they would be identical; +the information that $P$ was once higher than $Q$ has been lost. + + +\section{Stacked mode} + +When a track is being displayed in \emph{stacked} mode, regions are spread out +vertically to indicate their layering, like in Figure~\ref{fig:stacked}. \begin{figure}[ht] \begin{center} -\includegraphics{explicit-layering1.pdf} +\includegraphics[scale=0.5]{stacked.png} \end{center} -\caption{Explicit layering: stage 1} -\label{fig:explicit-layering1} +\caption{A track in stacked mode} +\label{fig:stacked} \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}. +In this mode, layering is performed \emph{explicitly}. In other words, the +user's immediate actions decide which layer a region should be put on. When a +region move drag is started in stacked mode, the regions separate further out +vertically, to leave space between each layer, as shown in +Figure~\ref{fig:stacked-drag}. \begin{figure}[ht] \begin{center} -\includegraphics{explicit-layering2.pdf} +\includegraphics[scale=0.5]{stacked-drag.png} \end{center} -\caption{Explicit layering: stage 2} -\label{fig:explicit-layering2} +\caption{A track in stacked mode during a drag} +\label{fig:stacked-drag} \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}. +The region(s) being dragged can then be dropped in any location, horizontally +and vertically, and the regions will be layered accordingly. + -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. +\section{Overlaid mode} -Another, more complex, example is shown in Figure~\ref{fig:tricky-explicit-layering}. +When a track is being displayed in \emph{overlaid} mode, regions are +displayed on top of one another, like in Figure~\ref{fig:overlaid}. \begin{figure}[ht] \begin{center} -\includegraphics{tricky-explicit-layering.pdf} +\includegraphics[scale=0.5]{overlaid.png} \end{center} -\caption{More complex explicit layering} -\label{fig:tricky-explicit-layering} +\caption{A track in overlaid mode} +\label{fig:overlaid} \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. +In this mode, drags of regions maintain the same \emph{layer ordering}, even if the layers may +change. \end{document} diff --git a/doc/layering/tricky-explicit-layering.svg b/doc/layering/tricky-explicit-layering.svg deleted file mode 100644 index f4e89f6f92..0000000000 --- a/doc/layering/tricky-explicit-layering.svg +++ /dev/null @@ -1,323 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - time - - - - A - B - - C - D - - layer - - 0 - - 1 - - 2 - - -- cgit v1.2.3