Debian Codegraph @

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

raw
1 % Copyright 2019 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{Patterns}
12 \label{section-patterns}
13
14 \subsection{Overview}
15
16 There are many ways of filling a path. First, you can fill it using a solid
17 color and this is also the fastest method. Second, you can also fill it using a
18 shading, which means that the color changes smoothly between two (or more)
19 different colors. Third, you can fill it using a tiling pattern and it is
20 explained in the following how this is done.
21
22 A tiling pattern can be imagined as a rectangular tile (hence the name) on
23 which a small picture is painted. There is not a single tile, but
24 (conceptually) an infinite number of tiles, all showing the same picture, and
25 these tiles are arranged horizontally and vertically to fill the plane. When
26 you use a tiling pattern to fill a path, what happens is that the path clips
27 out a ``window'' through which we see part of this infinite plane.
28
29 Patterns come in two versions: \emph{inherently colored patterns} and
30 \emph{form-only patterns}. (These are often called ``color patterns'' and
31 ``uncolored patterns'', but these names are misleading since uncolored patterns
32 do have a color and the color changes. As I said, the name is misleading\dots)
33 An inherently colored pattern is just a colored tile like, say, a red star with
34 a black outline. A form-only pattern can be imagined as a tile that is a kind
35 of rubber stamp. When this pattern is used, the stamp is used to print copies
36 of the stamp picture onto the plane, but we can use a different stamp color
37 each time we use a form-only pattern.
38
39 \pgfname\ provides a special support for patterns. You can declare a pattern
40 and then use it very much like a fill color. \pgfname\ directly maps patterns
41 to the pattern facilities of the underlying graphic languages (PostScript,
42 \textsc{pdf}, and \textsc{svg}). This means that filling a path using a pattern
43 will be nearly as fast as if you used a uniform color.
44
45 There are a number of pitfalls and restrictions when using patterns. First,
46 once a pattern has been declared, you cannot change it anymore. In particular,
47 it is not possible to enlarge it or change the line width. Such flexibility
48 would require that the repeating of the pattern were not done by the graphic
49 language, but on the \pgfname\ level. This would make patterns orders of
50 magnitude slower to produce and to render. However, \pgfname{} does provide a
51 more-or-less successful emulation of ``mutable'' patterns, although internally,
52 a new (fixed) instance of a pattern is declared when the parameters of a
53 pattern change.
54
55 Second, the phase of patterns is not well-defined, that is, it is not clear
56 where the origin of the ``first'' tile is. To be more precise, PostScript and
57 \textsc{pdf} on the one hand and \textsc{svg} on the other hand define the
58 origin differently. PostScript and \textsc{pdf} define a fixed origin that is
59 independent of where the path lies. This has the highly desirable effect that
60 if you use the same pattern to fill multiple paths, the outcome is the same as
61 if you had filled a single path consisting of the union of all these paths. By
62 comparison, \textsc{svg} uses the upper-left (?) corner of the path to be
63 filled as the origin. However, the \textsc{svg} specification is a bit vague on
64 this question.
65
66
67 \subsection{Declaring a Pattern}
68
69 Before a pattern can be used, it must be declared. The following command is
70 used for this:
71
72 \begin{command}{\pgfdeclarepatternformonly%
73 \opt{\oarg{variables}}%
74 \marg{name}%
75 \marg{bottom left}%
76 \marg{top right}%
77 \marg{tile size}%
78 \marg{code}%
79 }
80 This command declares a new form-only pattern. The \meta{name} is a name
81 for later reference. The two parameters \meta{lower left} and \meta{upper
82 right} must describe a bounding box that is large enough to encompass the
83 complete tile.
84
85 The size of a tile is given by \meta{tile size}, that is, a tile is a
86 rectangle whose lower left corner is the origin and whose upper right
87 corner is given by \meta{tile size}. This might make you wonder why the
88 second and third parameters are needed. First, the bounding box might be
89 smaller than the tile size if the tile is larger than the picture on the
90 tile. Second, the bounding box might be bigger, in which case the picture
91 will ``bleed'' over the tile.
92
93 The \meta{code} should be \pgfname\ code than can be protocolled. It should
94 not contain any color code.
95 %
96 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
97 \pgfdeclarepatternformonly{stars}
98 {\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
99 {\pgfpoint{1cm}{1cm}}
100 {
101 \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
102 \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
103 \pgfpathlineto{\pgfpointpolar{144}{4mm}}
104 \pgfpathlineto{\pgfpointpolar{288}{4mm}}
105 \pgfpathlineto{\pgfpointpolar{72}{4mm}}
106 \pgfpathlineto{\pgfpointpolar{216}{4mm}}
107 \pgfpathclose%
108 \pgfusepath{fill}
109 }
110 \begin{tikzpicture}
111 \filldraw[pattern=stars] (0,0) rectangle (1.5,2);
112 \filldraw[pattern=stars,pattern color=red]
113 (1.5,0) rectangle (3,2);
114 \end{tikzpicture}
115 \end{codeexample}
116
117 The optional argument \meta{variables} consists of a comma separated list
118 of macros, registers or keys, representing the parameters of the pattern
119 that may vary. If a variable is a key, then the full path name must be used
120 (specifically, it must start with |/|). As an example, a list might look
121 like the following: |\mymacro,\mydimen,/pgf/my key|. Note that macros and
122 keys should be ``simple''. They should only store values in themselves.
123
124 The effect of \meta{variables}, is the following: Normally, when this
125 argument is empty, once a pattern has been declared, it becomes ``frozen''.
126 This means that it is not possible to enlarge the pattern or change the
127 line width later on. By specifying \meta{variables}, no pattern is actually
128 created. Instead, the arguments are stored away (so the macros, registers
129 or keys do not have to be defined in advance).
130
131 When the fill pattern is set, \pgfname{} checks if the pattern has already
132 been created with the \meta{variables} set to their current values
133 (\pgfname{} is usually ``smart enough'' to distinguish between macros,
134 registers and keys). If so, this already-declared-pattern is used as the
135 fill pattern. If not, a new instance of the pattern (which will have a
136 unique internal name) is declared using the current values of
137 \meta{variables}. These values are then saved and the fill pattern set
138 accordingly.
139
140 The following shows an example of a pattern which varies according to the
141 values of the macro |\size|, the key |/tikz/radius|, and the \TeX{}
142 dimension |\thickness|.
143 %
144 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
145 \pgfdeclarepatternformonly[/tikz/radius,\thickness,\size]{rings}
146 {\pgfpoint{-0.5*\size}{-0.5*\size}}
147 {\pgfpoint{0.5*\size}{0.5*\size}}
148 {\pgfpoint{\size}{\size}}
149 {
150 \pgfsetlinewidth{\thickness}
151 \pgfpathcircle\pgfpointorigin{\pgfkeysvalueof{/tikz/radius}}
152 \pgfusepath{stroke}
153 }
154 \newdimen\thickness
155 \tikzset{
156 radius/.initial=4pt,
157 size/.store in=\size, size=20pt,
158 thickness/.code={\thickness=#1},
159 thickness=0.75pt
160 }
161 \begin{tikzpicture}[rings/.style={pattern=rings}]
162 \filldraw [rings, radius=2pt, size=6pt] (0,0) rectangle +(1.5,2);
163 \filldraw [rings, radius=2pt, size=8pt] (2,0) rectangle +(1.5,2);
164 \filldraw [rings, radius=6pt, thickness=2pt] (0,2.5) rectangle +(1.5,2);
165 \filldraw [rings, radius=8pt, thickness=4pt] (2,2.5) rectangle +(1.5,2);
166 \end{tikzpicture}
167 \end{codeexample}
168 %
169 \end{command}
170
171 \begin{command}{\pgfdeclarepatterninherentlycolored
172 \opt{\oarg{variables}}
173 \marg{name}
174 \marg{lower left}
175 \marg{upper right}
176 \marg{tile size}
177 \marg{code}%
178 }
179 This command works like |\pgfdeclarepatternuncolored|, only the pattern
180 will have an inherent color. To set the color, you should use \pgfname's
181 color commands, not the |\color| command, since this fill is not
182 protocolled.
183 %
184 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
185 \pgfdeclarepatterninherentlycolored{green stars}
186 {\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
187 {\pgfpoint{1cm}{1cm}}
188 {
189 \pgfsetfillcolor{green!50!black}
190 \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
191 \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
192 \pgfpathlineto{\pgfpointpolar{144}{4mm}}
193 \pgfpathlineto{\pgfpointpolar{288}{4mm}}
194 \pgfpathlineto{\pgfpointpolar{72}{4mm}}
195 \pgfpathlineto{\pgfpointpolar{216}{4mm}}
196 \pgfpathclose%
197 \pgfusepath{stroke,fill}
198 }
199 \begin{tikzpicture}
200 \filldraw[pattern=green stars] (0,0) rectangle (3,2);
201 \end{tikzpicture}
202 \end{codeexample}
203 %
204 \end{command}
205
206
207 \subsection{Setting a Pattern}
208
209 Once a pattern has been declared, it can be used.
210
211 \begin{command}{\pgfsetfillpattern\marg{name}\marg{color}}
212 This command specifies that paths that are filled should be filled with the
213 ``color'' by the pattern \meta{name}. For an inherently colored pattern,
214 the \meta{color} parameter is ignored. For form-only patterns, the
215 \meta{color} parameter specifies the color to be used for the pattern.
216 %
217 \begin{codeexample}[
218 preamble={\usetikzlibrary{patterns}
219 \pgfdeclarepatternformonly{stars}
220 {\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
221 {\pgfpoint{1cm}{1cm}}
222 {
223 \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
224 \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
225 \pgfpathlineto{\pgfpointpolar{144}{4mm}}
226 \pgfpathlineto{\pgfpointpolar{288}{4mm}}
227 \pgfpathlineto{\pgfpointpolar{72}{4mm}}
228 \pgfpathlineto{\pgfpointpolar{216}{4mm}}
229 \pgfpathclose%
230 \pgfusepath{fill}
231 }
232 \pgfdeclarepatterninherentlycolored{green stars}
233 {\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
234 {\pgfpoint{1cm}{1cm}}
235 {
236 \pgfsetfillcolor{green!50!black}
237 \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
238 \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
239 \pgfpathlineto{\pgfpointpolar{144}{4mm}}
240 \pgfpathlineto{\pgfpointpolar{288}{4mm}}
241 \pgfpathlineto{\pgfpointpolar{72}{4mm}}
242 \pgfpathlineto{\pgfpointpolar{216}{4mm}}
243 \pgfpathclose%
244 \pgfusepath{stroke,fill}
245 }}]
246 \begin{tikzpicture}
247 \pgfsetfillpattern{stars}{red}
248 \filldraw (0,0) rectangle (1.5,2);
249
250 \pgfsetfillpattern{green stars}{red}
251 \filldraw (1.5,0) rectangle (3,2);
252 \end{tikzpicture}
253 \end{codeexample}
254 %
255 \end{command}
256
257
258 %%% Local Variables:
259 %%% mode: latex
260 %%% TeX-master: "pgfmanual"
261 %%% End: