diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-layers.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-base-layers.tex | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-layers.tex b/graphics/pgf/base/doc/pgfmanual-en-base-layers.tex new file mode 100644 index 0000000000..deba15d80b --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-base-layers.tex @@ -0,0 +1,136 @@ +% Copyright 2018 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Layered Graphics} +\label{section-layers} + +\subsection{Overview} + +\pgfname\ provides a layering mechanism for composing graphics from multiple +layers. (This mechanism is not to be confused with the conceptual ``software +layers'' the \pgfname\ system is composed of.) Layers are often used in graphic +programs. The idea is that you can draw on the different layers in any order. +So you might start drawing something on the ``background'' layer, then +something on the ``foreground'' layer, then something on the ``middle'' layer, +and then something on the background layer once more, and so on. At the end, no +matter in which ordering you drew on the different layers, the layers are +``stacked on top of each other'' in a fixed ordering to produce the final +picture. Thus, anything drawn on the middle layer would come on top of +everything of the background layer. + +Normally, you do not need to use different layers since you will have little +trouble ``ordering'' your graphic commands in such a way that layers are +superfluous. However, in certain situations you only ``know'' what you should +draw behind something else after the ``something else'' has been drawn. + +For example, suppose you wish to draw a yellow background behind your picture. +The background should be as large as the bounding box of the picture, plus a +little border. If you know the size of the bounding box of the picture at its +beginning, this is easy to accomplish. However, in general this is not the case +and you need to create a ``background'' layer in addition to the standard +``main'' layer. Then, at the end of the picture, when the bounding box has been +established, you can add a rectangle of the appropriate size to the picture. + + +\subsection{Declaring Layers} + +In \pgfname\ layers are referenced using names. The standard layer, which is a +bit special in certain ways, is called |main|. If nothing else is specified, +all graphic commands are added to the |main| layer. You can declare a new layer +using the following command: + +\begin{command}{\pgfdeclarelayer\marg{name}} + This command declares a layer named \meta{name} for later use. Mainly, this + will set up some internal bookkeeping. +\end{command} + +The next step toward using a layer is to tell \pgfname\ which layers will be +part of the actual picture and which will be their ordering. Thus, it is +possible to have more layers declared than are actually used. + +\begin{command}{\pgfsetlayers\marg{layer list}} + This command tells \pgfname\ which layers will be used in pictures. They + are stacked on top of each other in the order given. The layer |main| + should always be part of the list. Here is an example: + % +\begin{codeexample}[code only] +\pgfdeclarelayer{background} +\pgfdeclarelayer{foreground} +\pgfsetlayers{background,main,foreground} +\end{codeexample} + + This command should be given either outside of any picture or ``directly + inside'' of a picture. Here, the ``directly inside'' means that there + should be no further level of \TeX\ grouping between |\pgfsetlayers| and + the matching |\end{pgfpicture}| (no closing braces, no |\end{...}|). It + will also work if |\pgfsetlayers| is provided before |\end{tikzpicture}| + (with similar restrictions). +\end{command} + + +\subsection{Using Layers} + +Once the layers of your picture have been declared, you can start to ``fill'' +them. As said before, all graphics commands are normally added to the |main| +layer. Using the |{pgfonlayer}| environment, you can tell \pgfname\ that +certain commands should, instead, be added to the given layer. + +\begin{environment}{{pgfonlayer}\marg{layer name}} + The whole \meta{environment contents} is added to the layer with the name + \meta{layer name}. This environment can be used anywhere inside a picture. + Thus, even if it is used inside a |{pgfscope}| or a \TeX\ group, the + contents will still be added to the ``whole'' picture. Using this + environment multiple times inside the same picture will cause the + \meta{environment contents} to accumulate. + + \emph{Note:} You can \emph{not} add anything to the |main| layer using this + environment. The only way to add anything to the main layer is to give + graphic commands outside all |{pgfonlayer}| environments. + % +\begin{codeexample}[] +\pgfdeclarelayer{background layer} +\pgfdeclarelayer{foreground layer} +\pgfsetlayers{background layer,main,foreground layer} +\begin{tikzpicture} + % On main layer: + \fill[blue] (0,0) circle (1cm); + + \begin{pgfonlayer}{background layer} + \fill[yellow] (-1,-1) rectangle (1,1); + \end{pgfonlayer} + + \begin{pgfonlayer}{foreground layer} + \node[white] {foreground}; + \end{pgfonlayer} + + \begin{pgfonlayer}{background layer} + \fill[black] (-.8,-.8) rectangle (.8,.8); + \end{pgfonlayer} + + % On main layer again: + \fill[blue!50] (-.5,-1) rectangle (.5,1); +\end{tikzpicture} +\end{codeexample} + % +\end{environment} + +\begin{plainenvironment}{{pgfonlayer}\marg{layer name}} + This is the plain \TeX\ version of the environment. +\end{plainenvironment} + +\begin{contextenvironment}{{pgfonlayer}\marg{layer name}} + This is the Con\TeX t version of the environment. +\end{contextenvironment} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |