diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
commit | f07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch) | |
tree | 6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex | |
parent | 007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff) |
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
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.tex | 865 |
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: |