summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex865
1 files changed, 865 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
new file mode 100644
index 00000000000..743e357485c
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex
@@ -0,0 +1,865 @@
+% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
+%
+% This program can be redistributed and/or modified under the terms
+% of the LaTeX Project Public License Distributed from CTAN
+% archives in directory macros/latex/base/lppl.txt.
+
+\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
+ ``setup 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 coordiante 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}
+
+
+
+\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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, see Section~\ref{section-protocols}.
+\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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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 protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@buttcap}
+ Sets the cap to a butt cap. See |\pgfsys@stroke|.
+
+ This command is protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@roundcap}
+ Sets the cap to a round cap. See |\pgfsys@stroke|.
+
+ This command is protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@rectcap}
+ Sets the cap to a rectangular cap. See |\pgfsys@stroke|.
+
+ This command is protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@miterjoin}
+ Sets the join to a miter join. See |\pgfsys@stroke|.
+
+ This command is protocoled, 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 protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@roundjoin}
+ Sets the join to a round join. See |\pgfsys@stroke|.
+
+ This command is protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@beveljoin}
+ Sets the join to a bevel join. See |\pgfsys@stroke|.
+
+ This command is protocoled, 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 lengths 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'' phases of the dashing and of the ``off''
+ phases. 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 protocoled, 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}
+}
+
+\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}
+
+
+\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 separatedly. 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 protocoled, 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@xxx|
+ command. Thus, each |\color| command will reset both the stroking
+ and filling colors by calling |\pgfsys@color@reset|.
+
+ This command is protocoled, 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 protocoled, 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
+ cymk tuple (numbers between 0 and 1).
+
+ This command is protocoled, 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 cymk tuple
+ (numbers between 0 and 1).
+
+ This command is protocoled, 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 cymk tuple
+ (numbers between 0 and 1).
+
+ This command is protocoled, 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
+ cym tuple (numbers between 0 and 1).
+
+ This command is protocoled, 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 cym tuple
+ (numbers between 0 and 1).
+
+ This command is protocoled, 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 cym tuple
+ (numbers between 0 and 1).
+
+ This command is protocoled, 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 protocoled, 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 protocoled, 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 protocoled, 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{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 protocoled, see Section~\ref{section-protocols}.
+\end{command}
+
+\begin{command}{\pgfsys@endscope}
+ Restores the last saved graphic state.
+
+ This command is protocoled, see Section~\ref{section-protocols}.
+\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 exactly only 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 setup 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}
+
+
+\begin{command}{\pgfsys@definemask}
+ This command declares a mask 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 soft 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{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 setup 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}
+
+
+\subsection{Reusable Objects System Commands}
+
+\begin{command}{\pgfsys@invoke\marg{literals}}
+ This command gets protocoled 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 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}
+
+
+\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 protocoled, 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 protocoled, see Section~\ref{section-protocols}.
+\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: