diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex | 257 |
1 files changed, 117 insertions, 140 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex index a59b203b28d..e432823121d 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex @@ -8,233 +8,210 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. - \section{The Soft Path Subsystem} - \label{section-soft-paths} \makeatletter +This section describes a set of commands for creating \emph{soft paths} as +opposed to the commands of the previous section, which created \emph{hard +paths}. A soft path is a path that can still be ``changed'' or ``molded''. Once +you (or the \pgfname\ system) is satisfied with a soft path, it is turned into +a hard path, which can be inserted into the resulting |.pdf| or |.ps| file. -This section describes a set of commands for creating \emph{soft - paths} as opposed to the commands of the previous section, which -created \emph{hard paths}. A soft path is a path that can still be -``changed'' or ``molded.'' Once you (or the \pgfname\ system) is -satisfied with a soft path, it is turned into a hard path, which can -be inserted into the resulting |.pdf| or |.ps| file. - -Note that the commands described in this section are ``high-level'' in -the sense that they are not implemented in driver files, but rather -directly by the \pgfname-system layer. For this reason, the commands for -creating soft paths do not start with |\pgfsys@|, but rather with -|\pgfsyssoftpath@|. On the other hand, as a user you will never use -these commands directly, they are described as part of the -low-level interface. - +Note that the commands described in this section are ``high-level'' in the +sense that they are not implemented in driver files, but rather directly by the +\pgfname-system layer. For this reason, the commands for creating soft paths do +not start with |\pgfsys@|, but rather with |\pgfsyssoftpath@|. On the other +hand, as a user you will never use these commands directly, they are described +as part of the low-level interface. \subsection{Path Creation Process} -When the user writes a command like |\draw (0bp,0bp) -- (10bp,0bp);| -quite a lot happens behind the scenes: +When the user writes a command like |\draw (0bp,0bp) -- (10bp,0bp);| quite a +lot happens behind the scenes: +% \begin{enumerate} -\item - The frontend command is translated by \tikzname\ into commands - of the basic layer. In essence, the command is translated to - something like + \item The frontend command is translated by \tikzname\ into commands of the + basic layer. In essence, the command is translated to something like + % \begin{codeexample}[code only] \pgfpathmoveto{\pgfpoint{0bp}{0bp}} \pgfpathlineto{\pgfpoint{10bp}{0bp}} \pgfusepath{stroke} \end{codeexample} -\item - The |\pgfpathxxxx| commands do \emph{not} directly call ``hard'' - commands like |\pgfsys@xxxx|. Instead, the command |\pgfpathmoveto| - invokes a special command called |\pgfsyssoftpath@moveto| and - |\pgfpathlineto| invokes |\pgfsyssoftpath@lineto|. - - The |\pgfsyssoftpath@xxxx| commands, which are described below, - construct a soft path. Each time such a command is used, special - tokens are added to the end of an internal macro that stores the - soft path currently being constructed. -\item - When the |\pgfusepath| is encountered, the soft path stored in - the internal macro is ``invoked.'' Only now does a special macro - iterate over the soft path. For each line-to or move-to - operation on this path it calls an appropriate |\pgfsys@moveto| or - |\pgfsys@lineto| in order to, finally, create the desired hard path, - namely, the string of literals in the |.pdf| or |.ps| file. -\item - After the path has been invoked, |\pgfsys@stroke| is called to - insert the literal for stroking the path. + % + \item The |\pgfpathxxxx| commands do \emph{not} directly call ``hard'' + commands like |\pgfsys@xxxx|. Instead, the command |\pgfpathmoveto| + invokes a special command called |\pgfsyssoftpath@moveto| and + |\pgfpathlineto| invokes |\pgfsyssoftpath@lineto|. + + The |\pgfsyssoftpath@xxxx| commands, which are described below, + construct a soft path. Each time such a command is used, special tokens + are added to the end of an internal macro that stores the soft path + currently being constructed. + \item When the |\pgfusepath| is encountered, the soft path stored in the + internal macro is ``invoked''. Only now does a special macro iterate + over the soft path. For each line-to or move-to operation on this path + it calls an appropriate |\pgfsys@moveto| or |\pgfsys@lineto| in order + to, finally, create the desired hard path, namely, the string of + literals in the |.pdf| or |.ps| file. + \item After the path has been invoked, |\pgfsys@stroke| is called to insert + the literal for stroking the path. \end{enumerate} -Why such a complicated process? Why not have |\pgfpathlineto| directly -call |\pgfsys@lineto| and be done with it? There are two reasons: +Why such a complicated process? Why not have |\pgfpathlineto| directly call +|\pgfsys@lineto| and be done with it? There are two reasons: +% \begin{enumerate} -\item - The \pdf\ specification requires that a path is not interrupted by - any non-path-construction commands. Thus, the following code will - result in a corrupted |.pdf|: + \item The \pdf\ specification requires that a path is not interrupted by + any non-path-construction commands. Thus, the following code will + result in a corrupted |.pdf|: + % \begin{codeexample}[code only] \pgfsys@moveto{0}{0} \pgfsys@setlinewidth{1} \pgfsys@lineto{10}{0} \pgfsys@stroke \end{codeexample} - Such corrupt code is \emph{tolerated} by most viewers, but not - always. It is much better to create only (reasonably) legal code. -\item - A soft path can still be changed, while a hard path is fixed. For - example, one can still change the starting and end points of a soft - path or do optimizations on it. Such transformations are not possible - on hard paths. + % + Such corrupt code is \emph{tolerated} by most viewers, but not always. + It is much better to create only (reasonably) legal code. + \item A soft path can still be changed, while a hard path is fixed. For + example, one can still change the starting and end points of a soft + path or do optimizations on it. Such transformations are not possible + on hard paths. \end{enumerate} \subsection{Starting and Ending a Soft Path} -No special action must be taken in order to start the creation of a -soft path. Rather, each time a command like |\pgfsyssoftpath@lineto| -is called, a special token is added to the (global) current soft path -being constructed. +No special action must be taken in order to start the creation of a soft path. +Rather, each time a command like |\pgfsyssoftpath@lineto| is called, a special +token is added to the (global) current soft path being constructed. -However, you can access and change the current soft path. In this way, -it is possible to store a soft path, to manipulate it, or to invoke -it. +However, you can access and change the current soft path. In this way, it is +possible to store a soft path, to manipulate it, or to invoke it. \begin{command}{\pgfsyssoftpath@getcurrentpath\marg{macro name}} - This command will store the current soft path in \meta{macro name}. + This command will store the current soft path in \meta{macro name}. \end{command} \begin{command}{\pgfsyssoftpath@setcurrentpath\marg{macro name}} - This command will set the current soft path to be the path stored in - \meta{macro name}. This macro should store a path that has - previously been extracted using the |\pgfsyssoftpath@getcurrentpath| - command and has possibly been modified subsequently. + This command will set the current soft path to be the path stored in + \meta{macro name}. This macro should store a path that has previously been + extracted using the |\pgfsyssoftpath@getcurrentpath| command and has + possibly been modified subsequently. \end{command} \begin{command}{\pgfsyssoftpath@invokecurrentpath} - This command will turn the current soft path in a ``hard'' path. To - do so, it iterates over the soft path and calls an appropriate - |\pgfsys@xxxx| command for each element of the path. Note that the - current soft path is \emph{not changed} by this command. Thus, in - order to start a new soft path after the old one has been invoked - and is no longer needed, you need to set the current soft path to be - empty. This may seem strange, but it is often useful to immediately - use the last soft path again. + This command will turn the current soft path in a ``hard'' path. To do so, + it iterates over the soft path and calls an appropriate |\pgfsys@xxxx| + command for each element of the path. Note that the current soft path is + \emph{not changed} by this command. Thus, in order to start a new soft path + after the old one has been invoked and is no longer needed, you need to set + the current soft path to be empty. This may seem strange, but it is often + useful to immediately use the last soft path again. \end{command} \begin{command}{\pgfsyssoftpath@flushcurrentpath} - This command will invoke the current soft path and then set it to be - empty. + This command will invoke the current soft path and then set it to be empty. \end{command} - \subsection{Soft Path Creation Commands} \begin{command}{\pgfsyssoftpath@moveto\marg{x}\marg{y}} - This command appends a ``move-to'' segment to the current soft - path. The coordinates \meta{x} and \meta{y} are given as normal - \TeX\ dimensions. + This command appends a ``move-to'' segment to the current soft path. The + coordinates \meta{x} and \meta{y} are given as normal \TeX\ dimensions. - \example One way to draw a line: + \example One way to draw a line: + % \begin{codeexample}[code only] \pgfsyssoftpath@moveto{0pt}{0pt} \pgfsyssoftpath@lineto{10pt}{10pt} \pgfsyssoftpath@flushcurrentpath \pgfsys@stroke \end{codeexample} + % \end{command} \begin{command}{\pgfsyssoftpath@lineto\marg{x}\marg{y}} - Appends a ``line-to'' segment to the current soft path. + Appends a ``line-to'' segment to the current soft path. \end{command} \begin{command}{\pgfsyssoftpath@curveto\marg{a}\marg{b}\marg{c}\marg{d}\marg{x}\marg{y}} - Appends a ``curve-to'' segment to the current soft path with controls - $(a,b)$ and $(c,d)$. + Appends a ``curve-to'' segment to the current soft path with controls + $(a,b)$ and $(c,d)$. \end{command} \begin{command}{\pgfsyssoftpath@rect\marg{lower left x}\marg{lower left y}\marg{width}\marg{height}} - Appends a rectangle segment to the current soft path. + Appends a rectangle segment to the current soft path. \end{command} \begin{command}{\pgfsyssoftpath@closepath} - Appends a ``close-path'' segment to the current soft path. + Appends a ``close-path'' segment to the current soft path. \end{command} - - \subsection{The Soft Path Data Structure} -A soft path is stored in a standardized way, which makes it possible to -modify it before it becomes ``hard.'' Basically, a soft path is a long -sequence of triples. Each triple starts with a \emph{token} that -identifies what is going on. This token is followed by two dimensions in -braces. For example, the following is a soft path that means ``the -path starts at $(0\mathrm{bp}, 0\mathrm{bp})$ and then -continues in a straight line to $(10\mathrm{bp}, -0\mathrm{bp})$.'' - +A soft path is stored in a standardized way, which makes it possible to modify +it before it becomes ``hard''. Basically, a soft path is a long sequence of +triples. Each triple starts with a \emph{token} that identifies what is going +on. This token is followed by two dimensions in braces. For example, the +following is a soft path that means ``the path starts at $(0\mathrm{bp}, +0\mathrm{bp})$ and then continues in a straight line to $(10\mathrm{bp}, +0\mathrm{bp})$''. +% \begin{codeexample}[code only] \pgfsyssoftpath@movetotoken{0bp}{0bp}\pgfsyssoftpath@linetotoken{10bp}{0bp} \end{codeexample} -A curve-to is hard to express in this way since we need six numbers to -express it, not two. For this reasons, a curve-to is expressed using -three triples as follows: The command +A curve-to is hard to express in this way since we need six numbers to express +it, not two. For this reasons, a curve-to is expressed using three triples as +follows: The command +% \begin{codeexample}[code only] \pgfsyssoftpath@curveto{1bp}{2bp}{3bp}{4bp}{5bp}{6bp} \end{codeexample} -\noindent -results in the following three triples: +% +\noindent results in the following three triples: +% \begin{codeexample}[code only] \pgfsyssoftpath@curvetosupportatoken{1bp}{2bp} \pgfsyssoftpath@curvetosupportbtoken{3bp}{4bp} \pgfsyssoftpath@curvetotoken{5bp}{6bp} \end{codeexample} -These three triples must always ``remain together.'' Thus, a lonely +These three triples must always ``remain together''. Thus, a lonely |supportbtoken| is forbidden. In details, the following tokens exist: +% \begin{itemize} -\item - \declare{|\pgfsyssoftpath@movetotoken|} indicates a move-to - operation. The two following numbers indicate the position to which - the current point should be moved. -\item - \declare{|\pgfsyssoftpath@linetotoken|} indicates a line-to - operation. -\item - \declare{|\pgfsyssoftpath@curvetosupportatoken|} indicates the first - control point of a curve-to operation. The triple must be followed - by a |\pgfsyssoftpath@curvetosupportbtoken|. -\item - \declare{|\pgfsyssoftpath@curvetosupportbtoken|} indicates the second - control point of a curve-to operation. The triple must be followed - by a |\pgfsyssoftpath@curvetotoken|. -\item - \declare{|\pgfsyssoftpath@curvetotoken|} indicates the target - of a curve-to operation. -\item - \declare{|\pgfsyssoftpath@rectcornertoken|} indicates the corner of - a rectangle on the soft path. The triple must be followed - by a |\pgfsyssoftpath@rectsizetoken|. -\item - \declare{|\pgfsyssoftpath@rectsizetoken|} indicates the size of - a rectangle on the soft path. -\item - \declare{|\pgfsyssoftpath@closepath|} indicates that the subpath - begun with the last move-to operation should be closed. The parameter - numbers are currently not important, but if set to anything - different from |{0pt}{0pt}|, they should be set to the coordinate of - the original move-to operation to which the path ``returns'' now. + \item \declare{|\pgfsyssoftpath@movetotoken|} indicates a move-to + operation. The two following numbers indicate the position to which the + current point should be moved. + \item \declare{|\pgfsyssoftpath@linetotoken|} indicates a line-to + operation. + \item \declare{|\pgfsyssoftpath@curvetosupportatoken|} indicates the first + control point of a curve-to operation. The triple must be followed by a + |\pgfsyssoftpath@curvetosupportbtoken|. + \item \declare{|\pgfsyssoftpath@curvetosupportbtoken|} indicates the second + control point of a curve-to operation. The triple must be followed by a + |\pgfsyssoftpath@curvetotoken|. + \item \declare{|\pgfsyssoftpath@curvetotoken|} indicates the target of a + curve-to operation. + \item \declare{|\pgfsyssoftpath@rectcornertoken|} indicates the corner of a + rectangle on the soft path. The triple must be followed by a + |\pgfsyssoftpath@rectsizetoken|. + \item \declare{|\pgfsyssoftpath@rectsizetoken|} indicates the size of a + rectangle on the soft path. + \item \declare{|\pgfsyssoftpath@closepath|} indicates that the subpath + begun with the last move-to operation should be closed. The parameter + numbers are currently not important, but if set to anything different + from |{0pt}{0pt}|, they should be set to the coordinate of the original + move-to operation to which the path ``returns'' now. \end{itemize} - - - - |