| 1 |
% Copyright 2018 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Layered Graphics} |
| 12 |
\label{section-layers} |
| 13 |
|
| 14 |
\subsection{Overview} |
| 15 |
|
| 16 |
\pgfname\ provides a layering mechanism for composing graphics from multiple |
| 17 |
layers. (This mechanism is not to be confused with the conceptual ``software |
| 18 |
layers'' the \pgfname\ system is composed of.) Layers are often used in graphic |
| 19 |
programs. The idea is that you can draw on the different layers in any order. |
| 20 |
So you might start drawing something on the ``background'' layer, then |
| 21 |
something on the ``foreground'' layer, then something on the ``middle'' layer, |
| 22 |
and then something on the background layer once more, and so on. At the end, no |
| 23 |
matter in which ordering you drew on the different layers, the layers are |
| 24 |
``stacked on top of each other'' in a fixed ordering to produce the final |
| 25 |
picture. Thus, anything drawn on the middle layer would come on top of |
| 26 |
everything of the background layer. |
| 27 |
|
| 28 |
Normally, you do not need to use different layers since you will have little |
| 29 |
trouble ``ordering'' your graphic commands in such a way that layers are |
| 30 |
superfluous. However, in certain situations you only ``know'' what you should |
| 31 |
draw behind something else after the ``something else'' has been drawn. |
| 32 |
|
| 33 |
For example, suppose you wish to draw a yellow background behind your picture. |
| 34 |
The background should be as large as the bounding box of the picture, plus a |
| 35 |
little border. If you know the size of the bounding box of the picture at its |
| 36 |
beginning, this is easy to accomplish. However, in general this is not the case |
| 37 |
and you need to create a ``background'' layer in addition to the standard |
| 38 |
``main'' layer. Then, at the end of the picture, when the bounding box has been |
| 39 |
established, you can add a rectangle of the appropriate size to the picture. |
| 40 |
|
| 41 |
|
| 42 |
\subsection{Declaring Layers} |
| 43 |
|
| 44 |
In \pgfname\ layers are referenced using names. The standard layer, which is a |
| 45 |
bit special in certain ways, is called |main|. If nothing else is specified, |
| 46 |
all graphic commands are added to the |main| layer. You can declare a new layer |
| 47 |
using the following command: |
| 48 |
|
| 49 |
\begin{command}{\pgfdeclarelayer\marg{name}} |
| 50 |
This command declares a layer named \meta{name} for later use. Mainly, this |
| 51 |
will set up some internal bookkeeping. |
| 52 |
\end{command} |
| 53 |
|
| 54 |
The next step toward using a layer is to tell \pgfname\ which layers will be |
| 55 |
part of the actual picture and which will be their ordering. Thus, it is |
| 56 |
possible to have more layers declared than are actually used. |
| 57 |
|
| 58 |
\begin{command}{\pgfsetlayers\marg{layer list}} |
| 59 |
This command tells \pgfname\ which layers will be used in pictures. They |
| 60 |
are stacked on top of each other in the order given. The layer |main| |
| 61 |
should always be part of the list. Here is an example: |
| 62 |
% |
| 63 |
\begin{codeexample}[code only] |
| 64 |
\pgfdeclarelayer{background} |
| 65 |
\pgfdeclarelayer{foreground} |
| 66 |
\pgfsetlayers{background,main,foreground} |
| 67 |
\end{codeexample} |
| 68 |
|
| 69 |
This command should be given either outside of any picture or ``directly |
| 70 |
inside'' of a picture. Here, the ``directly inside'' means that there |
| 71 |
should be no further level of \TeX\ grouping between |\pgfsetlayers| and |
| 72 |
the matching |\end{pgfpicture}| (no closing braces, no |\end{...}|). It |
| 73 |
will also work if |\pgfsetlayers| is provided before |\end{tikzpicture}| |
| 74 |
(with similar restrictions). |
| 75 |
\end{command} |
| 76 |
|
| 77 |
|
| 78 |
\subsection{Using Layers} |
| 79 |
|
| 80 |
Once the layers of your picture have been declared, you can start to ``fill'' |
| 81 |
them. As said before, all graphics commands are normally added to the |main| |
| 82 |
layer. Using the |{pgfonlayer}| environment, you can tell \pgfname\ that |
| 83 |
certain commands should, instead, be added to the given layer. |
| 84 |
|
| 85 |
\begin{environment}{{pgfonlayer}\marg{layer name}} |
| 86 |
The whole \meta{environment contents} is added to the layer with the name |
| 87 |
\meta{layer name}. This environment can be used anywhere inside a picture. |
| 88 |
Thus, even if it is used inside a |{pgfscope}| or a \TeX\ group, the |
| 89 |
contents will still be added to the ``whole'' picture. Using this |
| 90 |
environment multiple times inside the same picture will cause the |
| 91 |
\meta{environment contents} to accumulate. |
| 92 |
|
| 93 |
\emph{Note:} You can \emph{not} add anything to the |main| layer using this |
| 94 |
environment. The only way to add anything to the main layer is to give |
| 95 |
graphic commands outside all |{pgfonlayer}| environments. |
| 96 |
% |
| 97 |
\begin{codeexample}[] |
| 98 |
\pgfdeclarelayer{background layer} |
| 99 |
\pgfdeclarelayer{foreground layer} |
| 100 |
\pgfsetlayers{background layer,main,foreground layer} |
| 101 |
\begin{tikzpicture} |
| 102 |
% On main layer: |
| 103 |
\fill[blue] (0,0) circle (1cm); |
| 104 |
|
| 105 |
\begin{pgfonlayer}{background layer} |
| 106 |
\fill[yellow] (-1,-1) rectangle (1,1); |
| 107 |
\end{pgfonlayer} |
| 108 |
|
| 109 |
\begin{pgfonlayer}{foreground layer} |
| 110 |
\node[white] {foreground}; |
| 111 |
\end{pgfonlayer} |
| 112 |
|
| 113 |
\begin{pgfonlayer}{background layer} |
| 114 |
\fill[black] (-.8,-.8) rectangle (.8,.8); |
| 115 |
\end{pgfonlayer} |
| 116 |
|
| 117 |
% On main layer again: |
| 118 |
\fill[blue!50] (-.5,-1) rectangle (.5,1); |
| 119 |
\end{tikzpicture} |
| 120 |
\end{codeexample} |
| 121 |
% |
| 122 |
\end{environment} |
| 123 |
|
| 124 |
\begin{plainenvironment}{{pgfonlayer}\marg{layer name}} |
| 125 |
This is the plain \TeX\ version of the environment. |
| 126 |
\end{plainenvironment} |
| 127 |
|
| 128 |
\begin{contextenvironment}{{pgfonlayer}\marg{layer name}} |
| 129 |
This is the Con\TeX t version of the environment. |
| 130 |
\end{contextenvironment} |
| 131 |
|
| 132 |
|
| 133 |
%%% Local Variables: |
| 134 |
%%% mode: latex |
| 135 |
%%% TeX-master: "pgfmanual" |
| 136 |
%%% End: |