diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-commands.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-commands.tex | 1390 |
1 files changed, 1390 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-commands.tex b/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-commands.tex new file mode 100644 index 00000000000..03d697b981c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-commands.tex @@ -0,0 +1,1390 @@ +% Copyright 2019 by Till Tantau +% +% 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{Commands of the System Layer} + +\makeatletter + +\subsection{Beginning and Ending a Stream of System Commands} + +A ``user'' of the \pgfname\ system layer (like the basic layer or a frontend) +will interface with the system layer by calling a stream of commands starting +with |\pgfsys@|. From the system layer's point of view, these commands form a +long stream. Between calls to the system layer, control goes back to the user. + +The driver files implement system layer commands by inserting |\special| +commands that implement the desired operation. For example, |\pgfsys@stroke| +will be mapped to |\special{pdf: S}| by the driver file for |pdftex|. + +For many drivers, when such a stream of specials starts, it is necessary to +install an appropriate transformation and perhaps perform some more +bureaucratic tasks. For this reason, every stream will start with a +|\pgfsys@beginpicture| and will end with a corresponding ending command. + +\begin{command}{\pgfsys@beginpicture} + Called at the beginning of a |{pgfpicture}|. This command should ``set up + things''. + + Most drivers will need to implement this command. +\end{command} + +\begin{command}{\pgfsys@endpicture} + Called at the end of a |{pgfpicture}|. + + Most drivers will need to implement this command. +\end{command} + +\begin{command}{\pgfsys@typesetpicturebox\marg{box}} + Called \emph{after} a |{pgfpicture}| has been typeset. The picture will + have been put in box \meta{box}. This command should insert the box into + the normal text. The box \meta{box} will still be a ``raw'' box that + contains only the |\special|'s that make up the description of the picture. + The job of this command is to resize and shift \meta{box} according to the + baseline shift and the size of the box. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + +\begin{command}{\pgfsys@beginpurepicture} + This version of the |\pgfsys@beginpicture| picture command can be used for + pictures that are guaranteed not to contain any escaped boxes (see below). + In this case, a driver might provide a more compact version of the command. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + +\begin{command}{\pgfsys@endpurepicture} + Called at the end of a ``pure'' |{pgfpicture}|. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + +Inside a stream it is sometimes necessary to ``escape'' back into normal +typesetting mode; for example to insert some normal text, but with all of the +current transformations and clippings being in force. For this escaping, the +following command is used: + +\begin{command}{\pgfsys@hbox\marg{box number}} + Called to insert a (horizontal) TeX box inside a |{pgfpicture}|. + + Most drivers will need to (re-)implement this command. +\end{command} + +\begin{command}{\pgfsys@hboxsynced\marg{box number}} + Called to insert a (horizontal) TeX box inside a |{pgfpicture}|, but with + the current coordinate transformation matrix synced with the canvas + transformation matrix. + + This command should do the same as if you used |\pgflowlevelsynccm| + followed by |\pgfsys@hbox|. However, the default implementation of this + command will use a ``TeX-translation'' for the translation part of the + transformation matrix. This will ensure that hyperlinks ``survive'' at + least translations. On the other hand, a driver may choose to revert to a + simpler implementation. This is done, for example, for the \textsc{svg} + implementation, where a \TeX-translation makes no sense. +\end{command} + +\begin{command}{\pgfsys@pictureboxsynced\marg{box number}} + Basically, this should do the same as doing a (scoped) low level sync + followed by inserting the box \meta{box number} directly into the output + stream. However, the default implementation uses |\pgfsys@hboxsynced| in + conjunction with |\pgfsys@beginpicture| to ensure that, if possible, + hyperlinks survive in \textsc{pdf}s. Drivers that are sensitive to + picture-in-picture scopes should replace this implementation by + % +\begin{codeexample}[code only] +\pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope +\end{codeexample} + % +\end{command} + + +\subsection{Scoping System Commands} + +The scoping commands are used to keep changes of the graphics state local. + +\begin{command}{\pgfsys@beginscope} + Saves the current graphic state on a graphic state stack. All changes to + the graphic state parameters mentioned for |\pgfsys@stroke| and + |\pgfsys@fill| will be local to the current graphic state and the old + values will be restored after |\pgfsys@endscope| is used. + + \emph{Warning:} \pdf\ and PostScript differ with respect to the question of + whether the current path is part of the graphic state or not. For this + reason, you should never use this command unless the path is currently + empty. For example, it might be a good idea to use |\pgfsys@discardpath| + prior to calling this command. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@endscope} + Restores the last saved graphic state. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + + +\subsection{Path Construction System Commands} + +\begin{command}{\pgfsys@moveto\marg{x}\marg{y}} + This command is used to start a path at a specific point $(x,y)$ or to move + the current point of the current path to $(x,y)$ without drawing anything + upon stroking (the current path is ``interrupted''). + + Both \meta{x} and \meta{y} are given as \TeX\ dimensions. It is the + driver's job to transform these to the coordinate system of the backend. + Typically, this means converting the \TeX\ dimension into a dimensionless + multiple of $\frac{1}{72}\mathrm{in}$. The function |\pgf@sys@bp| helps + with this conversion. + + \example Draw a line from $(10\mathrm{pt},10\mathrm{pt})$ to the origin of + the picture. + % +\begin{codeexample}[code only] +\pgfsys@moveto{10pt}{10pt} +\pgfsys@lineto{0pt}{0pt} +\pgfsys@stroke +\end{codeexample} + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@lineto\marg{x}\marg{y}} + Continue the current path to $(x,y)$ with a straight line. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@curveto\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}\marg{$x_3$}\marg{$y_3$}} + Continue the current path to $(x_3,y_3)$ with a Bézier curve that has the + two control points $(x_1,y_1)$ and $(x_2,y_2)$. + + \example Draw a good approximation of a quarter circle: + % +\begin{codeexample}[code only] +\pgfsys@moveto{10pt}{0pt} +\pgfsys@curveto{10pt}{5.55pt}{5.55pt}{10pt}{0pt}{10pt} +\pgfsys@stroke +\end{codeexample} + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@rect\marg{x}\marg{y}\marg{width}\marg{height}} + Append a rectangle to the current path whose lower left corner is at + $(x,y)$ and whose width and height in big points are given by \meta{width} + and \meta{height}. + + This command can be ``mapped back'' to |\pgfsys@moveto| and + |\pgfsys@lineto| commands, but it is included since \pdf\ has a special, + quick version of this command. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@closepath} + Close the current path. This results in joining the current point of the + path with the point specified by the last |\pgfsys@moveto| operation. + Typically, this is preferable over using |\pgfsys@lineto| to the last point + specified by a |\pgfsys@moveto|, since the line starting at this point and + the line ending at this point will be smoothly joined by + |\pgfsys@closepath|. + + \example Consider + % +\begin{codeexample}[code only] +\pgfsys@moveto{0pt}{0pt} +\pgfsys@lineto{10bp}{10bp} +\pgfsys@lineto{0bp}{10bp} +\pgfsys@closepath +\pgfsys@stroke +\end{codeexample} + % + and + % +\begin{codeexample}[code only] +\pgfsys@moveto{0bp}{0bp} +\pgfsys@lineto{10bp}{10bp} +\pgfsys@lineto{0bp}{10bp} +\pgfsys@lineto{0bp}{0bp} +\pgfsys@stroke +\end{codeexample} + + The difference between the above will be that in the second triangle the + corner at the origin will be wrong; it will just be the overlay of two + lines going in different directions, not a sharp pointed corner. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + + +\subsection{Canvas Transformation System Commands} + +\begin{command}{\pgfsys@transformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}} + Perform a concatenation of the canvas transformation matrix with the matrix + given by the values \meta{a} to \meta{f}, see the \pdf\ or PostScript + manual for details. The values \meta{a} to \meta{d} are dimensionless + factors, \meta{e} and \meta{f} are \TeX\ dimensions + + \example |\pgfsys@transformcm{1}{0}{0}{1}{1cm}{1cm}|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@transformshift\marg{x displacement}\marg{y displacement}} + This command will change the origin of the canvas to $(x,y)$. + + This command has a default implementation and need not be implemented by a + driver file. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@transformxyscale\marg{x scale}\marg{y scale}} + This command will scale the canvas (and everything that is drawn) by a + factor of \meta{x scale} in the $x$-direction and \meta{y scale} in the + $y$-direction. Note that this applies to everything, including lines. So a + scaled line will have a different width and may even have a different width + when going along the $x$-axis and when going along the $y$-axis, if the + scaling is different in these directions. Usually, you do not want this. + + This command has a default implementation and need not be implemented by a + driver file. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@viewboxmeet\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}% + \marg{$x'_1$}\marg{$y'_1$}\marg{$x'_2$}\marg{$y'_2$}% +} + Starts a ``view box'' scope, which must be ended using |\pgfsys@endviewbox| + later on (with matching scopes). + + The effect of this command is as follows: Consider the rectangles $R$ with + lower left corner $(x_1,y_1)$ and upper right corner $(x_2,y_2)$ and $R'$ + with corners $(x'_1,y'_1)$ and $(x'_2,y'_2)$. The command will install a + canvas translation and uniform scaling such that $R'$ then has the same + center as~$R$ and additionally, has maximum size such that it still fits + inside~$R$. (Think of this as ``viewing'' $R'$ through $R$ such that the + aspect ratio is kept.) + + This command has a default implementation. Its main purpose is to allow + animations of the view box; for static drawings it is better to compute the + necessary transformations directly. +\end{command} + +\begin{command}{\pgfsys@viewboxslice\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}% + \marg{$x'_1$}\marg{$y'_1$}\marg{$x'_2$}\marg{$y'_2$}% +} + Works like the previous command, but now $R'$ has minimal size such that it + encompasses all of $R$. +\end{command} + +\begin{command}{\pgfsys@endviewbox} + Ends a viewbox previously started using |\pgfsys@viewboxmeet| or the + |...slice| variant. +\end{command} + + +\subsection{Stroking, Filling, and Clipping System Commands} + +\begin{command}{\pgfsys@stroke} + Stroke the current path (as if it were drawn with a pen). A number of + graphic state parameters influence this, which can be set using appropriate + system commands described later. + % + \begin{description} + \item[Line width] The ``thickness'' of the line. A width of 0 is the + thinnest width renderable on the device. On a high-resolution + printer this may become invisible and should be avoided. A good + choice is 0.4pt, which is the default. + \item[Stroke color] This special color is used for stroking. If it is + not set, the current color is used. + \item[Cap] The cap describes how the endings of lines are drawn. A + round cap adds a little half circle to these endings. A butt cap + ends the lines exactly at the end (or start) point without anything + added. A rectangular cap ends the lines like the butt cap, but the + lines protrude over the endpoint by the line thickness. (See also + the \pdf\ manual.) If the path has been closed, no cap is drawn. + \item[Join] This describes how a bend (a join) in a path is rendered. A + round join draws bends using small arcs. A bevel join just draws + the two lines and then fills the join minimally so that it becomes + convex. A miter join extends the lines so that they form a single + sharp corner, but only up to a certain miter limit. (See the \pdf\ + manual once more.) + \item[Dash] The line may be dashed according to a dashing pattern. + \item[Clipping area] If a clipping area is established, only those + parts of the path that are inside the clipping area will be drawn. + \end{description} + + In addition to stroking a path, the path may also be used for clipping + after it has been stroked. This will happen if the |\pgfsys@clipnext| is + used prior to this command, see there for details. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@closestroke} + This command should have the same effect as first closing the path and then + stroking it. + + This command has a default implementation and need not be implemented by a + driver file. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + + +\begin{command}{\pgfsys@fill} + This command fills the area surrounded by the current path. If the path has + not yet been closed, it is closed prior to filling. The path itself is not + stroked. For self-intersecting paths or paths consisting of multiple parts, + the nonzero winding number rule is used to determine whether a point is + inside or outside the path, except if |\ifpgfsys@eorule| holds -- in which + case the even-odd rule should be used. (See the \pdf\ or PostScript manual + for details.) + + The following graphic state parameters influence the filling: + % + \begin{description} + \item[Interior rule] If |\ifpgfsys@eorule| is set, the even-odd rule is + used, otherwise the non-zero winding number rule. + \item[Fill color] If the fill color is not especially set, the current + color is used. + \item[Clipping area] If a clipping area is established, only those + parts of the filling area that are inside the clipping area will be + drawn. + \end{description} + + In addition to filling the path, the path will also be used for clipping if + |\pgfsys@clipnext| is used prior to this command. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@fillstroke} + First, the path is filled, then the path is stroked. If the fill and stroke + colors are the same (or if they are not specified and the current color is + used), this yields almost the same as a |\pgfsys@fill|. However, due to the + line thickness of the stroked path, the fill-stroked area will be slightly + larger. + + In addition to stroking and filling the path, the path will also be used + for clipping if |\pgfsys@clipnext| is used prior to this command. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@discardpath} + Normally, this command should ``throw away'' the current path. However, + after |\pgfsys@clipnext| has been called, the current path should + subsequently be used for clipping. See |\pgfsys@clipnext| for details. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@clipnext} + This command should be issued after a path has been constructed, but before + it has been stroked and/or filled or discarded. When the command is used, + the next stroking/filling/discarding command will first be executed + normally. Then, afterwards, the just-used path will be used for subsequent + clipping. If there has already been a clipping region, this region is + intersected with the new clipping path (the clipping cannot get bigger). + The nonzero winding number rule is used to determine whether a point is + inside or outside the clipping area or the even-odd rule, depending on + whether |\ifpgfsys@eorule| holds. +\end{command} + + +\subsection{Graphic State Option System Commands} + +\begin{command}{\pgfsys@setlinewidth\marg{width}} + Sets the width of lines, when stroked, to \meta{width}, which must be a + \TeX\ dimension. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@buttcap} + Sets the cap to a butt cap. See |\pgfsys@stroke|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@roundcap} + Sets the cap to a round cap. See |\pgfsys@stroke|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@rectcap} + Sets the cap to a rectangular cap. See |\pgfsys@stroke|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@miterjoin} + Sets the join to a miter join. See |\pgfsys@stroke|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@setmiterlimit\marg{factor}} + Sets the miter limit of lines to \meta{factor}. See the \pdf\ or PostScript + for details on what the miter limit is. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@roundjoin} + Sets the join to a round join. See |\pgfsys@stroke|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@beveljoin} + Sets the join to a bevel join. See |\pgfsys@stroke|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@setdash\marg{pattern}\marg{phase}} + Sets the dashing patter. \meta{pattern} should be a list of \TeX\ + dimensions separated by commas. \meta{phase} should be a single dimension. + + \example |\pgfsys@setdash{3pt,3pt}{0pt}| + + The list of values in \meta{pattern} is used to determine the lengths of + the ``on'' and ``off'' phases of the dashing. For example, if + \meta{pattern} is |3bp,4bp|, then the dashing pattern is ``3bp on followed + by 4bp off, followed by 3bp on, followed by 4bp off, and so on''. A pattern + of |.5pt,4pt,3pt,1.5pt| means ``.5pt on, 4pt off, 3pt on, 1.5pt off, .5pt + on, \dots'' If the number of entries is odd, the last one is used twice, so + |3pt| means ``3pt on, 3pt off, 3pt on, 3pt off, \dots'' An empty list means + ``always on''. + + The second argument determines the ``phase'' of the pattern. For example, + for a pattern of |3bp,4bp| and a phase of |1bp|, the pattern would start: + ``2bp on, 4bp off, 3bp on, 4bp off, 3bp on, 4bp off, \dots'' + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +{\let\ifpgfsys@eorule=\relax +\begin{command}{\ifpgfsys@eorule} + Determines whether the even odd rule is used for filling and clipping or + not. +\end{command} +} + + +\subsection{Color System Commands} + +The \pgfname\ system layer provides a number of system commands for setting +colors. These command coexist with commands from the |color| and |xcolor| +package, which perform similar functions. However, the |color| package does not +support having two different colors for stroking and filling, which is a useful +feature that is supported by \pgfname. For this reason, the \pgfname\ system +layer offers commands for setting these colors separately. Also, plain \TeX\ +profits from the fact that \pgfname\ can set colors. + +For \pdf, implementing these color commands is easy since \pdf\ supports +different stroking and filling colors directly. For PostScript, a more +complicated approach is needed in which the colors need to be stored in special +PostScript variables that are set whenever a stroking or a filling operation is +done. + +\begin{command}{\pgfsys@color@rgb\marg{red}\marg{green}\marg{blue}} + Sets the color used for stroking and filling operations to the given + red/green/blue tuple (numbers between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@rgb@stroke\marg{red}\marg{green}\marg{blue}} + Sets the color used for stroking operations to the given red/green/blue + tuple (numbers between 0 and 1). + + \example Make stroked text dark red: |\pgfsys@color@rgb@stroke{0.5}{0}{0}| + + The special stroking color is only used if the stroking color has been set + since the last |\color| or |\pgfsys@color@...| command. Thus, each |\color| + command will reset both the stroking and filling colors by calling + |\pgfsys@color@reset|. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@rgb@fill\marg{red}\marg{green}\marg{blue}} + Sets the color used for filling operations to the given red/green/blue + tuple (numbers between 0 and 1). This color may be different from the + stroking color. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} + Sets the color used for stroking and filling operations to the given cmyk + tuple (numbers between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmyk@stroke\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} + Sets the color used for stroking operations to the given cmyk tuple + (numbers between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmyk@fill\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} + Sets the color used for filling operations to the given cmyk tuple (numbers + between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}} + Sets the color used for stroking and filling operations to the given cmy + tuple (numbers between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmy@stroke\marg{cyan}\marg{magenta}\marg{yellow}} + Sets the color used for stroking operations to the given cmy tuple (numbers + between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@cmy@fill\marg{cyan}\marg{magenta}\marg{yellow}} + Sets the color used for filling operations to the given cmy tuple (numbers + between 0 and 1). + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@gray\marg{black}} + Sets the color used for stroking and filling operations to the given black + value, where 0 means black and 1 means white. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@gray@stroke\marg{black}} + Sets the color used for stroking operations to the given black value, where + 0 means black and 1 means white. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@gray@fill\marg{black}} + Sets the color used for filling operations to the given black value, where + 0 means black and 1 means white. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@color@reset} + This command will be called when the |\color| command is used. It should + purge any internal settings of stroking and filling color. After this call, + till the next use of a command like |\pgfsys@color@rgb@fill|, the current + color installed by the |\color| command should be used. + + If the \TeX-if |\pgfsys@color@reset@inorder| is set to true, this command + may ``assume'' that any call to a color command that sets the fill or + stroke color came ``before'' the call to this command and may try to + optimize the output accordingly. + + An example of an incorrect ``out of order'' call would be using + |\pgfsys@color@reset| at the beginning of a box that is constructed using + |\setbox|. Then, when the box is constructed, no special fill or stroke + color might be in force. However, when the box is later on inserted at some + point, a special fill color might already have been set. In this case, this + command is not guaranteed to reset the color correctly. +\end{command} + +\begin{command}{\pgfsys@color@reset@inordertrue} + Sets the optimized ``in order'' version of the color resetting. This is the + default. +\end{command} + +\begin{command}{\pgfsys@color@reset@inorderfalse} + Switches off the optimized color resetting. +\end{command} + +\begin{command}{\pgfsys@color@unstacked\marg{\LaTeX\ color}} + This slightly obscure command causes the color stack to be tricked. When + called, this command should set the current color to \meta{\LaTeX\ color} + without causing any change in the color stack. + + \example |\pgfsys@color@unstacked{red}| +\end{command} + + +\subsection{Pattern System Commands} + +\begin{command}{\pgfsys@declarepattern + \marg{name}\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}% + \marg{$x$ step}\marg{$y$ step}% + \marg{$a$}\marg{$b$}\marg{$c$}\marg{$d$}\allowbreak\marg{$e$}\marg{$f$}% + \marg{code}\marg{flag}% +} + This command declares a new colored or uncolored pattern, depending on + whether \meta{flag} is |0|, which means uncolored, or |1|, which means + colored. Uncolored patterns have no inherent color, the color is provided + when they are set. Colored patters have an inherent color. + + The \meta{name} is a name for later use when the pattern is to be shown. + The pairs $(x_1,y_1)$ and $(x_2,y_2)$ must describe a bounding box of the + pattern \meta{code}. + + The tiling step of the pattern is given by \meta{$x$ step} and \meta{$y$ + step}. + + The parameters \meta{$a$} to \meta{$f$} are entries of the transformation + matrix that is applied to the pattern, see |\pgfsys@patternmatrix| for more + information. + + \example + % +\begin{codeexample}[code only] +\pgfsys@declarepattern + {hori}{-.5pt}{0pt}{.5pt}{3pt}{3pt}{3pt}% + {1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}% + {\pgfsys@moveto{0pt}{0pt}\pgfsys@lineto{0pt}{3pt}\pgfsys@stroke} + {0} +\end{codeexample} + % +\end{command} + + +\begin{command}{\pgfsys@patternmatrix} + For convenience \pgfname\ defines the transformation matrix that is applied + to all patterns defined with |\pgfdeclarepatternformonly| and + |\pgfdeclarepatterninherentlycolored| in a macro. This can be used as an + extension point for ad-hoc transformation of existing patterns. The + default definition is the + identity matrix: + % +\begin{codeexample}[code only] +\def\pgfsys@patternmatrix{{1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}} +\end{codeexample} + % + The entries of the enclosed array + |{|\meta{$a$}|}{|\meta{$b$}|}{|\meta{$c$}|}{|\meta{$d$}|}{|\meta{$e$}|}{|\meta{$f$}|}| + are entries in the transformation matrix, identified as in the following + transformation prescription: + \begin{equation*} + \begin{pmatrix} + x' \\ + y' \\ + 1 \\ + \end{pmatrix} + = + \begin{pmatrix} + a & c & e \\ + b & d & f \\ + 0 & 0 & 1 \\ + \end{pmatrix} + \begin{pmatrix} + x \\ + y \\ + 1 \\ + \end{pmatrix} . + \end{equation*} + Carrying out the matrix multiplication results in the following system of + equations + \begin{align*} + x' &= a x + c y + e , \\ + y' &= b x + d y + f . + \end{align*} + Evidently, the parameters \marg{$a$} to \marg{$d$} have to be dimensionless + because they are scaling factors, but the parameters \marg{$e$} and + \marg{$f$} are offsets, therefore they have to carry a unit. +\end{command} + +\begin{command}{\pgfsys@setpatternuncolored\marg{name}\marg{red}\marg{green}\marg{blue}} + Sets the fill color to the pattern named \meta{name}. This pattern must + previously have been declared with \meta{flag} set to |0|. The color of the + pattern is given in the parameters \meta{red}, \meta{green}, and + \meta{blue} in the usual way. + + The fill color ``pattern'' will persist till the next color command that + modifies the fill color. +\end{command} + +\begin{command}{\pgfsys@setpatterncolored\marg{name}} + Sets the fill color to the pattern named \meta{name}. This pattern must + have been declared with the |1| flag. +\end{command} + + +\subsection{Image System Commands} + +The system layer provides some commands for image inclusion. + +\begin{command}{\pgfsys@imagesuffixlist} + This macro should expand to a list of suffixes, separated by `:', that will + be tried when searching for an image. + + \example |\def\pgfsys@imagesuffixlist{eps:epsi:ps}| +\end{command} + +\begin{command}{\pgfsys@defineimage} + Called, when an image should be defined. + + This command does not take any parameters. Instead, certain macros will be + preinstalled with appropriate values when this command is invoked. These + are: + % + \begin{itemize} + \item\declare{|\pgf@filename|} File name of the image to be defined. + \item\declare{|\pgf@imagewidth|} Will be set to the desired (scaled) + width of the image. + \item\declare{|\pgf@imageheight|} Will be set to the desired (scaled) + height of the image. + + If this macro and also the height macro are empty, the image should + have its ``natural'' size. + + If only one of them is specified, the undefined value the image is + scaled so that the aspect ratio is kept. + + If both are set, the image is scaled in both directions + independently, possibly changing the aspect ratio. + \end{itemize} + + The following macros presumable mostly make sense for drivers that + can handle \pdf: + % + \begin{itemize} + \item \declare{|\pgf@imagepage|} The desired page number to be + extracted from a multi-page ``image''. + \item\declare{|\pgf@imagemask|} If set, it will be set to + |/SMask x 0 R| where |x| is the \pdf\ object number of a soft mask + to be applied to the image. + \item\declare{|\pgf@imageinterpolate|} If set, it will be set to + |/Interpolate true| or |/Interpolate false|, indicating whether the + image should be interpolated in \pdf. + \end{itemize} + + The command should now set up the macro |\pgf@image| such that calling this + macro will result in typesetting the image. Thus, |\pgf@image| is the + ``return value'' of the command. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + + +\subsection{Shading System Commands} + +\begin{command}{\pgfsys@horishading\marg{name}\marg{height}\marg{specification}} + Declares a horizontal shading for later use. The effect of this command + should be the definition of a macro called |\@pgfshading|\meta{name}|!| (or + |\csname @pdfshading|\meta{name}|!\endcsname|, to be precise). When + invoked, this new macro should insert a shading at the current position. + + \meta{name} is the name of the shading, which is also used in the output + macro name. \meta{height} is the height of the shading and must be given as + a TeX dimension like |2cm| or |10pt|. \meta{specification} is a shading + color specification as specified in Section~\ref{section-shadings}. The + shading specification implicitly fixes the width of the shading. + + When |\@pgfshading|\meta{name}|!| is invoked, it should insert a box of + height \meta{height} and the width implicit in the shading declaration. +\end{command} + +\begin{command}{\pgfsys@vertshading\marg{name}\marg{width}\marg{specification}} + Like the horizontal version, only for vertical shadings. This time, the + height of the shading is implicit in \meta{specification} and the width is + given as \meta{width}. +\end{command} + +\begin{command}{\pgfsys@radialshading\marg{name}\marg{starting point}\marg{specification}} + Declares a radial shading. Like the previous macros, this command should + set up the macro |\@pgfshading|\meta{name}|!|, which upon invocation should + insert a radial shading whose size is implicit in \meta{specification}. + + The parameter \meta{starting point} is a \pgfname\ point specifying the + inner starting point of the shading. +\end{command} + +\begin{command}{\pgfsys@functionalshading\marg{name}\marg{lower left corner}\meta{upper right corner}\marg{type 4 function}} + Declares a shading using a PostScript-like function that provides a color + for each point. Like the previous macros, this command should set up the + macro |\@pgfshading|\meta{name}|!| so that it will produce a box containing + the desired shading. + + Parameter \meta{name} is the name of the shading. Parameter \meta{type 4 + function} is a Postscript-like function (type 4 function of the PDF + specification) as described in Section~3.9.4 of the PDF specification + version 1.7. Parameters \meta{lower left corner} and \meta{upper right + corner} are \pgfname\ points that specifies the lower left and upper right + corners of the shading, respectively. + + When \meta{type 4 function} is evaluated, the coordinate of the current + point will be on the (virtual) PostScript stack in bp units. After the + function has been evaluated, the stack should consist of three numbers (not + integers! -- the Apple PDF renderer is broken in this regard, so add cvrs + at the end if needed) that represent the red, green, and blue components of + the color. + + A buggy function will result is \emph{totally unpredictable chaos} during + rendering. +\end{command} + + +\subsection{Transparency System Commands} + +\begin{command}{\pgfsys@opacity\marg{value}} + Sets the opacity of all operations, treating stroking and filling as a + transparency group. Some drivers support this operations, others do not and + set the fill and stroke individually. This difference can only be seen when + a path is stroked and filled at the same time: When the drawing and fill + opacities are set individually, the effect of filling and drawing a path at + the same time is the same as first filling the path and then drawing it. On + the other, if the opacity is set using this command, the effect should + rather be that same as first filling and then drawing the path without any + opacity in an off-screen area and then copying the result to the target + area with a homogeneous opacity of \meta{value}. + + Since \textsc{pdf} does not support this form of opacity, this command is + only present on the system layer and not supported in the basic layer. +\end{command} + +\begin{command}{\pgfsys@stroke@opacity\marg{value}} + Sets the opacity of stroking operations. +\end{command} + +\begin{command}{\pgfsys@fill@opacity\marg{value}} + Sets the opacity of filling operations. +\end{command} + +\begin{command}{\pgfsys@blend@mode\marg{value}} + Sets the blend mode, see Section~7.2.4 of the \textsc{pdf} Specification, + Version~1.7. +\end{command} + +\begin{command}{\pgfsys@transparencygroupfrombox\marg{box}} + This takes a \TeX\ box and converts it into a transparency group. This + means that any transparency settings apply to the box as a whole. For + instance, if a box contains two overlapping black circles and you draw the + box and, thus, the two circles normally with 50\% transparency, then the + overlap will be darker than the rest. By comparison, if the circles are + part of a transparency group, the overlap will get the same color as the + rest. +\end{command} + +A transparency group can be \emph{isolated} and/or a \emph{knockout} group (see +Sections~7.3.4 and 7.3.5 of the \textsc{pdf} Specification Version~1.7). Which +of these is the case is dictated by the current settings of the following two +ifs, which must be set before the above command is called: + +{\let\ifpgfsys@transparency@group@isolated=\relax +\begin{command}{\ifpgfsys@transparency@group@isolated} + Determines whether a transparency group should be isolated. +\end{command} +} + +{\let\ifpgfsys@transparency@group@knockout=\relax +\begin{command}{\ifpgfsys@transparency@group@knockout} + Determines whether a transparency group is a knockout group or not. +\end{command} +} + +\begin{command}{\pgfsys@fadingfrombox\marg{name}\marg{box}} + Declares the fading \meta{name}. The \meta{box} is a \TeX-box. Its + content's luminosity determines the opacity of the resulting fading. This + means that the lighter a pixel inside the box, the more opaque the fading + will be at this position. +\end{command} + +\begin{command}{\pgfsys@usefading\meta{name}\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}} + Installs a previously declared fading \meta{name} in the current graphics + state. Afterwards, all drawings will be masked by the fading. The fading + should be centered on the origin and have its original size, except that + the parameters \meta{a} to \meta{f} specify a transformation matrix that + should be applied additionally to the fading before it is installed. The + transformation should not apply to the following graphics, however. +\end{command} + +\begin{command}{\pgfsys@clipfading} + This command has a default implementation and need not be implemented by + driver files other than |pgfsys-dvips.def|. The macro is called + in |\pgfsetfadingforcurrentpath| and |\pgfsetfadingforcurrentpathstroked| + of the basic layer, where it invokes the current path for clipping the + shading just before installing it as an opacity mask for fading. The + default implementation is actually a non-operation, but with |dvips| it + is used to clip the fading as described. +\end{command} + +\begin{command}{\pgfsys@definemask} + This command declares a fading (known as a soft mask in this context) based + on an image and for usage with images. It works similar to + |\pgfsys@defineimage|: Certain macros are set when the command is called. + The result should be to set the macro |\pgf@mask| to a pdf object count + that can subsequently be used as a transparency mask. The following macros + will be set when this command is invoked: + % + \begin{itemize} + \item \declare{|\pgf@filename|} + File name of the mask to be defined. + \item \declare{|\pgf@maskmatte|} + The so-called matte of the mask (see the \pdf\ documentation for + details). The matte is a color specification consisting of 1, 3 or + 4 numbers between 0 and 1. The number of numbers depends on the + number of color channels in the image (not in the mask!). It will + be assumed that the image has been preblended with this color. + \end{itemize} +\end{command} + + +\subsection{Animation Commands} + +The animation system layer command (|\pgfsys@anim...|) are described in a +separate section, Section~\ref{section-pgfsys-anim}. + + +\subsection{Object Identification System Commands} +\label{section-sys-id} + +The system layer provides commands for adding identification labels (ids) to +different objects in a graphic. These can be used for hyperlinking, which is +needed for instance in conjunction with animations. + +The following ``objects'' can get an id assigned to them: +% +\begin{enumerate} + \item Graphic scopes (namely when |\pgfsys@begin@idscope| is called), + \item view boxes (namely when |\pgfsys@viewboxmeet| or + |\pgfsys@viewboxslice| are called), + \item paths (namely when |\pgfsys@fill|, |\pgfsys@stroke|, and so on are + called), + \item text boxes (namely when |\pgfsys@hbox| or |\pgfsys@hboxsynced| is + called), and + \item animations (namely when |\pgfsys@animate| is called). +\end{enumerate} + +Creating and using ids is a two-step process. First, you create the id using +|\pgfsys@new@id|, which stores a fresh id in a macro. You can now pass this id +around and clone it. Then, at some point, you wish one of the above objects to +actually get this id. For this, you use |\pgfsys@use@id| just \emph{before} the +object since this command always influences the \emph{next} object. + +The basic id management gets more powerful when you use \emph{id types}. The +idea is as follows: In reality, the objects from above do not get assigned only +an id, but rather a combination of an id and a type -- and you can set the type +independently of the id. This is used, for instance, to allow easy access to +the different parts of a node in animations: Each node has a single id, but +consists of several graphic objects (normally, at least a background path and a +text). Each of these uses the same underlying id of the node, but the path has +the type |path| (actually |background.path|) while the text has the type +|text|. The advantage is that for each node only one id must be stored instead +of a great number of the many different possible parts of a node. + +\begin{command}{\pgfsys@new@id\marg{macro}} + Creates a new id for later use and stores it in \meta{macro}. It is an + internal text created by the driver and may not be changed or modified. +\end{command} + +\begin{command}{\pgfsys@use@id\marg{id}} + ``Uses'' an id previously created using |\pgfsys@new@id|. This causes the + \emph{next} graphic object to get the \meta{id} (not the current one). Once + used, the id-type-pair becomes \emph{invalid} and will not be attached to + any other graphics objects. It is, however, not an error to try this. If + \meta{id} is empty, no id-type-pair is attached to the next object. +\end{command} + +\begin{command}{\pgfsys@use@type\marg{type}} + Changes the type used with the next graphic object. As mentioned earlier, + the id assigned to the next object is actually a pair consisting of the + currently used id and the currently used type. +\end{command} + +\begin{command}{\pgfsys@append@type\marg{text}} + Appends the \meta{text} to the current type. +\end{command} + +\begin{command}{\pgfsys@push@type} + Pushes the current type on a global ``stack of types'' without opening a + \TeX\ scope. The is useful when you temporarily wish to change the type + (for instance, by appending something to it), but you cannot create a new + scope. +\end{command} + +\begin{command}{\pgfsys@pop@type} + Restores the most recently pushed type. +\end{command} + +\begin{command}{\pgfsys@begin@idscope} + Starts a (graphics) scope whose sole purpose is to assign it an + id-type-pair so that it can be referenced later. Note that this command + does not always produce a graphics scope: If no id is currently in use or + if the id-type-pair has already been used, a graphic scope may or may not + be created as defined by the driver (but always a \TeX\ scope). This allows + drivers to minimize the number of graphic scopes created. + + When an id scope is created, any code that has been ``attached'' to it + using |\pgfsys@attach@to@id| gets executed, see that command. + + Note that |\pgfsys@beginscope| does not use the current id-type-pair. You + need to call this command to attach an id to a group. +\end{command} + +\begin{command}{\pgfsys@end@idscope} + Ends the graphics id scope started by |\pgfsys@end@idscope|. It must nest + correctly with other graphic scopes and \TeX\ scopes. +\end{command} + +\begin{command}{\pgfsys@attach@to@id\marg{id}\marg{type}\marg{begin code}\marg{end code}\marg{setup code}} + Attaches codes to the \meta{id}-\meta{type}-pair, where \meta{id} must have + been created using |\pgfsys@new@id|. The effect is that just before the id + scope for this pair is created, the \meta{setup code} is executed, then the + scope is started, then the \meta{begin code} is executed at the beginning, + and, finally, \meta{end code} gets executed just before the scope ends. + Multiple calls of this macro accumulated. +\end{command} + + +\subsection{Resource Description Framework Annotations (RDFa)} +\label{section-sys-rdf} + +With certain output formats (in particular, with \textsc{svg}) you can insert +annotations into the output file following the standard set by the +\emph{resource description framework} (\textsc{rdf}), please consult the +literature on \textsc{rdf} for an introduction to resource descriptions and +ontologies. + +The support for \textsc{rdf} annotations works as follows in \pgfname: You use +the following commands before you create an id scope (using +|\pgfsys@begin@idscope|). Then the attributes set by the commands will be added +as an annotation to that object. Here is an example: +% +\begin{codeexample}[code only] +\pgfsys@rdf@resource{/fruits/apple} +\pgfsys@begin@idscope + ... +\pgfsys@end@idscope +\end{codeexample} + +If \textsc{svg} output is produced, this results in the following code in the +\textsc{svg} file: +% +\begin{codeexample}[code only] +<g resource="/fruits/apple"> + ... +</g> +\end{codeexample} + +Note that a call to |\pgfsys@begin@idscope| adds all the set attributes, but +then clears the settings (globally). Thus, you should set all attributes more +or less right before the id scope is created. For most of these command, if you +call them multiple times before starting the id scope, the ``last call wins'', +that is, later values overwrite earlier ones. In contrast, for the commands +|\pgfsys@rdf@property|, |\pgfsys@rdf@rel|, |\pgfsys@rdf@rev|, as well as +|\pgfsys@rdf@typeof|, the calls accumulate, that is, the texts passed in each +call will all be added to the output, properly separated to form a list of +values. Consider for instance: +% +\begin{codeexample}[code only] +\pgfsys@rdf@resource{/fruits/apple} +\pgfsys@rdf@resource{/fruits/watermelon} +\pgfsys@rdf@property{http://foo.com/props/juicy} +\pgfsys@rdf@property{http://foo.com/props/green} +\pgfsys@begin@idscope + ... +\pgfsys@end@idscope +\end{codeexample} + +In the resulting id scope, we will have: +% +\begin{codeexample}[code only] +<g resource="/fruits/watermelon" + property="http://foo.com/props/juicy http://foo.com/props/green"> + ... +</g> +\end{codeexample} + +\begin{command}{\pgfsys@rdf@about\marg{text}} + Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id + scope (please see the \textsc{rdf}a specification for details on the + semantics of |about| in the context of the resource description framework). +\end{command} + +The following commands work the same way as the above command, except that the +set attribute is different. Please see the \textsc{rdf}a specification for +details on these attributes. Note that the |\pgfsys@rdf@inlist| command is the +only one that takes no argument. + +\begin{command}{\pgfsys@rdf@content\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@datatype\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@href\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@inlist} +\end{command} + +\begin{command}{\pgfsys@rdf@prefix\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@property\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@rel\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@resource\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@rev\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@src\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@typeof\marg{text}} +\end{command} + +\begin{command}{\pgfsys@rdf@vocab\marg{text}} +\end{command} + + +\subsection{Reusable Objects System Commands} + +\begin{command}{\pgfsys@invoke\marg{literals}} + This command gets protocolled literals and should insert them into the + |.pdf| or |.dvi| file using an appropriate |\special|. +\end{command} + +\begin{command}{\pgfsys@defobject\marg{name}\marg{lower left}\marg{upper right}\marg{code}} + Declares an object for later use. The idea is that the object can be + precached in some way and then be rendered more quickly when used several + times. For example, an arrow head might be defined and prerendered in this + way. + + The parameter \meta{name} is the name for later use. \meta{lower left} and + \meta{upper right} are \pgfname\ points specifying a bounding box for the + object. \meta{code} is the code for the object. The code should not be too + fancy. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + +\begin{command}{\pgfsys@useobject\marg{name}\marg{extra code}} + Renders a previously declared object. The first parameter is the name of + the object. The second parameter is extra code that should be executed + right \emph{before} the object is rendered. Typically, this will be some + transformation code. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + +\begin{command}{\pgfsys@marker@declare\marg{macro}\marg{code}} + Declares a \emph{marker} symbol for later use. The command is very similar + to |\pgfsys@defobject|, but the use case is slightly different: The graphic + object defined using the \meta{code} is stored in such a way that it can be + used as an \emph{arrow tip marker symbol} in animations. The \meta{macro} + is set to an identifier by which the marker can be referenced later on. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + +\begin{command}{\pgfsys@marker@use\marg{macro}} + Adds the marker object referenced by the \meta{macro} to the current + output. + + This command has a default implementation and need not be implemented by a + driver file. +\end{command} + + +\subsection{Invisibility System Commands} + +All drawing or stroking or text rendering between calls of the following +commands should be suppressed. A similar effect can be achieved by clipping +against an empty region, but the following commands do not open a graphics +scope and can be opened and closed ``orthogonally'' to other scopes. + +\begin{command}{\pgfsys@begininvisible} + Between this command and the closing |\pgfsys@endinvisible| all output + should be suppressed. Nothing should be drawn at all, which includes all + paths, images and shadings. However, no groups (neither \TeX\ groups nor + graphic state groups) should be opened by this command. + + This command has a default implementation and need not be implemented by a + driver file. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + +\begin{command}{\pgfsys@endinvisible} + Ends the invisibility section, unless invisibility blocks have been nested. + In this case, only the ``last'' one restores visibility. + + This command has a default implementation and need not be implemented by a + driver file. + + This command is protocolled, see Section~\ref{section-protocols}. +\end{command} + + +\subsection{Page Size Commands} + +The following commands can be used to set the page size of a document in a +``portable'' way. Note, however, that many packages also (try to) set the page +size. + +These commands are typically not given inside a |{pgfpicture}|, but on the +outer level of compilation. + +\begin{command}{\pgfsys@papersize\marg{width}\marg{height}} + Inserts the necessary |\special|s for the current driver into the output + stream to ``locally'' change the page size. Whether such a ``local'' change + is possible depends strongly on the driver. For instance, |dvips| will + honor the first call to this command that is part of the shipped-out + document and will ignore all other uses. In contrast, |pdftex| will use the + current value of the paper size for each page and, additionally, setting + the papersize is local to the current \TeX\ group. +\end{command} + +\begin{command}{\pgfsys@global@papersize\marg{width}\marg{height}} + Like the previous command, only for drivers where setting the paper size + parameters is a \TeX-group-local operation, |\global| is prefixed to the + setting of the page sizes. +\end{command} + +\begin{command}{\pgfsys@thepageheight} + This macro expands to the current page's height, provided \LaTeX\ is used, + otherwise a best guess is returned (currently just |\the\vsize|). +\end{command} + +\begin{command}{\pgfsys@thepagewidth} + As above. +\end{command} + + +\subsection{Position Tracking Commands} + +The following commands are used to determine the position of text on a page. +This is a rather complicated process in general since at the moment when the +text is read by \TeX, the final position cannot be determined, yet. For +example, the text might be put in a box which is later put in the headline or +perhaps in the footline or perhaps even on a different page. + +For these reasons, position tracking is typically a two-stage process. In a +first stage you indicate that a certain position is of interest by +\emph{marking} it. This will (depending on the details of the backend driver) +cause page coordinates or this position to be written to an |.aux| file when +the page is shipped. Possibly, the position might also be determined at an even +later stage. Then, on a second run of \TeX, the position is read from the +|.aux| file and can be used. + +\begin{command}{\pgfsys@markposition\marg{name}} + Marks a position on the page. This command should be given while normal + typesetting is done such as in + % +\begin{codeexample}[code only] +The value of $x$ is \pgfsys@markposition{here}important. +\end{codeexample} + % + It causes the position |here| to be saved when the page is shipped out. +\end{command} + +\begin{command}{\pgfsys@getposition\marg{name}\marg{macro}} + This command retrieves a position that has been marked on an earlier run of + \TeX\ on the current file. The \meta{macro} must be a macro name such as + |\mymacro|. It will be redefined such that it is + % + \begin{itemize} + \item either just |\relax| or + \item a |\pgfpoint...| command. + \end{itemize} + % + The first case will happen when the position has not been marked at all or + when the file is typeset for the first time, when the coordinates are not + yet available. + + In the second case, executing \meta{macro} yields the position on the page + that is to be interpreted as follows: A coordinate like + |\pgfpoint{2cm}{3cm}| means ``2cm to the right and 3cm up from the origin + of the page''. The position of the origin of the page is not guaranteed to + be at the lower left corner, it is only guaranteed that all pictures on a + page use the same origin. + + To determine the lower left corner of a page, you can call + |\pgfsys@getposition| with \meta{name} set to the special name + |pgfpageorigin|. By shifting all positions by the amount returned by this + call you can position things absolutely on a page. + + \example Referencing a point of the page: + % +\begin{codeexample}[code only] +The value of $x$ is \pgfsys@markposition{here}important. + +Lots of text. + +\hbox{\pgfsys@markposition{myorigin}% +\begin{pgfpicture} + % Switch of size protocol + \pgfpathmoveto{\pgfpointorigin} + \pgfusepath{use as bounding box} + + \pgfsys@getposition{here}{\hereposition} + \pgfsys@getposition{myorigin}{\thispictureposition} + + \pgftransformshift{\pgfpointscale{-1}{\thispictureposition}} + \pgftransformshift{\hereposition} + + \pgfpathcircle{\pgfpointorigin}{1cm} + \pgfusepath{draw} +\end{pgfpicture}} +\end{codeexample} + % +\end{command} + + +\subsection{Internal Conversion Commands} + +The system commands take \TeX\ dimensions as input, but the dimensions that +have to be inserted into \pdf\ and PostScript files need to be dimensionless +values that are interpreted as multiples of $\frac{1}{72}\mathrm{in}$. For +example, the \TeX\ dimension $2bp$ should be inserted as |2| into a \pdf\ file +and the \TeX\ dimension $10\mathrm{pt}$ as |9.9626401|. To make this conversion +easier, the following command may be useful: + +\begin{command}{\pgf@sys@bp\marg{dimension}} + Inserts how many multiples of $\frac{1}{72}\mathrm{in}$ the + \meta{dimension} is into the current protocol stream (buffered). + + \example |\pgf@sys@bp{\pgf@x}| or |\pgf@sys@bp{1cm}|. +\end{command} + +Note that this command is \emph{not} a system command that can/needs to be +overwritten by a driver. + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |