Debian Codegraph @

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

raw
1 % Copyright 2019 by Till Tantau and Mark Wibrow
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{Decorations}
12 \label{section-base-decorations}
13
14 \begin{pgfmodule}{decorations}
15 The commands for creating decorations are defined in this module, so you
16 need to load this module to use decorations. This module is automatically
17 loaded by the different decoration libraries.
18 \end{pgfmodule}
19
20
21 \subsection{Overview}
22
23 Decorations are a general way of creating graphics by ``moving along'' a path
24 and, while doing so, either drawing something or constructing a new path. This
25 could be as simple as extending a path with a ``zigzagged'' line\ldots
26 %
27 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
28 \tikz \draw decorate[decoration=zigzag] {(0,0) -- (3,0)};
29 \end{codeexample}
30 %
31 \ldots but could also be as complex as typesetting text along a path:
32 %
33 {\catcode`\|12
34 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.text}}]
35 \tikz \path decorate [decoration={text along path,
36 text={Some text along a path}}]
37 { (0,2) .. controls (2,2) and (1,0) .. (3,0) };
38 \end{codeexample}
39 }
40
41 The workflow for using decorations is the following:
42 %
43 \begin{enumerate}
44 \item You define a decoration using the |\pgfdeclaredecoration| command.
45 Different useful decorations are already declared in libraries like
46 |decorations.shapes|.
47 \item You use normal path construction commands like |\pgfpathlineto| to
48 construct a path. Let us call this path the \emph{to-be-decorated}
49 path.
50 \item You place the path construction commands inside the environment
51 |{pgfdecoration}|. This environment takes the name of a previously
52 declared decoration as a parameter. It will then start ``walking
53 along'' the to-be-decorated path. As it does this, a special finite
54 automaton called a \emph{decoration automaton} produces new path
55 commands as its output (or even other outputs). These outputs replace
56 the to-be-decorated path; indeed, after the to-be-decorated path has
57 been fully walked along it is thrown away, only the output of the
58 automaton persists.
59 \end{enumerate}
60
61 In the present section the process of how decoration automata work is explained
62 first. Then the command(s) for declaring decoration automata and for using them
63 are covered.
64
65
66 \subsection{Decoration Automata}
67
68 Decoration automata (and the closely related meta-decoration automata) are a
69 general concept for creating graphics ``along paths''. For straight lines, this
70 idea was first proposed by Till Tantau in an earlier version of \pgfname, the
71 idea to extend this to arbitrary path was proposed and implemented by Mark
72 Wibrow. Further versatility is provided by ``meta-decorations''. These are
73 automata that decorate a path with decorations.
74
75 In the present subsection the different ideas underlying decoration automata
76 are presented.
77
78
79 \subsubsection{The Different Paths}
80
81 In order to prevent confusion with different types of paths, such as those that
82 are extended, those that are decorated and those that are created, the
83 following conventions will be used:
84 %
85 \begin{itemize}
86 \item The \emph{preexisting} path refers to the current path in existence
87 before a decoration environment. (Possibly this path has been created
88 by another decoration used earlier, but we will still call this path
89 the preexisting path also in this case.)
90 \item The \emph{input} path refers to the to-be-decorated path that the
91 decoration automaton moves along. The input path may consist of many
92 line and curve input segments (for example, a circle or an ellipse
93 consists of four curves). It is specified inside the decoration
94 environment.
95 \item The \emph{output} path refers to the path that the decoration
96 creates. Depending on the decoration, this path may or may not be empty
97 (a decoration can also choose to use side-effects instead of producing
98 an output path). The input path is always consumed by the decoration
99 automaton, that is, it is no longer available in any way after the
100 decoration automaton has finished.
101 \end{itemize}
102
103 The effect of a decoration environment is the following: The input path, which
104 is specified inside the environment, is constructed and stored. This process
105 does not alter the preexisting path in any way. Then the decoration automaton
106 is started (as described later) and it produces an output path (possibly
107 empty). Whenever part of the output path is produced, it is concatenated with
108 the preexisting path. After the environment, the current path will equal the
109 original preexisting path followed by the output path.
110
111 It is permissible that a decoration issues a |\pgfusepath| command. As usual,
112 this causes the current path to be filled or stroked or some other action to be
113 taken and the current path is set to the empty path. As described above, when
114 the decoration automaton starts, the current path is the preexisting path and
115 as the automaton progresses, the current path is constantly being extended by
116 the output path. This means that first time a |\pgfusepath| command is used on
117 a decoration, the preexisting path is part of the path this command operates
118 on; in subsequent calls only the part of the output path constructed since the
119 last |\pgfusepath| command will be used.
120
121 You can use this mechanism to stroke or fill different parts of the output path
122 in different colors, line widths, fills and shades; all within the same
123 decoration. Alternatively, a decoration can choose to produce no output path at
124 all: the |text| decoration simply typesets text along a path.
125
126
127 \subsubsection{Segments and States}
128
129 The most common use of a decoration is to ``repeat something along a path''
130 (for example, the |zigzag| decoration repeats
131 %
132 \tikz\draw decorate[decoration=zigzag] {(0,0)--(\pgfdecorationsegmentlength,0)};
133 %
134 along a path). However, it not necessarily the case that only one thing is
135 repeated: a decoration can consist of different parts, or \emph{segments},
136 repeated in a particular order.
137
138 When you declare a decoration, you provide a description of how their different
139 segments will be rendered. The description of each segment should be given in a
140 way as if the ``$x$-axis'' of the segment is the tangent to the path at a
141 particular point, and that point is the origin of the segment. Thus, for
142 example, the segment of the |zigzag| decoration might be defined using the
143 following code:
144 %
145 \begin{codeexample}[code only]
146 \pgfpathlineto{\pgfpoint{5pt}{5pt}}
147 \pgfpathlineto{\pgfpoint{15pt}{-5pt}}
148 \pgfpathlineto{\pgfpoint{20pt}{0pt}}
149 \end{codeexample}
150
151 \pgfname\ will ensure that an appropriate coordinate transformation is in place
152 when the segment is rendered such that the segment actually points in the right
153 direction. Also, subsequent segments will be transformed such that they are
154 ``further along the path'' toward the end of the path. All transformations are
155 set up automatically.
156
157 Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the beginning
158 of the segment code. Doing so would subdivide the path into numerous subpaths.
159 Rather, we assume that the previous segment caused the current point to be at
160 the origin.
161
162 The width of a segment can (and must) be specified explicitly. \pgfname\ will
163 use this width to find out the start point of the next segment and the correct
164 rotation. The width the you provide need not be the ``real'' width of the
165 segment, which allows decoration segments to overlap or to be spaced far apart.
166
167 The |zigzag| decoration only has one segment that is repeated again and again.
168 However, we might also like to have \emph{different} segments and use rules to
169 describe which segment should be used where. For example, we might have special
170 segments at the start and at the end.
171
172 Decorations use a mechanism known in theoretical in computer science as
173 \emph{finite state automata} to describe which segment is used at a particular
174 point. The idea is the following: For the first segment we start in a special
175 \emph{state} called the \emph{initial state}. In this state, and also in all
176 other states later, \pgfname\ first computes how much space is left on the
177 input path. That is, \pgfname\ keeps track of the distance to the end of the
178 input path. Attached to each state there is a set of rules of the following
179 form: ``If the remaining distance on the input path is less than $x$, switch to
180 state~$q$.'' \pgfname\ checks for each of these rules whether it applies and,
181 if so, immediately switches to state~$q$.
182
183 Only if none of the rules tell us to switch to another state, \pgfname\ will
184 execute the state's code. This code will (typically) add a segment to the
185 output path. In addition to the rules there is also a width parameter attached
186 to each state. \pgfname\ then translates the coordinate system by this width
187 and reduces the remaining distance on the input path. Then, \pgfname\ either
188 stays in the current state or switches to another state, depending on yet
189 another property attached of the state.
190
191 The whole process stops when a special state called |final| is reached. The
192 segment of this state is immediately added to the output path (it is often
193 empty, though) and the process ends.
194
195
196 \subsection{Declaring Decorations}
197
198 The following command is used to declare a decoration. Essentially, this
199 command describes the decoration automaton.
200
201 \begin{command}{\pgfdeclaredecoration\marg{name}\marg{initial state}\marg{states}}
202 This command declares a new decoration called \meta{name}. The
203 \meta{states} argument contains a description of the decoration automaton's
204 states and the transitions between them. The \meta{initial state} is the
205 state in which the automaton starts.
206
207 When the automaton is later applied to an input path, it keeps track of a
208 certain position on the input path. This current point will ``travel along
209 the path'', each time being moved along by a certain distance. This will
210 also work if the path is not a straight line. That is, it is permissible
211 that the path curves are veers at a sharp angle. It is also permissible
212 that while traveling along the input path, the current input segment ends
213 and a new input segment starts. In this case, the remaining distance on the
214 first input segment is subtracted from the \meta{dimension} and then we
215 travel along the second input segment for the remaining distance. This
216 input segment may also end early, in which case we travel along the next
217 input segment, and so on. Note that it cannot happen that we travel past
218 the end of the input path since this would have caused an immediate switch
219 to the |final| state.
220
221 Note that the computation of the path lengths has only a low accuracy
222 because of \TeX's small math capabilities. Do not expect high accuracy
223 alignments when using decorations (unless the input path consists only of
224 horizontal and vertical lines).
225
226 The \meta{states} argument should consist of |\state| commands, one for
227 each state of the decoration automaton. The |\state| command is defined
228 only when the \meta{states} argument is executed.
229
230 \begin{command}{\state\marg{name}\oarg{options}\marg{code}}
231 This command declares a new state inside the current decoration
232 automaton. The state is named \meta{name}.
233
234 When the decoration automaton is in state \meta{name}, the following
235 things happen:
236 %
237 \begin{enumerate}
238 \item The \meta{options} are parsed. This may lead to a state
239 switch, see below. When this happens, the following steps are
240 not executed. The \meta{options} are executed one after the
241 other in the given order. If an option causes a state switch,
242 the switch is immediate, even if later options might cause a
243 different state switch.
244 \item The \meta{code} is executed in a \TeX-group with the current
245 transformation matrix set up in such a way that the origin is
246 on the input path at the current point (the point at the
247 distance traveled up to now) and the coordinate system is
248 rotated in such a way that the positive $x$-axis points in the
249 direction of the tangent to the input path at the current
250 point, while the positive $y$-axis points to the left of this
251 tangent.
252
253 As described earlier, the \meta{code} can have two different
254 effects: If it just contains path construction commands, the
255 decoration will produce an output path, that is, it extends the
256 preexisting path. Here is an example:
257 %
258 \begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
259 \pgfdeclaredecoration{example}{initial}
260 {
261 \state{initial}[width=10pt]
262 {
263 \pgfpathlineto{\pgfpoint{0pt}{5pt}}
264 \pgfpathlineto{\pgfpoint{5pt}{5pt}}
265 \pgfpathlineto{\pgfpoint{5pt}{-5pt}}
266 \pgfpathlineto{\pgfpoint{10pt}{-5pt}}
267 \pgfpathlineto{\pgfpoint{10pt}{0pt}}
268 }
269 \state{final}
270 {
271 \pgfpathlineto{\pgfpointdecoratedpathlast}
272 }
273 }
274 \tikz[decoration=example]
275 {
276 \draw [decorate] (0,0) -- (3,0);
277 \draw [red,decorate] (0,0) to [out=45,in=135] (3,0);
278 }
279 \end{codeexample}
280
281 Alternatively, the \meta{code} can also contain the
282 |\pgfusepath| command. This will use the path in the usual
283 manner, where ``the path'' is the preexisting path plus a part
284 of the output path for the first invocation and the different
285 parts of the rest of the output path for the following
286 invocation. Here is an example:
287 %
288 \begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations,shapes.geometric}}]
289 \pgfdeclaredecoration{stars}{initial}{
290 \state{initial}[width=15pt]
291 {
292 \pgfmathparse{round(rnd*100)}
293 \pgfsetfillcolor{yellow!\pgfmathresult!orange}
294 \pgfsetstrokecolor{yellow!\pgfmathresult!red}
295 \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}}
296 }
297 \state{final}
298 {
299 \pgfpathmoveto{\pgfpointdecoratedpathlast}
300 }
301 }
302 \tikz\path[decorate, decoration=stars, star point ratio=2, star points=5,
303 inner sep=0, minimum size=rnd*10pt+2pt]
304 (0,0) .. controls (0,2) and (3,2) .. (3,0)
305 .. controls (3,-3) and (0,0) .. (0,-3)
306 .. controls (0,-5) and (3,-5) .. (3,-3);
307 \end{codeexample}
308 %
309 \item After the \meta{code} has been executed (possibly more than
310 once, if the |repeat state| option is used), the state switches
311 to whatever state has been specified inside the \meta{options}
312 using the |next state| option. If no |next state| has been
313 specified, the state stays the same.
314 \end{enumerate}
315
316 The \meta{options} are executed with the key path set to
317 |/pgf/decoration automaton|. The following keys are defined:
318 %
319 \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}\texttt{ to }\meta{new state}}
320 When this key is encountered, \pgfname\ checks whether the
321 remaining distance to the end of the input path is less than
322 \meta{dimension}. If so, an immediate state switch to \meta{new
323 state} occurs.
324 \end{key}
325 %
326 \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}\texttt{ to }\meta{new state}}
327 When this key is encountered, \pgfname\ checks whether the
328 remaining distance to the end of the current input segment of the
329 input path is less than \meta{dimension}. If so, an immediate state
330 switch to \meta{new state} occurs.
331 \end{key}
332 %
333 \begin{key}{/pgf/decoration automaton/width=\meta{dimension}}
334 First, this option causes an immediate switch to the state |final|
335 if the remaining distance on the input path is less than
336 \meta{dimension}. The effect is the same as if you had said
337 |switch if less than=|\meta{dimension}| to final| just before the
338 |width| option.
339
340 If no switch occurs, this option tells \pgfname\ the width of the
341 segment. The current point will travel along the input path (as
342 described earlier) by this distance.
343 \end{key}
344 %
345 \begin{key}{/pgf/decoration automaton/repeat state=\meta{repetitions} (initially 0)}
346 Tells \pgfname\ how long the automaton stays ``normally'' in the
347 current state. This count is reset to \meta{repetitions} each time
348 one of the |switch if| keys causes a state switch. If no state
349 switches occur, the \meta{code} is executed and the repetition
350 counter is decreased. Then, there is once more a chance of a state
351 change caused by any of the \meta{options}. If no repetition
352 occurs, the \meta{code} is executed once more and the counter is
353 decreased once more. When the counter reaches zero, the \meta{code}
354 is executed once more, but, then, a different state is entered, as
355 specified by the |next state| option.
356
357 Note, that the maximum number of times the state will be executed
358 is $\meta{repetitions}+1$.
359 \end{key}
360 %
361 \begin{key}{/pgf/decoration automaton/next state=\meta{new state}}
362 After the \meta{code} for state has been executed for the last
363 time, a state switch to \meta{new state} is performed. If this
364 option is not given, the next state is the same as the current
365 state.
366 \end{key}
367
368 \begin{key}{/pgf/decoration automaton/if input segment is closepath=\meta{options}}
369 This key checks whether the current input segment is a closepath
370 operation. If so, the \meta{options} get executed; otherwise
371 nothing happens. You can use this option to handle a closepath in
372 some special way, for instance, switching to a new state in which
373 |\pgfpathclose| is executed.
374 \end{key}
375
376 \begin{key}{/pgf/decoration automaton/auto end on length=\meta{dimension}}
377 This key is just included for convenience, it does nothing that
378 cannot be achieved using the previous options. The effect is the
379 following: If the remaining input path's length is at most
380 \meta{dimension}, the decorated path is ended with a straight line
381 to the end of the input path and, possibly, it is closed, namely if
382 the input path ended with a closepath operation. Otherwise, it is
383 checked whether the current input segment is a closepath segment
384 and whether the remaining distance on the current input segment is
385 at most \meta{distance}. If so, then a closepath operation is used
386 to close the decorated path and the automaton continues with the
387 next subpath, remaining in the current state.
388
389 In all other cases, nothing happens.
390 \end{key}
391
392 \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}}
393 This key has the following effect: Firstly, in case the \TeX-if
394 |\ifpgfdecoratepathhascorners| is false, nothing happens.
395 Otherwise, it is tested whether the remaining distance on the
396 current input segment is at most \meta{dimension}. If so, a
397 |lineto| operation is used to reach the end of this input segment
398 and the automaton continues with the next input segment, but
399 remains in the current state.
400
401 The main idea behind this option is to avoid having decoration
402 segments ``overshoot'' past a corner.
403 \end{key}
404
405 You may sometimes wish to do computations outside the transformational
406 \TeX-group of the current segment, so that these results of these
407 computations are available in the next state. For this, the following
408 two options are useful:
409
410 \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}}
411 If the \meta{code} of the state is executed, the \meta{precode} is
412 executed first and it is executed outside the \TeX-group of the
413 \meta{code}. Note that when the \meta{precode} is executed, the
414 transformation matrix is not set up.
415 \end{key}
416
417 \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}}
418 Works like the |persistent precomputation| option, only the
419 \meta{postcode} is executed after (and also outside) the \TeX-group
420 of the main \meta{code}.
421 \end{key}
422
423 There are a number of macros and dimensions which may be useful inside
424 a decoration automaton. The following macros are available:
425
426 \begin{command}{\pgfdecoratedpathlength}
427 The length of the input path. If the input path consists of several
428 input segments, this number is the sum of the lengths of the input
429 segments.
430 \end{command}
431
432 \begin{command}{\pgfdecoratedinputsegmentlength}
433 The length of the current input segment of the input path.
434 ``Current input segment'' refers to the input segment on which the
435 current point lies.
436 \end{command}
437
438 \begin{command}{\pgfpointdecoratedpathlast}
439 The final point of the input path.
440 \end{command}
441
442 \begin{command}{\pgfpointdecoratedinputsegmentlast}
443 The final point of the current input segment of the input path.
444 \end{command}
445
446 \begin{command}{\pgfdecoratedangle}
447 The angle of the tangent to the decorated path at the \emph{origin}
448 of the current segment. The transformation matrix applied at the
449 beginning of a state includes a rotation equivalent to this angle.
450 \end{command}
451
452 The following \TeX\ dimension registers are also available inside the
453 automaton:
454
455 \begin{command}{\pgfdecoratedremainingdistance}
456 The remaining distance on the input path.
457 \end{command}
458
459 \begin{command}{\pgfdecoratedcompleteddistance}
460 The completed distance on the input path.
461 \end{command}
462
463 \begin{command}{\pgfdecoratedinputsegmentremainingdistance}
464 The remaining distance on the current input segment of the input path.
465 \end{command}
466
467 \begin{command}{\pgfdecoratedinputsegmentcompleteddistance}
468 The completed distance on the current input segment of the input path.
469 \end{command}
470
471 Further keys and macros are defined and used by the decoration
472 libraries, see Section~\ref{section-library-decorations}.
473
474 The following example shows how these options can be used:
475 %
476 \begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
477 \pgfdeclaredecoration{complicated example decoration}{initial}
478 {
479 \state{initial}[width=5pt,next state=up]
480 { \pgfpathlineto{\pgfpoint{5pt}{0pt}} }
481
482 \state{up}[width=5pt,next state=down]
483 {
484 \ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance
485 % Growing
486 \pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedcompleteddistance}}
487 \pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedcompleteddistance}}
488 \pgfpathlineto{\pgfpoint{5pt}{0pt}}
489 \else
490 % Shrinking
491 \pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedremainingdistance}}
492 \pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedremainingdistance}}
493 \pgfpathlineto{\pgfpoint{5pt}{0pt}}
494 \fi%
495 }
496 \state{down}[width=5pt,next state=up]
497 {
498 \ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance
499 % Growing
500 \pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedcompleteddistance}}
501 \pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedcompleteddistance}}
502 \pgfpathlineto{\pgfpoint{5pt}{0pt}}
503 \else
504 % Shrinking
505 \pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedremainingdistance}}
506 \pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedremainingdistance}}
507 \pgfpathlineto{\pgfpoint{5pt}{0pt}}
508 \fi%
509 }
510 \state{final}
511 {
512 \pgfpathlineto{\pgfpointdecoratedpathlast}
513 }
514 }
515 \begin{tikzpicture}[decoration=complicated example decoration]
516 \draw decorate{ (0,0) -- (3,0)};
517 \fill [red!50,rounded corners=2pt]
518 decorate {(.5,-2) -- ++(2.5,-2.5)} -- (3,-5) -| (0,-2) -- cycle;
519 \end{tikzpicture}
520 \end{codeexample}
521 \end{command}
522 \end{command}
523
524
525 \subsubsection{Predefined Decorations}
526
527 The three decorations |moveto|, |lineto|, and |curveto| are predefined and
528 ``always available''. They are mostly useful in conjunction with
529 meta-decorations. They are documented in
530 Section~\ref{section-library-decorations} alongside the other decorations.
531
532
533 \subsection{Using Decorations}
534
535 Once a decoration has been declared, it can be used.
536
537 \begin{environment}{{pgfdecoration}\marg{decoration list}}
538 The \meta{environment contents} should contain commands for creating an
539 path. This path is the basis for the \emph{input paths} for the decorations
540 in the \meta{decoration list}. In detail, the following happens:
541 %
542 \begin{enumerate}
543 \item The preexisting unused path is saved.
544 \item The path commands specified in \meta{environment contents} are
545 executed and this resulting path is saved. The path is then divided
546 into different \emph{input paths} as follows: The format for each
547 item in \marg{decoration list} is
548 %
549 \begin{quote}
550 \marg{decoration}\marg{length}\opt{\marg{before code}\marg{after code}}
551 \end{quote}
552 %
553 The \meta{before code} and the \meta{after code} are optional. The
554 input path is divided into input paths as follows: The first input
555 path consists of the first lines of the path specified in the
556 \meta{environment contents} until the \meta{length} of the first
557 element of the \meta{decoration list} is reached. If this length is
558 reached in the middle of a line, the line is broken up at this
559 exact position. Then the second input path has the \meta{length} of
560 the second element in the \meta{decoration list} and consists of
561 the lines making up the following \meta{length} part of the path in
562 the \meta{environment contents}, and so on.
563
564 If the lengths in the \meta{decoration list} do not add up to the
565 total length of the path in the \meta{environment contents}, either
566 some decorations are dropped (if their lengths add up to more than
567 the length of the \meta{environment contents}) or the input path is
568 not fully used (if their lengths add up to less).
569 \item The preexisting path is reinstalled.
570 \item The decoration automata move along the input paths, thus creating
571 (and possibly using) the output paths. These output paths extend
572 the current path (unless they are used).
573 \end{enumerate}
574
575 Some important points should be noted regarding the use of this
576 environment:
577 %
578 \begin{itemize}
579 \item If \meta{environment contents} does not begin with
580 |\pgfpathmoveto|, the last known point on the preexisting path is
581 assumed as the starting point.
582 \item All except the last of any sequence of consecutive move-to
583 commands in \meta{environment contents} are discarded.
584 \item Any move-to commands at the end of \meta{environment contents}
585 are ignored.
586 \item Any close-path commands on the input path are interpreted as
587 straight lines. Internally, something a little more complicated is
588 going on, however, a closed path on the input path has no effect on
589 the output path, other than causing the automaton to travel in a
590 straight line towards the location of the last move-to command on
591 the input path.
592 \item Although tangent computations for the input path work with the
593 last point on the preexisting path, no automatic move-to operations
594 are issued for the output path. If an output path starts with a
595 line-to or curve-to when the existing path is empty, an appropriate
596 move-to command should be inserted before the decoration starts.
597 \item If a decoration uses its own path, the first time this happens
598 the preexisting path is part of the path that is used at this
599 point.
600 \end{itemize}
601
602 Before the automata start to ``work on'' their respective inputs paths,
603 \meta{before code} is executed. After the decoration automaton has
604 finished, \meta{after code} is executed.
605 %
606 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
607 \begin{tikzpicture}[decoration={segment length=5pt}]
608 \draw [help lines] grid (3,2);
609 \begin{pgfdecoration}{{curveto}{1cm},{zigzag}{2cm},{curveto}{1cm}}
610 \pgfpathmoveto{\pgfpointorigin}
611 \pgfpathcurveto
612 {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
613 \end{pgfdecoration}
614 \pgfusepath{stroke}
615 \end{tikzpicture}
616 \end{codeexample}
617
618 When the lengths are evaluated, the dimension
619 |\pgfdecoratedremainingdistance| holds the remaining distance on the entire
620 decorated path, and |\pgfdecoratedpathlength| holds the total length of the
621 path. Thus, it is possible to specify lengths like
622 |\pgfdecoratedpathlength/3|.
623 %
624 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
625 \begin{tikzpicture}[decoration={segment length=5pt}]
626 \draw [help lines] grid (3,2);
627 \begin{pgfdecoration}{
628 {curveto}{\pgfdecoratedpathlength/3},
629 {zigzag}{\pgfdecoratedpathlength/3},
630 {curveto}{\pgfdecoratedremainingdistance}
631 }
632 \pgfpathmoveto{\pgfpointorigin}
633 \pgfpathcurveto
634 {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
635 \end{pgfdecoration}
636 \pgfusepath{stroke}
637 \end{tikzpicture}
638 \end{codeexample}
639
640 When \meta{before code} is executed, the following macro is useful:
641 %
642 \begin{command}{\pgfpointdecoratedpathfirst}
643 Returns the point corresponding to the start of the current input path.
644 \end{command}
645 %
646 When \meta{after code} is executed, the following macro can be used:
647 %
648 \begin{command}{\pgfpointdecoratedpathlast}
649 Returns the point corresponding to the end of the current input path.
650 \end{command}
651 %
652 This means that if decorations do not use their own path, it is possible to
653 do something with them and continue from the correct place.
654 %
655 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
656 \begin{tikzpicture}
657 \draw [help lines] grid (3,2);
658 \begin{pgfdecoration}{
659 {curveto}{\pgfdecoratedpathlength/3}
660 {}
661 {
662 \pgfusepath{stroke}
663 },
664 {zigzag}{\pgfdecoratedpathlength/3}
665 {
666 \pgfpathmoveto{\pgfpointdecoratedpathfirst}
667 \pgfdecorationsegmentlength=5pt
668 }
669 {
670 \pgfsetstrokecolor{red}
671 \pgfusepath{stroke}
672 \pgfpathmoveto{\pgfpointdecoratedpathlast}
673 \pgfsetstrokecolor{black}
674 },
675 {curveto}{\pgfdecoratedremainingdistance}
676 }
677 \pgfpathmoveto{\pgfpointorigin}
678 \pgfpathcurveto
679 {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
680 \end{pgfdecoration}
681 \pgfusepath{stroke}
682 \end{tikzpicture}
683 \end{codeexample}
684
685 After the |{decoration}| environment has finished, the following macros are
686 available:
687
688 \begin{command}{\pgfdecorateexistingpath}
689 The preexisting path before the environment was entered.
690 \end{command}
691
692 \begin{command}{\pgfdecoratedpath}
693 The (total) input path (that is, the path created by the environment
694 contents).
695 \end{command}
696
697 \begin{command}{\pgfdecorationpath}
698 The output path. If the path is used, this macro contains only the last
699 unused part of the output path.
700 \end{command}
701
702 \begin{command}{\pgfpointdecoratedpathlast}
703 The final point of the input path.
704 \end{command}
705
706 \begin{command}{\pgfpointdecorationpathlast}
707 The final point of the output path.
708 \end{command}
709
710 The following style is executed each time a decoration is used. You may use
711 it to set up default options for decorations.
712 %
713 \begin{stylekey}{/pgf/every decoration (initially \normalfont empty)}
714 This style is executed for every decoration.
715 \end{stylekey}
716 \end{environment}
717
718 \begin{plainenvironment}{{pgfdecoration}\marg{name}}
719 The plain-\TeX{} version of the |{pgfdecorate}| environment.
720 \todosp{`pgfdecorate' right or `pgfdecoration'? really no idea}
721 \end{plainenvironment}
722
723 \begin{contextenvironment}{{pgfdecoration}\marg{name}}
724 The Con\TeX t version of the |{pgfdecoration}| environment.
725 \end{contextenvironment}
726
727 For convenience, the following macros provide a ``shorthand'' for decorations
728 (internally, they all use the |{pgfdecoration}| environment).
729
730 \begin{command}{\pgfdecoratepath\marg{name}\marg{path commands}}
731 Decorate the path described by \meta{path commands} with the decoration
732 \meta{name}. This is equivalent to
733 %
734 \begin{codeexample}[code only]
735 \pgfdecoration{{name}{\pgfdecoratedpathlength}
736 {\pgfdecoratebeforecode}{\pgfdecorateaftercode}}
737 // the path commands.
738 \endpgfdecoration
739 \end{codeexample}
740 %
741 \end{command}
742
743 \begin{command}{\pgfdecoratecurrentpath\marg{name}}
744 Decorate the preexisting path with the decoration \meta{name}.
745 \end{command}
746
747 Both the above commands use the current definitions of the following macros:
748
749 \begin{command}{\pgfdecoratebeforecode}
750 Code executed as \meta{before code}, see the description of
751 |\pgfdecoration|.
752 \end{command}
753
754 \begin{command}{\pgfdecorateaftercode}
755 Code executed as \meta{after code}, see the description of
756 |\pgfdecoration|.
757 \end{command}
758
759 It may sometimes be useful to add an additional transformation for each segment
760 of a decoration. The following command allows you to define such a ``last
761 minute transformation''.
762
763 \begin{command}{\pgfsetdecorationsegmenttransformation\marg{code}}
764 The \meta{code} will be executed at the very beginning of each segment.
765 Note when applying multiple decorations, this will be reset between
766 decorations, so it needs to be specified for each segment.
767 %
768 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
769 \begin{tikzpicture}
770 \draw [help lines] grid (3,2);
771 \begin{pgfdecoration}{
772 {curveto}{\pgfdecoratedpathlength/3},
773 {zigzag}{\pgfdecoratedpathlength/3}
774 {
775 \pgfdecorationsegmentlength=5pt
776 \pgfsetdecorationsegmenttransformation{\pgftransformyshift{.5cm}}
777 },
778 {curveto}{\pgfdecoratedremainingdistance}
779 }
780 \pgfpathmoveto{\pgfpointorigin}
781 \pgfpathcurveto
782 {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
783 \end{pgfdecoration}
784 \pgfusepath{stroke}
785 \end{tikzpicture}
786 \end{codeexample}
787 %
788 \end{command}
789
790
791 \subsection{Meta-Decorations}
792 \label{section-base-meta-decorations}
793
794 A meta-decoration provides an alternative way to decorate a path with multiple
795 decorations. It is, in essence, an automaton that decorates an input path with
796 decoration automatons. In general, however, the end effect is still that a path
797 is decorated with other paths, and the input path should be thought of as being
798 divided into sub-input-paths, each with their own decoration. Like ordinary
799 decorations, a meta-decoration must be declared before it can be used.
800
801
802 \subsubsection{Declaring Meta-Decorations}
803
804 \begin{command}{\pgfdeclaremetadecorate\marg{name}\marg{initial state}\marg{states}}
805 This command declares a new meta-decoration called \meta{name}. The
806 \meta{states} argument contains a description of the meta-decoration
807 automaton's states and the transitions between them. The \meta{initial
808 state} is the state in which the automaton starts.
809
810 The |\state| command is similar to the one found in decoration
811 declarations, and takes the same form:
812
813 \begin{command}{\state\marg{name}\oarg{options}\marg{code}} Declares the
814 state \meta{name} inside the current meta-decoration automaton. Unlike
815 decorations, states in meta-decorations are not executed within a
816 group, which makes the persistent computation options superfluous.
817 Consider using an initial state with |width=0pt| to do precalculations
818 that could speed the execution of the meta-decoration.
819
820 The \meta{options} are executed with the key path set to
821 |/pgf/meta-decorations automaton/|, and the following keys are defined
822 for this path:
823
824 \begin{key}{/pgf/meta-decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}}
825 This causes \pgfname\ to check whether the remaining distance to
826 the end of the input path is less than \meta{dimension}, and, if
827 so, to immediately switch to the state \meta{new state}. When this
828 key is evaluated, the macro |\pgfmetadecoratedpathlength| will be
829 defined as the total length of the decoration path, allowing for
830 values such as |\pgfmetadecoratedpathlength/8|.
831 \end{key}
832
833 \begin{key}{/pgf/meta-decoration automaton/width=\meta{dimension}}
834 As always, this option will cause an immediate switch to the state
835 |final| if the remaining distance on the input path is less than
836 \meta{dimension}.
837
838 Otherwise, this option tells \pgfname\ the width of the
839 ``meta-segment'', that is, the length of the sub-input-path which
840 the decoration automaton specified in \meta{code} will decorate.
841 \end{key}
842
843 \begin{key}{/pgf/meta-decoration automaton/next state=\meta{new state}}
844 After the code for a state has been executed, a state switch to
845 \meta{new state} is performed. If this option is not given, the
846 next state is the same as the current state.
847 \end{key}
848
849 The code in \meta{code} is quite different from the code in a
850 decoration state. In almost all cases only the following three macros
851 will be required:
852
853 \begin{command}{\decoration\marg{name}}
854 This sets the decoration for the current state to \meta{name}. If
855 this command is omitted, the |moveto| decoration will be used.
856 \end{command}
857
858 \begin{command}{\beforedecoration\marg{before code}}
859 Defines \meta{before code} as (typically) \pgfname{} commands to be
860 executed before the decoration is applied to the current segment.
861 This command can be omitted. If you wish to set up some decoration
862 specific parameters such as segment length, or segment amplitude,
863 then they can be set in \meta{before code}.
864 \end{command}
865
866 \begin{command}{\afterdecoration\marg{after code}}
867 Defines \meta{after code} as commands to be executed after the
868 decoration has been applied to the current segment. This command
869 can be omitted.
870 \end{command}
871
872 There are some macros that may be useful when creating meta-decorations
873 (note that they are all macros):
874
875 \begin{command}{\pgfpointmetadecoratedpathfirst}
876 When the \meta{before code} is executed, this macro stores the
877 first point on the current sub-input-path.
878 \end{command}
879
880 \begin{command}{\pgfpointmetadecoratedpathlast}
881 When the \meta{after code} is executed, this macro stores the last
882 point on the current sub-input-path.
883 \end{command}
884
885 \begin{command}{\pgfmetadecoratedpathlength}
886 The entire length of the entire input path.
887 \end{command}
888
889 \begin{command}{\pgfmetadecoratedcompleteddistance}
890 The completed distance on the entire input path.
891 \end{command}
892
893 \begin{command}{\pgfmetadecoratedremainingdistance}
894 The remaining distance on the entire input path.
895 \end{command}
896
897 \begin{command}{\pgfmetadecoratedinputsegmentcompleteddistance}
898 The completed distance on the current input segment of the entire
899 input path.
900 \end{command}
901
902 \begin{command}{\pgfmetadecoratedinputsegmentremainingdistance}
903 The remaining distance on the current input segment of the entire
904 input path.
905 \end{command}
906 \end{command}
907
908 Here is a complete example of a meta-decoration:
909 %
910 \begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
911 \pgfdeclaremetadecoration{arrows}{initial}{
912 \state{initial}[width=0pt, next state=arrow]
913 {
914 \pgfmathdivide{100}{\pgfmetadecoratedpathlength}
915 \let\factor\pgfmathresult
916 \pgfsetlinewidth{1pt}
917 \pgfset{/pgf/decoration/segment length=4pt}
918 }
919 \state{arrow}[
920 switch if less than=\pgfmetadecorationsegmentlength to final,
921 width=\pgfmetadecorationsegmentlength/3,
922 next state=zigzag]
923 {
924 \decoration{curveto}
925 \beforedecoration
926 {
927 \pgfmathparse{\pgfmetadecoratedcompleteddistance*\factor}
928 \pgfsetcolor{red!\pgfmathresult!yellow}
929 \pgfpathmoveto{\pgfpointmetadecoratedpathfirst}
930 }
931 }
932 \state{zigzag}[width=\pgfmetadecorationsegmentlength/3, next state=end arrow]
933 {
934 \decoration{zigzag}
935 }
936 \state{end arrow}[width=\pgfmetadecorationsegmentlength/3, next state=move]
937 {
938 \decoration{curveto}
939 \beforedecoration{\pgfpathmoveto{\pgfpointmetadecoratedpathfirst}}
940 \afterdecoration
941 {
942 \pgfsetarrowsend{to}
943 \pgfusepath{stroke}
944 }
945 }
946 \state{move}[width=\pgfmetadecorationsegmentlength/2, next state=arrow]{}
947 \state{final}{}
948 }
949
950 \tikz\draw[decorate,decoration={arrows,meta-segment length=2cm}]
951 (0,0) .. controls (0,2) and (3,2) .. (3,0)
952 .. controls (3,-2) and (0,-2) .. (0,-4)
953 .. controls (0,-6) and (3,-6) .. (3,-8)
954 .. controls (3,-10) and (0,-10) .. (0,-8);
955 \end{codeexample}
956 %
957 \end{command}
958
959
960 \subsubsection{Predefined Meta-decorations}
961
962 There are no predefined meta-decorations loaded with \pgfname{}.
963
964
965 \subsubsection{Using Meta-Decorations}
966
967 Using meta-decorations is ``simpler'' than using decorations, because you can
968 only use one meta-decoration per path.
969
970 \begin{environment}{{pgfmetadecoration}\marg{name}}
971 This environment decorates the input path described in \meta{environment
972 contents}, with the meta-decoration \meta{name}.
973 \end{environment}
974
975 \begin{plainenvironment}{{pgfmetadecoration}\marg{name}}
976 The plain \TeX{} version of the |{pgfmetadecoration}| environment.
977 \end{plainenvironment}
978
979 \begin{contextenvironment}{{pgfmetadecoration}\marg{name}}
980 The Con\TeX t version of the |{pgfmetadecoration}| environment.
981 \end{contextenvironment}