Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-layers.tex

raw
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: