| 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} |