Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-paths.tex

raw
1 % Copyright 2018 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{The Soft Path Subsystem}
12 \label{section-soft-paths}
13
14 \makeatletter
15
16 This section describes a set of commands for creating \emph{soft paths} as
17 opposed to the commands of the previous section, which created \emph{hard
18 paths}. A soft path is a path that can still be ``changed'' or ``molded''. Once
19 you (or the \pgfname\ system) is satisfied with a soft path, it is turned into
20 a hard path, which can be inserted into the resulting |.pdf| or |.ps| file.
21
22 Note that the commands described in this section are ``high-level'' in the
23 sense that they are not implemented in driver files, but rather directly by the
24 \pgfname-system layer. For this reason, the commands for creating soft paths do
25 not start with |\pgfsys@|, but rather with |\pgfsyssoftpath@|. On the other
26 hand, as a user you will never use these commands directly, they are described
27 as part of the low-level interface.
28
29
30 \subsection{Path Creation Process}
31
32 When the user writes a command like |\draw (0bp,0bp) -- (10bp,0bp);| quite a
33 lot happens behind the scenes:
34 %
35 \begin{enumerate}
36 \item The frontend command is translated by \tikzname\ into commands of the
37 basic layer. In essence, the command is translated to something like
38 %
39 \begin{codeexample}[code only]
40 \pgfpathmoveto{\pgfpoint{0bp}{0bp}}
41 \pgfpathlineto{\pgfpoint{10bp}{0bp}}
42 \pgfusepath{stroke}
43 \end{codeexample}
44 %
45 \item The |\pgfpathxxxx| commands do \emph{not} directly call ``hard''
46 commands like |\pgfsys@xxxx|. Instead, the command |\pgfpathmoveto|
47 invokes a special command called |\pgfsyssoftpath@moveto| and
48 |\pgfpathlineto| invokes |\pgfsyssoftpath@lineto|.
49
50 The |\pgfsyssoftpath@xxxx| commands, which are described below,
51 construct a soft path. Each time such a command is used, special tokens
52 are added to the end of an internal macro that stores the soft path
53 currently being constructed.
54 \item When the |\pgfusepath| is encountered, the soft path stored in the
55 internal macro is ``invoked''. Only now does a special macro iterate
56 over the soft path. For each line-to or move-to operation on this path
57 it calls an appropriate |\pgfsys@moveto| or |\pgfsys@lineto| in order
58 to, finally, create the desired hard path, namely, the string of
59 literals in the |.pdf| or |.ps| file.
60 \item After the path has been invoked, |\pgfsys@stroke| is called to insert
61 the literal for stroking the path.
62 \end{enumerate}
63
64 Why such a complicated process? Why not have |\pgfpathlineto| directly call
65 |\pgfsys@lineto| and be done with it? There are two reasons:
66 %
67 \begin{enumerate}
68 \item The \pdf\ specification requires that a path is not interrupted by
69 any non-path-construction commands. Thus, the following code will
70 result in a corrupted |.pdf|:
71 %
72 \begin{codeexample}[code only]
73 \pgfsys@moveto{0}{0}
74 \pgfsys@setlinewidth{1}
75 \pgfsys@lineto{10}{0}
76 \pgfsys@stroke
77 \end{codeexample}
78 %
79 Such corrupt code is \emph{tolerated} by most viewers, but not always.
80 It is much better to create only (reasonably) legal code.
81 \item A soft path can still be changed, while a hard path is fixed. For
82 example, one can still change the starting and end points of a soft
83 path or do optimizations on it. Such transformations are not possible
84 on hard paths.
85 \end{enumerate}
86
87
88 \subsection{Starting and Ending a Soft Path}
89
90 No special action must be taken in order to start the creation of a soft path.
91 Rather, each time a command like |\pgfsyssoftpath@lineto| is called, a special
92 token is added to the (global) current soft path being constructed.
93
94 However, you can access and change the current soft path. In this way, it is
95 possible to store a soft path, to manipulate it, or to invoke it.
96
97 \begin{command}{\pgfsyssoftpath@getcurrentpath\marg{macro name}}
98 This command will store the current soft path in \meta{macro name}.
99 \end{command}
100
101 \begin{command}{\pgfsyssoftpath@setcurrentpath\marg{macro name}}
102 This command will set the current soft path to be the path stored in
103 \meta{macro name}. This macro should store a path that has previously been
104 extracted using the |\pgfsyssoftpath@getcurrentpath| command and has
105 possibly been modified subsequently.
106 \end{command}
107
108 \begin{command}{\pgfsyssoftpath@invokecurrentpath}
109 This command will turn the current soft path in a ``hard'' path. To do so,
110 it iterates over the soft path and calls an appropriate |\pgfsys@xxxx|
111 command for each element of the path. Note that the current soft path is
112 \emph{not changed} by this command. Thus, in order to start a new soft path
113 after the old one has been invoked and is no longer needed, you need to set
114 the current soft path to be empty. This may seem strange, but it is often
115 useful to immediately use the last soft path again.
116 \end{command}
117
118 \begin{command}{\pgfsyssoftpath@flushcurrentpath}
119 This command will invoke the current soft path and then set it to be empty.
120 \end{command}
121
122
123 \subsection{Soft Path Creation Commands}
124
125 \begin{command}{\pgfsyssoftpath@moveto\marg{x}\marg{y}}
126 This command appends a ``move-to'' segment to the current soft path. The
127 coordinates \meta{x} and \meta{y} are given as normal \TeX\ dimensions.
128
129 \example One way to draw a line:
130 %
131 \begin{codeexample}[code only]
132 \pgfsyssoftpath@moveto{0pt}{0pt}
133 \pgfsyssoftpath@lineto{10pt}{10pt}
134 \pgfsyssoftpath@flushcurrentpath
135 \pgfsys@stroke
136 \end{codeexample}
137 %
138 \end{command}
139
140 \begin{command}{\pgfsyssoftpath@lineto\marg{x}\marg{y}}
141 Appends a ``line-to'' segment to the current soft path.
142 \end{command}
143
144 \begin{command}{\pgfsyssoftpath@curveto\marg{a}\marg{b}\marg{c}\marg{d}\marg{x}\marg{y}}
145 Appends a ``curve-to'' segment to the current soft path with controls
146 $(a,b)$ and $(c,d)$.
147 \end{command}
148
149 \begin{command}{\pgfsyssoftpath@rect\marg{lower left x}\marg{lower left y}\marg{width}\marg{height}}
150 Appends a rectangle segment to the current soft path.
151 \end{command}
152
153 \begin{command}{\pgfsyssoftpath@closepath}
154 Appends a ``close-path'' segment to the current soft path.
155 \end{command}
156
157
158 \subsection{The Soft Path Data Structure}
159
160 A soft path is stored in a standardized way, which makes it possible to modify
161 it before it becomes ``hard''. Basically, a soft path is a long sequence of
162 triples. Each triple starts with a \emph{token} that identifies what is going
163 on. This token is followed by two dimensions in braces. For example, the
164 following is a soft path that means ``the path starts at $(0\mathrm{bp},
165 0\mathrm{bp})$ and then continues in a straight line to $(10\mathrm{bp},
166 0\mathrm{bp})$''.
167 %
168 \begin{codeexample}[code only]
169 \pgfsyssoftpath@movetotoken{0bp}{0bp}\pgfsyssoftpath@linetotoken{10bp}{0bp}
170 \end{codeexample}
171
172 A curve-to is hard to express in this way since we need six numbers to express
173 it, not two. For this reasons, a curve-to is expressed using three triples as
174 follows: The command
175 %
176 \begin{codeexample}[code only]
177 \pgfsyssoftpath@curveto{1bp}{2bp}{3bp}{4bp}{5bp}{6bp}
178 \end{codeexample}
179 %
180 \noindent results in the following three triples:
181 %
182 \begin{codeexample}[code only]
183 \pgfsyssoftpath@curvetosupportatoken{1bp}{2bp}
184 \pgfsyssoftpath@curvetosupportbtoken{3bp}{4bp}
185 \pgfsyssoftpath@curvetotoken{5bp}{6bp}
186 \end{codeexample}
187
188 These three triples must always ``remain together''. Thus, a lonely
189 |supportbtoken| is forbidden.
190
191 In details, the following tokens exist:
192 %
193 \begin{itemize}
194 \item \declare{|\pgfsyssoftpath@movetotoken|} indicates a move-to
195 operation. The two following numbers indicate the position to which the
196 current point should be moved.
197 \item \declare{|\pgfsyssoftpath@linetotoken|} indicates a line-to
198 operation.
199 \item \declare{|\pgfsyssoftpath@curvetosupportatoken|} indicates the first
200 control point of a curve-to operation. The triple must be followed by a
201 |\pgfsyssoftpath@curvetosupportbtoken|.
202 \item \declare{|\pgfsyssoftpath@curvetosupportbtoken|} indicates the second
203 control point of a curve-to operation. The triple must be followed by a
204 |\pgfsyssoftpath@curvetotoken|.
205 \item \declare{|\pgfsyssoftpath@curvetotoken|} indicates the target of a
206 curve-to operation.
207 \item \declare{|\pgfsyssoftpath@rectcornertoken|} indicates the corner of a
208 rectangle on the soft path. The triple must be followed by a
209 |\pgfsyssoftpath@rectsizetoken|.
210 \item \declare{|\pgfsyssoftpath@rectsizetoken|} indicates the size of a
211 rectangle on the soft path.
212 \item \declare{|\pgfsyssoftpath@closepath|} indicates that the subpath
213 begun with the last move-to operation should be closed. The parameter
214 numbers are currently not important, but if set to anything different
215 from |{0pt}{0pt}|, they should be set to the coordinate of the original
216 move-to operation to which the path ``returns'' now.
217 \end{itemize}