summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex
Initial commit
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex')
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex1380
1 files changed, 1380 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex
new file mode 100644
index 0000000000..47b876cd1b
--- /dev/null
+++ b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex
@@ -0,0 +1,1380 @@
+% Copyright 2006 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@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 not 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: