diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex | 1014 |
1 files changed, 1014 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex new file mode 100644 index 00000000000..21ddb1f445c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex @@ -0,0 +1,1014 @@ + % Copyright 2008 by Till Tantau and Mark Wibrow +% +% 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{Decorations} +\label{section-base-decorations} + + +\begin{pgfmodule}{decorations} + The commands for creating decorations are defined in this + module, so you need to load this module to use decorations. This + module is automatically loaded by the different decoration + libraries. +\end{pgfmodule} + + +\subsection{Overview} + +Decorations are a general way of creating graphics by ``moving along'' +a path and, while doing so, either drawing something or constructing a +new path. This could be as simple as extending a path with a +``zigzagged'' line\ldots + +\begin{codeexample}[] +\tikz \draw decorate[decoration=zigzag] {(0,0) -- (3,0)}; +\end{codeexample} +\ldots but could also be as complex as typesetting text along a path: +{\catcode`\|12 +\begin{codeexample}[] +\tikz \path decorate [decoration={text along path, + text={Some text along a path}}] + { (0,2) .. controls (2,2) and (1,0) .. (3,0) }; +\end{codeexample} +} + +The workflow for using decorations is the following: +\begin{enumerate} +\item You define a decoration using the |\pgfdeclaredecoration| + command. Different useful decorations are already declared in + libraries like |decorations.shapes|. +\item You use normal path construction commands like |\pgfpathlineto| + to construct a path. Let us call this path the + \emph{to-be-decorated} path. +\item You place the path construction commands inside the environment + |{pgfdecoration}|. This environment takes the name of a previously + declared decoration as a parameter. It will then starting ``walking + along'' the to-be-decorated path. As it does this, a special finite + automaton called a \emph{decoration automaton} produces as its + output new path construction commands (or even other outputs). These + outputs replace the to-be-decorated path; indeed, after the + to-be-decorated path has been fully walked along it is thrown away, + only the output of the automaton persists. +\end{enumerate} + +In the present section the process of how decoration automata work is +explained first. Then the command(s) for declaring decoration automata +and for using them are covered. + + + +\subsection{Decoration Automata} + +Decoration automata (and the closely related meta-decoration automata) +are a general concept for creating graphics ``along paths.'' For +straight lines, this idea was first proposed by Till Tantau in an +earlier version of \pgfname, the idea to extend this to arbitrary path +was proposed and implemented by Mark Wibrow. Further versitility is +provided by ``meta-decorations''. These are automata that decorate a +path with decorations. + +In the present subsection the different ideas underlying decoration +automata are presented. + + + +\subsubsection{The Different Paths} + +In order to prevent confusion with different types of path, such +as those that are extended, those that are decorated and those that +are created, the following conventions will be used: + +\begin{itemize} +\item + The \emph{preexisting} path refers to the current path in existence + before a decoration environment. (Possibly this path has been + created by another decoration used earlier, but we will still call + this path the preexisting path also in this case.) +\item + The \emph{input} path refers to the to-be-decorated path that the + decoration automaton moves along. The input path may consist of many + line and curve input segments (for example, a circle or an ellipse + consists of four curves). It is specified inside the decoration + environment. +\item + The \emph{output} path refers to the path that the decoration + creates. Depending on the decoration, this path may or may not be + empty (a decoration can also choose to use side-effects instead of + producing an output path). The input path is always consumed by the + decoration automaton, that is, it is no longer available in any way + after the decoration automaton has finished. +\end{itemize} + +The effect of a decoration environment is the following: The input +path, which is specified inside the environment, is constructed and +stored. This process does not alter the preexisting path in any +way. Then the decoration automaton is started (as described later) and +it produces an output path (possibly empty). Whenever part of the +output path is produced, it is concatenated with the preexisting +path. After the environment, the current path will equal the original +preexisting path followed by the output path. + +It is permissible that a decoration issues a |\pgfusepath| +command. As usual, this causes the current path to be +filled or stroked or some other action to be taken and the current +path is set to the empty path. As described above, when the decoration +automaton starts the current path is the preexisting path and as the +automaton progresses, the current path is constantly being extend by +the output path. This means that first time e |\pgfusepath| command is +used on a decoration, the preexisting path is part of the path this +command operates on; in subsequent calls only the part of the output +path constructed since the last |\pgfusepath| command will be used. + +You can use this mechanism to stroke or fill different part of the +output path in different colors, line widths, fills and shades; all +within the same decoration. Alternatively, a decoration can choose to +produce no output path at all: the |text| decoration simply typesets +text along a path. + + +\subsubsection{Segments and States} + +The most common use a decoration is to ``repeat something along a +path'' (for example, the |zigzag| decoration +repeats \tikz\draw decorate[decoration=zigzag] +{(0,0)--(\pgfdecorationsegmentlength,0)}; along a path). However, it +not necessarily the case that only one thing be repeated: a decoration +can consist of different parts, or \emph{segments}, repeated in a +particular order. + +When you declare a decoration, you provide a description +of how their different segments will be rendered. The description of +each segment should be given in a way as if the ``x-axis'' of the +segment is the tangent to the path at a particular point, +and that point is the origin of the segment. +Thus, for example, the segment of the |zigzag| decoration might be +defined using the following code: +\begin{codeexample}[code only] +\pgfpathlineto{\pgfpoint{5pt}{5pt}} +\pgfpathlineto{\pgfpoint{15pt}{-5pt}} +\pgfpathlineto{\pgfpoint{20pt}{0pt}} +\end{codeexample} + +\pgfname\ will ensure that an appropriate coordinate transformation +is in place when the segment is rendered such that +the segment actually points in the right direction. Also +subsequent segments will be transformed such that they are +``further along the path'' toward the end of the path. +All transformations are setup automatically. + +Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the +beginning of the segment code. Doing so would subdivide the path into +numerous subpaths. Rather, we assume that the previous segment caused +the current point to be at the origin. + +The width of a segment can (and must) be specified +explicitly. \pgfname\ will use this width to find out the start point +of the next segment and the correct rotation. The width the you +provide need not be the ``real'' width of the segment, which allows +decoration segments to overlap or to be spaced far apart. + +The |zigzag| decoration only has one segment that is repeated again and +again. However, we might also like to have \emph{different} segments +and use rules to describe which segment should be used where. For +example, we might have special segments at the start and at the end. + +Decorations use a mechanism known in theoretical in computer science +as \emph{finite state automata} to describe which segment is used at a +particular point. The idea is the following: For the first segment we +start in a special \emph{state} called the \emph{initial state}. In +this state, and also in all other state later, \pgfname\ first +computes how much space is left on the input path. That is, \pgfname\ keeps +track of the distance to the end of the input path. Attached to each state +there is a set of rules of the following form: ``If the remaining +distance on the input path is less than $x$, switch to state~$q$.'' +\pgfname\ checks for each of these rules whether it applies and, if +so, immediately switches to state~$q$. + +Only if none of the rules tell us to switch to another +state, \pgfname\ will execute the state's code. This code will +(typically) add a segment to the output path. In addition to the rules +there is also width parameter attached to each state. \pgfname\ then +translates the coordinate system by this width and reduces the +remaining distance on the input path. Then, \pgfname\ either stays in +the current state or switches to another state, depending on yet +another property attached of the state. + +The whole process stops when a special state called |final| is +reached. The segment of this state is immediately added to the output +path (it is often empty, though) and the process ends. + + + + +\subsection{Declaring Decorations} + +The following command is used to declare a decoration. Essentially, +this command describes the decoration automaton. + + +\begin{command}{\pgfdeclaredecoration\marg{name}\marg{initial + state}\marg{states}} + This command declares a new decoration called \meta{name}. The + \meta{states} argument contains a description of the decoration + automaton's states and the transitions between them. The + \meta{initial state} is the state in which the automaton starts. + + When the automaton is later applied to an input path, it keeps track + of a certain position on the input path. This current point + will ``travel along the path,'' each time being moved along by a + certain distance. This will also work if the path is not a straight + line. That is, it is permissible that the path curves are veers at a + sharp angle. It is also permissible that while travelling along the + input path the current input segment ends and a new input segment starts. In this + case, the remaining distance on the first input segment is subtracted + from the \meta{dimension} and then we travelled along the second + input segment for the remaining distance. This input segment may also end + early, in which case we travel along the next input segment, and so + on. Note that it cannot happen that we travel past the end of the + input path since this would have caused an immediate switch to + the |final| state. + + Note note that the computation of the path lengths has only a low + accuracy because of \TeX's small math capabilities. Do not + expect high accuracy alignments when using decorations (unless the + input path consists only of horizontal and vertical lines). + + The \meta{states} argument should consist of |\state| commands, one + for each state of the decoration automaton. The |\state| command is + defined only when the \meta{states} argument is executed. + + \begin{command}{\state\marg{name}\oarg{options}\marg{code}} + This command declares a new state inside the current decoration + automaton. The state is named \meta{name}. + + When the decoration automaton is in state \meta{name}, the following things + happen: + \begin{enumerate} + \item + The \meta{options} are parsed. This may lead, see below, to a + state switch. When this happens, the following steps are not + executed. The \meta{options} are executed one after the other in + the given order. If an option causes a state switch, the switch + is immediate, even if later options might cause a different + state switch. + \item + The \meta{code} is executed in a \TeX-group with the current + transformation matrix setup in such a way that the origin is on + the input path at the current point (the point at the distance + travelled up to now) and the coordinate system is rotated in + such a way that the positive $x$-axis points in the direction of + the tangent to the input path at the current point, while the + positive $y$-axis points to the left of this tangent. + + As described earlier, the \meta{code} can have two different + effects: If it just contains path construction commands, the + decoration will produce an output path, which is extends the + preexisting path. Here is an example: + +\begin{codeexample}[] +\pgfdeclaredecoration{example}{initial} +{ + \state{initial}[width=10pt] + { + \pgfpathlineto{\pgfpoint{0pt}{5pt}} + \pgfpathlineto{\pgfpoint{5pt}{5pt}} + \pgfpathlineto{\pgfpoint{5pt}{-5pt}} + \pgfpathlineto{\pgfpoint{10pt}{-5pt}} + \pgfpathlineto{\pgfpoint{10pt}{0pt}} + } + \state{final} + { + \pgfpathlineto{\pgfpointdecoratedpathlast} + } +} +\tikz[decoration=example] +{ + \draw [decorate] (0,0) -- (3,0); + \draw [red,decorate] (0,0) to [out=45,in=135] (3,0); +} +\end{codeexample} + + Alternatively, the \meta{code} can also contain the + |\pgfusepath| command. This will use the path in usual manner, + where ``the path'' is the preexisting path plus a part of the + output path for the first invocation and the different parts of + the rest of the output path for the following invocation. Here is + an example: + +\begin{codeexample}[] +\pgfdeclaredecoration{stars}{initial}{ + \state{initial}[width=15pt] + { + \pgfmathparse{round(rnd*100)} + \pgfsetfillcolor{yellow!\pgfmathresult!orange} + \pgfsetstrokecolor{yellow!\pgfmathresult!red} + \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}} + } + \state{final} + { + \pgfpathmoveto{\pgfpointdecoratedpathlast} + } +} +\tikz\path[decorate, decoration=stars, star point ratio=2, star points=5, + inner sep=0, minimum size=rnd*10pt+2pt] + (0,0) .. controls (0,2) and (3,2) .. (3,0) + .. controls (3,-3) and (0,0) .. (0,-3) + .. controls (0,-5) and (3,-5) .. (3,-3); +\end{codeexample} + + \item + After the \meta{code} has been executed (possibly more than + once, if the |repeat state| option is used), the state switches to + whatever state has been specified inside the \meta{options} + using the |next state| option. If no |next state| has been + specified, the state stays the same. + \end{enumerate} + + The \meta{options} are executed with the key path set to + |/pgf/decoration automaton|. The following keys are defined: + \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}} + When this key is encountered, \pgfname\ checks whether the + remaining distance to the end of the input path is less than + \meta{dimension}. If so, an immediate state switch to \meta{new + state} occurs. + \end{key} + \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}| to |\meta{new state}} + When this key is encountered, \pgfname\ checks whether the + remaining distance to the end of the current input segment of the + input path is less than \meta{dimension}. If so, an immediate + state switch to \meta{new state} occurs. + \end{key} + \begin{key}{/pgf/decoration automaton/width=\meta{dimension}} + First, this option causes an immediate switch to the + state |final| if the remaining distance on the input path is + less than \meta{dimension}. The effect is the same as if you had + said |switch if less than=|\meta{dimension}| to final| just + before the |width| option. + + If no switch occurs, this option tells \pgfname\ the width of + the segment. The current point will travel along the input path + (as described earlier) by this distance. + \end{key} + \begin{key}{/pgf/decoration automaton/repeat state=\meta{repetitions} (initially 0)} + Tells \pgfname\ how long the automaton stays ``normally'' in the + current state. This count is reset to \meta{repetitions} each + time one of the |switch if| keys causes a state switch. If no + state switches occur, the \meta{code} is executed and the + repetition counter is decreased. Then, there is once more a + chance of a state change caused by any of the \meta{options}. If + no repetition occurs, the \meta{code} is executed + once more and the counter is decreased once more. When the + counter reaches zero, the \meta{code} is executed once more, + but, then, a different state is entered, as specified by the + |next state| option. + + Note, that the maximum number of times the state will be executed + is $\meta{repetitions}+1$. + \end{key} + \begin{key}{/pgf/decoration automaton/next state=\meta{new state}} + After the \meta{code} for state has been executed for the last + time, a state switch to \meta{new state} is performed. If this + option is not given, the next state is the same as the current state. + \end{key} + + \begin{key}{/pgf/decoration automaton/if input segment is closepath=\meta{options}} + This key checks whether the current input segment is a closepath + operation. If so, the \meta{options} get executed; otherwise + nothing happens. You can use this option to handle a closepath + in some special way, for instance, switching to a new state in + which |\pgfpathclose| is executed. + \end{key} + + \begin{key}{/pgf/decoration automaton/auto end on length=\meta{dimension}} + This key is just included for convenience, it does nothing that + cannot be achieved using the previous options. The effect is the + following: If the remaingin input path's length is at most + \meta{dimension}, the decorated path is ended with a straight + line to the end of the input path and, possibly, it is closed, + namely if the input path ended with a closepath + operation. Otherwise, it is checked whether the current input + segment is a closepath segment and whether the remaining + distance on the current input segment is at most + \meta{distance}. If so, the a closepath operation is used to + close the decorated path and the automaton continues with the + next subpath, remaining in the current state. + + In all other cases, nothing happens. + \end{key} + + \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}} + This key has the following effect: Firstly, the \TeX-if + |\ifpgfdecoratepathhascorners| is false, nothing + happens. Otherwise, it is tested whether the remaining distance + on the current input segment is at most \meta{dimension}. If so, + a lineto operation is used to reach the end of this input + segment and the automaton continues with the next input segment, + but remains in the current state. + + The main idea behind this option is to avoid having decoration + segments ``overshoot'' past a corner. + \end{key} + + You may sometimes wish to do computations outside the + transformational \TeX-group of the current segment, + so that these results of these computations are available in the + next state. For this, the following two options are useful: + + \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}} + If the \meta{code} of state is executed, the \meta{precode} is + executed first and it executed outside the \TeX-group of the + \meta{code}. Note that when the \meta{precode} is executed, the + transformation matrix is not setup. + \end{key} + + \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}} + Works like the |persistent precomputation| option, only the + \meta{postcode} is executed after (and also outside) the + \TeX-group of the main \meta{code}. + \end{key} + + There are a number of macros and dimensions which may be useful + inside a decoration automaton. The following macros are available: + + \begin{command}{\pgfdecoratedpathlength} + The length of the input path. If the input path consists of + several input segments, this number is the sum of the lengths of the + input segments. + \end{command} + + \begin{command}{\pgfdecoratedinputsegmentlength} + The length of the current input segment of the input path. ``Current + input segment'' refers to the input segment on which the current point + lies. + \end{command} + + \begin{command}{\pgfpointdecoratedpathlast} + The final point of the input path. + \end{command} + + \begin{command}{\pgfpointdecoratedinputsegmentlast} + The final point of the current input segment of the input path. + \end{command} + + \begin{command}{\pgfdecoratedangle} + The angle of the tangent to the decorated path at the \emph{origin} + of the current segment. The transformation matrix applied at + the beginning of a state includes a rotation equivalent to + this angle. + \end{command} + + The following \TeX\ dimension registers are also available inside the + automaton: + + \begin{command}{\pgfdecoratedremainingdistance} + The remaining distance on the input path. + \end{command} + + \begin{command}{\pgfdecoratedcompleteddistance} + The completed distance on the input path. + \end{command} + + \begin{command}{\pgfdecoratedinputsegmentremainingdistance} + The remaining distance on the current input segment of the input path. + \end{command} + + \begin{command}{\pgfdecoratedinputsegmentcompleteddistance} + The completed distance on the current input segment of the input path. + \end{command} + + Further keys and macros are defined and used by the decoration + libraries, see Section~\ref{section-library-decorations}. + + The following example shows how these options can be used: +\begin{codeexample}[] +\pgfdeclaredecoration{complicated example decoration}{initial} +{ + \state{initial}[width=5pt,next state=up] + { \pgfpathlineto{\pgfpoint{5pt}{0pt}} } + + \state{up}[width=5pt,next state=down] + { + \ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance + % Growing + \pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedcompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedcompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \else + % Shrinking + \pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \fi% + } + \state{down}[width=5pt,next state=up] + { + \ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance + % Growing + \pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedcompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedcompleteddistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \else + % Shrinking + \pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedremainingdistance}} + \pgfpathlineto{\pgfpoint{5pt}{0pt}} + \fi% + } + \state{final} + { + \pgfpathlineto{\pgfpointdecoratedpathlast} + } +} +\begin{tikzpicture}[decoration=complicated example decoration] + \draw decorate{ (0,0) -- (3,0)}; + \fill [red!50,rounded corners=2pt] + decorate {(.5,-2) -- ++(2.5,-2.5)} -- (3,-5) -| (0,-2) -- cycle; +\end{tikzpicture} +\end{codeexample} + \end{command} +\end{command} + + + +\subsubsection{Predefined Decorations} + +The three decorations |moveto|, |lineto|, and |curveto| are predefined +and ``always available.'' They are mostly useful in conjunction with +meta-decorations. They are documented in +Section~\ref{section-library-decorations} alongside the other +decorations. + + + +\subsection{Using Decorations} + +Once a decoration has been declared, it can be used. + +\begin{environment}{{pgfdecoration}\marg{decoration list}} + The \meta{environment contents} should contain commands for creating + an path. This path is the basis for the \emph{input paths} + for the decorations in the \meta{decoration list}. In detail, the + following happens: + \begin{enumerate} + \item + The preexisting unused path is saved. + \item + The path commands specified in \meta{environment contents} are + executed and this resulting path is saved. The path is then + divided into different \emph{input paths} as follows: + The format for each item in \marg{decoration list} is + \begin{quote} + \marg{decoration}\marg{length}\opt{\marg{before code}\marg{after code}} + \end{quote} + The \meta{before code} and the \meta{after code} are optional. The + input path is divided into input paths as follows: The first input + path consists of the first lines of the path specified in the + \meta{environment contents} until the \meta{length} of the first + element of the \meta{decoration list} is reached. If this length + is reached in the middle of a line, the line is broken up at this + exact position. Then the second input path has the \meta{length} + of the second element in the \meta{decoration list} and consists + of the lines making up the following \meta{length} part of the + path in the \meta{environment contents}, and so on. + + If the lengths in the \meta{decoration list} + do not add up to the total length of the path in the + \meta{environment contents}, either some decorations are dropped + (if their lengths add up to more than the length of the + \meta{environment contents}) or + the input path is not fully used (if their lengths add up to less). + \item + The preexisting path is reinstalled. + \item + The decoration automata move along the input paths, thus creating + (and possibly using) the output paths. These output paths extend + (unless they are used) the current path. + \end{enumerate} + + Some important points should be noted regarding the use of this + environment: + + \begin{itemize} + \item + If \meta{environment contents} does not begin with + |\pgfpathmoveto|, he last known point on the preexisting path is + assumed as the starting point. + \item + All except the last of any sequence of consecutive move-to commands + in \meta{environment contents} are discarded. + \item + Any move-to commands at end of \meta{environment contents} are + ignored. + \item + Any close-path commands on the input path are interpreted as + straight lines. + Internally somthing a little more complicated is going on, + however, a closed path on the input path has no effect on the + output path, other than causing the automaton to travel in a + straight line towards the location of the last move-to command on + the input path. + \item + Although tangent computations for the input path work with the + last point on the preexisting path, no automatic move-to + operations are issued for the output path. + If an output path commences with a line-to or curve-to when the + existing path is empty, an appropriate move-to command should be + inserted before the decoration commences. + \item + If a decoration uses its own path, the first time this happens the + preexisting path is part of the path that is used at this point. + \end{itemize} + + When the decoration automata ``work on'' their respective input + paths, before the automaton starts, \meta{before code} is + executed. After the decoration automaton has finished, \meta{after + code} is executed. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={segment length=5pt}] + \draw [help lines] grid (3,2); + \begin{pgfdecoration}{{curveto}{1cm},{zigzag}{2cm},{curveto}{1cm}} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} + \end{pgfdecoration} +\pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + When the lengths are evaluated, the dimension + |\pgfdecoratedremainingdistance| holds the remaining distance on + the entire decorated path, and |\pgfdecoratedpathlength| holds the + total length of the path. Thus, it is possible to specify lengths + like |\pgfdecoratedpathlength/3|. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={segment length=5pt}] + \draw [help lines] grid (3,2); + \begin{pgfdecoration}{ + {curveto}{\pgfdecoratedpathlength/3}, + {zigzag}{\pgfdecoratedpathlength/3}, + {curveto}{\pgfdecoratedremainingdistance} + } + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} + \end{pgfdecoration} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + When \meta{before code} is executed, the following macro is useful: + \begin{command}{\pgfpointdecoratedpathfirst} + Returns the point corresponding to the start of the current + input path. + \end{command} + When \meta{after code} is executed, the following macro can be used: + \begin{command}{\pgfpointdecoratedpathlast} + Returns the point corresponding to the end of the current input + path. + \end{command} + This means that if decorations do not use their own path, it is + possible to do something with them and and continue from the + correct place. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] grid (3,2); + \begin{pgfdecoration}{ + {curveto}{\pgfdecoratedpathlength/3} + {} + { + \pgfusepath{stroke} + }, + {zigzag}{\pgfdecoratedpathlength/3} + { + \pgfpathmoveto{\pgfpointdecoratedpathfirst} + \pgfdecorationsegmentlength=5pt + } + { + \pgfsetstrokecolor{red} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointdecoratedpathlast} + \pgfsetstrokecolor{black} + }, + {curveto}{\pgfdecoratedremainingdistance} + } + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} + \end{pgfdecoration} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + + After the |{decoration}| environment has finished, the following + macros are available: + + \begin{command}{\pgfdecorateexistingpath} + The preexisting path before the environment was entered. + \end{command} + + \begin{command}{\pgfdecoratedpath} + The (total) input path (that is, the path created by the environment contents). + \end{command} + + \begin{command}{\pgfdecorationpath} + The output path. If the path is used, this macro contains only the + last unused part of the output path. + \end{command} + + \begin{command}{\pgfpointdecoratedpathlast} + The final point of the input path. + \end{command} + + \begin{command}{\pgfpointdecorationpathlast} + The final point of the output path. + \end{command} + + The following style is executed each time a decoration is used. You + may use it to setup default options for decorations. + \begin{stylekey}{/pgf/every decoration (initially \normalfont empty)} + This sytle is executed for every decoration. + \end{stylekey} +\end{environment} + +\begin{plainenvironment}{{pgfdecoration}\marg{name}} + The plain-\TeX{} version of the |{pgfdecorate}| environment. +\end{plainenvironment} + +\begin{contextenvironment}{{pgfdecoration}\marg{name}} + The Con\TeX t version of the |{pgfdecoration}| environment. +\end{contextenvironment} + +For convenience, the following macros provide a ``shorthand'' +for decorations (internally, they all use the |{pgfdecoration}| +environment). + +\begin{command}{\pgfdecoratepath\marg{name}\marg{path commands}} + Decorate the path described by \meta{path commands} with the + decoration \meta{name}. This is equivalent to +\begin{codeexample}[code only] +\pgfdecorate{{name}{\pgfdecoratedpathlength} + {\pgfdecoratebeforecode}{\pgfdecorateaftercode}} + // the path commands. +\endpgfdecorate +\end{codeexample} +\end{command} + +\begin{command}{\pgfdecoratecurrentpath\marg{name}} + Decorate the preexisting path with the decoration \meta{name}. +\end{command} + +Both the above commands use the current definitons of the following +macros: + +\begin{command}{\pgfdecoratebeforecode} + Code executed as \meta{before code}, see the description of + |\pgfdecorate|. +\end{command} + +\begin{command}{\pgfdecorateaftercode} + Code executed as \meta{after code}, see the description of + |\pgfdecorate|. +\end{command} + +It may sometimes be useful to add an additional transformation +for each segment of a decoration. The following command allows +you to define such a ``last minute transformation.'' + +\begin{command}{\pgfsetdecorationsegmenttransformation\marg{code}} + The \meta{code} will be executed at the very beginning of each + segment. Note when applying multiple decorations, this will + be reset between decorations, so it needs to be specified for + each segment. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] grid (3,2); + \begin{pgfdecoration}{ + {curveto}{\pgfdecoratedpathlength/3}, + {zigzag}{\pgfdecoratedpathlength/3} + { + \pgfdecorationsegmentlength=5pt + \pgfsetdecorationsegmenttransformation{\pgftransformyshift{.5cm}} + }, + {curveto}{\pgfdecoratedremainingdistance} + } + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} + \end{pgfdecoration} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + + + +\subsection{Meta-Decorations} + +\label{section-base-meta-decorations} + +A meta-decoration provides an alternative way to decorate a path with +mutiple decorations. It is, in essence, an automaton that decorates +an input path with decoration automatons. In general, however, the end +effect is still that a path is decorated with other paths, and the input +path should be thought of as being divided into sub-input-paths, each with +their own decoration. Like ordinary decorations, before a +meta-decoration can be used it must be declared. + +\subsubsection{Declaring Meta-Decorations} + +\begin{command}{\pgfdeclaremetadecorate\marg{name}\marg{initial state}\marg{states}} + + This command declares a new meta-decoration called \meta{name}. The + \meta{states} argument contains a description of the meta-decoration + automaton's states and the transitions between them. The + \meta{initial state} is the state in which the automaton starts. + + The |\state| command is similar to the one found in + decoration declarations, and takes the same form: + + \begin{command}{\state\marg{name}\oarg{options}\marg{code}} + Declares the state \meta{name} inside the current meta-decoration + automaton. Unlike decorations, states in meta-decorations are not + executed within a group, which makes the persistent computation + options superfluous. Consider using an initial state with + |width=0pt| to do precalculations that could speed the execution + of the meta-decoration. + + The \meta{options} are executed with the key path set to + |/pgf/meta-decorations automaton/|, and the following keys are defined for + this path: + + \begin{key}{/pgf/meta-decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}} + This causes \pgfname\ to check whether the + remaining distance to the end of the input path is less than + \meta{dimension}, and, if so, to immediately switch to the state + \meta{new state}. When this key is evaluated, the macro + |\pgfmetadecoratedpathlength| will be defined as the total length of + the decoration path, allowing for values such as + |\pgfmetadecoratedpathlength/8|. + \end{key} + + \begin{key}{/pgf/meta-decoration automaton/width=\meta{dimension}} + As always, this option will cause an immediate switch to the + state |final| if the remaining distance on the input path is less than + \meta{dimension}. + + Otherwise, this option tells \pgfname\ the width of the + ``meta-segment'', that is, the length of the sub-input-path + which the decoration automaton specified in \meta{code} will decorate. + \end{key} + + \begin{key}{/pgf/meta-decoration automaton/next state=\meta{new state}} + After the code for a state has been executed, a state switch to + \meta{new state} is performed. If this option is not given, the + next state is the same as the current state. + \end{key} + + The code in \meta{code} is quite different from the code in a + decoration state. In almost all cases only the following three + macros will be required: + + \begin{command}{\decoration\marg{name}} + This sets the decoration for the current state to \meta{name}. + If this command is omitted, the |moveto| decoration will be + used. + \end{command} + + \begin{command}{\beforedecoration\marg{before code}} + Defines \marg{before code} as (typically) \pgfname{} commands to be + executed before the decoration is applied to the current segment. + This command can be omitted. + If you wish to set up some decoration specific parameters + such as segment length, or segment amplitude, then they + can be set in \meta{before code}. + \end{command} + + \begin{command}{\afterdecoration\marg{after code}} + Defines \marg{after code} as commands to be executed afer the + decoration has been applied to the current segment. + This command can be omitted. + \end{command} + + There are some macros that may be usedful when creating + meta-decorations (note that they are all macros): + + \begin{command}{\pgfpointmetadecoratedpathfirst} + When the \meta{before code} is executed, + this macro stores the first point on the current + sub-input-path. + \end{command} + + \begin{command}{\pgfpointmetadecoratedpathlast} + When the \meta{after code} is executed, + this macro stores the last point on the current + sub-input-path. + \end{command} + + \begin{command}{\pgfmetadecoratedpathlength} + The entire length of the entire input path. + \end{command} + + \begin{command}{\pgfmetadecoratedcompleteddistance} + The completed distance on the entire input path. + \end{command} + + \begin{command}{\pgfmetadecoratedremainingdistance} + The remaining distance on the entire input path. + \end{command} + + \begin{command}{\pgfmetadecoratedinputsegmentcompleteddistance} + The completed distance on the current input segment of the entire + input path. + \end{command} + + \begin{command}{\pgfmetadecoratedinputsegmentremainingdistance} + The remaining distance on the current input segment of the entire + input path. + \end{command} + \end{command} + + Here is a complete example of a meta-decoration: + +\begin{codeexample}[] +\pgfdeclaremetadecoration{arrows}{initial}{ + \state{initial}[width=0pt, next state=arrow] + { + \pgfmathdivide{100}{\pgfmetadecoratedpathlength} + \let\factor\pgfmathresult + \pgfsetlinewidth{1pt} + \pgfset{/pgf/decoration/segment length=4pt} + } + \state{arrow}[ + switch if less than=\pgfmetadecorationsegmentlength to final, + width=\pgfmetadecorationsegmentlength/3, + next state=zigzag] + { + \decoration{curveto} + \beforedecoration + { + \pgfmathparse{\pgfmetadecoratedcompleteddistance*\factor} + \pgfsetcolor{red!\pgfmathresult!yellow} + \pgfpathmoveto{\pgfpointmetadecoratedpathfirst} + } + } + \state{zigzag}[width=\pgfmetadecorationsegmentlength/3, next state=end arrow] + { + \decoration{zigzag} + } + \state{end arrow}[width=\pgfmetadecorationsegmentlength/3, next state=move] + { + \decoration{curveto} + \beforedecoration{\pgfpathmoveto{\pgfpointmetadecoratedpathfirst}} + \afterdecoration + { + \pgfsetarrowsend{to} + \pgfusepath{stroke} + } + } + \state{move}[width=\pgfmetadecorationsegmentlength/2, next state=arrow]{} + \state{final}{} +} + +\tikz\draw[decorate,decoration={arrows,meta-segment length=2cm}] + (0,0) .. controls (0,2) and (3,2) .. (3,0) + .. controls (3,-2) and (0,-2) .. (0,-4) + .. controls (0,-6) and (3,-6) .. (3,-8) + .. controls (3,-10) and (0,-10) .. (0,-8); +\end{codeexample} + +\end{command} + + +\subsubsection{Predefined Meta-decorations} + +There are no predefined meta-decorations loaded with \pgfname{}. + + +\subsubsection{Using Meta-Decorations} + +Using meta-decorations is ``simpler'' than using decorations, because +you can only use one meta-decoration per path. + +\begin{environment}{{pgfmetadecoration}\marg{name}} + This environment decorates the input path described in + \meta{environment contents}, with the meta-decoration \meta{name}. +\end{environment} + +\begin{plainenvironment}{{pgfmetadecoration}\marg{name}} + The plain \TeX{} version of the |{pgfmetadecoration}| environment. +\end{plainenvironment} + +\begin{contextenvironment}{{pgfmetadecoration}\marg{name}} + The Con\TeX t version of the |{pgfmetadecoration}| environment. +\end{contextenvironment} |