Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-commands.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Commands of the System Layer}
12
13 \makeatletter
14
15 \subsection{Beginning and Ending a Stream of System Commands}
16
17 A ``user'' of the \pgfname\ system layer (like the basic layer or a frontend)
18 will interface with the system layer by calling a stream of commands starting
19 with |\pgfsys@|. From the system layer's point of view, these commands form a
20 long stream. Between calls to the system layer, control goes back to the user.
21
22 The driver files implement system layer commands by inserting |\special|
23 commands that implement the desired operation. For example, |\pgfsys@stroke|
24 will be mapped to |\special{pdf: S}| by the driver file for |pdftex|.
25
26 For many drivers, when such a stream of specials starts, it is necessary to
27 install an appropriate transformation and perhaps perform some more
28 bureaucratic tasks. For this reason, every stream will start with a
29 |\pgfsys@beginpicture| and will end with a corresponding ending command.
30
31 \begin{command}{\pgfsys@beginpicture}
32 Called at the beginning of a |{pgfpicture}|. This command should ``set up
33 things''.
34
35 Most drivers will need to implement this command.
36 \end{command}
37
38 \begin{command}{\pgfsys@endpicture}
39 Called at the end of a |{pgfpicture}|.
40
41 Most drivers will need to implement this command.
42 \end{command}
43
44 \begin{command}{\pgfsys@typesetpicturebox\marg{box}}
45 Called \emph{after} a |{pgfpicture}| has been typeset. The picture will
46 have been put in box \meta{box}. This command should insert the box into
47 the normal text. The box \meta{box} will still be a ``raw'' box that
48 contains only the |\special|'s that make up the description of the picture.
49 The job of this command is to resize and shift \meta{box} according to the
50 baseline shift and the size of the box.
51
52 This command has a default implementation and need not be implemented by a
53 driver file.
54 \end{command}
55
56 \begin{command}{\pgfsys@beginpurepicture}
57 This version of the |\pgfsys@beginpicture| picture command can be used for
58 pictures that are guaranteed not to contain any escaped boxes (see below).
59 In this case, a driver might provide a more compact version of the command.
60
61 This command has a default implementation and need not be implemented by a
62 driver file.
63 \end{command}
64
65 \begin{command}{\pgfsys@endpurepicture}
66 Called at the end of a ``pure'' |{pgfpicture}|.
67
68 This command has a default implementation and need not be implemented by a
69 driver file.
70 \end{command}
71
72 Inside a stream it is sometimes necessary to ``escape'' back into normal
73 typesetting mode; for example to insert some normal text, but with all of the
74 current transformations and clippings being in force. For this escaping, the
75 following command is used:
76
77 \begin{command}{\pgfsys@hbox\marg{box number}}
78 Called to insert a (horizontal) TeX box inside a |{pgfpicture}|.
79
80 Most drivers will need to (re-)implement this command.
81 \end{command}
82
83 \begin{command}{\pgfsys@hboxsynced\marg{box number}}
84 Called to insert a (horizontal) TeX box inside a |{pgfpicture}|, but with
85 the current coordinate transformation matrix synced with the canvas
86 transformation matrix.
87
88 This command should do the same as if you used |\pgflowlevelsynccm|
89 followed by |\pgfsys@hbox|. However, the default implementation of this
90 command will use a ``TeX-translation'' for the translation part of the
91 transformation matrix. This will ensure that hyperlinks ``survive'' at
92 least translations. On the other hand, a driver may choose to revert to a
93 simpler implementation. This is done, for example, for the \textsc{svg}
94 implementation, where a \TeX-translation makes no sense.
95 \end{command}
96
97 \begin{command}{\pgfsys@pictureboxsynced\marg{box number}}
98 Basically, this should do the same as doing a (scoped) low level sync
99 followed by inserting the box \meta{box number} directly into the output
100 stream. However, the default implementation uses |\pgfsys@hboxsynced| in
101 conjunction with |\pgfsys@beginpicture| to ensure that, if possible,
102 hyperlinks survive in \textsc{pdf}s. Drivers that are sensitive to
103 picture-in-picture scopes should replace this implementation by
104 %
105 \begin{codeexample}[code only]
106 \pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope
107 \end{codeexample}
108 %
109 \end{command}
110
111
112 \subsection{Scoping System Commands}
113
114 The scoping commands are used to keep changes of the graphics state local.
115
116 \begin{command}{\pgfsys@beginscope}
117 Saves the current graphic state on a graphic state stack. All changes to
118 the graphic state parameters mentioned for |\pgfsys@stroke| and
119 |\pgfsys@fill| will be local to the current graphic state and the old
120 values will be restored after |\pgfsys@endscope| is used.
121
122 \emph{Warning:} \pdf\ and PostScript differ with respect to the question of
123 whether the current path is part of the graphic state or not. For this
124 reason, you should never use this command unless the path is currently
125 empty. For example, it might be a good idea to use |\pgfsys@discardpath|
126 prior to calling this command.
127
128 This command is protocolled, see Section~\ref{section-protocols}.
129 \end{command}
130
131 \begin{command}{\pgfsys@endscope}
132 Restores the last saved graphic state.
133
134 This command is protocolled, see Section~\ref{section-protocols}.
135 \end{command}
136
137
138 \subsection{Path Construction System Commands}
139
140 \begin{command}{\pgfsys@moveto\marg{x}\marg{y}}
141 This command is used to start a path at a specific point $(x,y)$ or to move
142 the current point of the current path to $(x,y)$ without drawing anything
143 upon stroking (the current path is ``interrupted'').
144
145 Both \meta{x} and \meta{y} are given as \TeX\ dimensions. It is the
146 driver's job to transform these to the coordinate system of the backend.
147 Typically, this means converting the \TeX\ dimension into a dimensionless
148 multiple of $\frac{1}{72}\mathrm{in}$. The function |\pgf@sys@bp| helps
149 with this conversion.
150
151 \example Draw a line from $(10\mathrm{pt},10\mathrm{pt})$ to the origin of
152 the picture.
153 %
154 \begin{codeexample}[code only]
155 \pgfsys@moveto{10pt}{10pt}
156 \pgfsys@lineto{0pt}{0pt}
157 \pgfsys@stroke
158 \end{codeexample}
159
160 This command is protocolled, see Section~\ref{section-protocols}.
161 \end{command}
162
163 \begin{command}{\pgfsys@lineto\marg{x}\marg{y}}
164 Continue the current path to $(x,y)$ with a straight line.
165
166 This command is protocolled, see Section~\ref{section-protocols}.
167 \end{command}
168
169 \begin{command}{\pgfsys@curveto\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}\marg{$x_3$}\marg{$y_3$}}
170 Continue the current path to $(x_3,y_3)$ with a Bézier curve that has the
171 two control points $(x_1,y_1)$ and $(x_2,y_2)$.
172
173 \example Draw a good approximation of a quarter circle:
174 %
175 \begin{codeexample}[code only]
176 \pgfsys@moveto{10pt}{0pt}
177 \pgfsys@curveto{10pt}{5.55pt}{5.55pt}{10pt}{0pt}{10pt}
178 \pgfsys@stroke
179 \end{codeexample}
180
181 This command is protocolled, see Section~\ref{section-protocols}.
182 \end{command}
183
184 \begin{command}{\pgfsys@rect\marg{x}\marg{y}\marg{width}\marg{height}}
185 Append a rectangle to the current path whose lower left corner is at
186 $(x,y)$ and whose width and height in big points are given by \meta{width}
187 and \meta{height}.
188
189 This command can be ``mapped back'' to |\pgfsys@moveto| and
190 |\pgfsys@lineto| commands, but it is included since \pdf\ has a special,
191 quick version of this command.
192
193 This command is protocolled, see Section~\ref{section-protocols}.
194 \end{command}
195
196 \begin{command}{\pgfsys@closepath}
197 Close the current path. This results in joining the current point of the
198 path with the point specified by the last |\pgfsys@moveto| operation.
199 Typically, this is preferable over using |\pgfsys@lineto| to the last point
200 specified by a |\pgfsys@moveto|, since the line starting at this point and
201 the line ending at this point will be smoothly joined by
202 |\pgfsys@closepath|.
203
204 \example Consider
205 %
206 \begin{codeexample}[code only]
207 \pgfsys@moveto{0pt}{0pt}
208 \pgfsys@lineto{10bp}{10bp}
209 \pgfsys@lineto{0bp}{10bp}
210 \pgfsys@closepath
211 \pgfsys@stroke
212 \end{codeexample}
213 %
214 and
215 %
216 \begin{codeexample}[code only]
217 \pgfsys@moveto{0bp}{0bp}
218 \pgfsys@lineto{10bp}{10bp}
219 \pgfsys@lineto{0bp}{10bp}
220 \pgfsys@lineto{0bp}{0bp}
221 \pgfsys@stroke
222 \end{codeexample}
223
224 The difference between the above will be that in the second triangle the
225 corner at the origin will be wrong; it will just be the overlay of two
226 lines going in different directions, not a sharp pointed corner.
227
228 This command is protocolled, see Section~\ref{section-protocols}.
229 \end{command}
230
231
232 \subsection{Canvas Transformation System Commands}
233
234 \begin{command}{\pgfsys@transformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}}
235 Perform a concatenation of the canvas transformation matrix with the matrix
236 given by the values \meta{a} to \meta{f}, see the \pdf\ or PostScript
237 manual for details. The values \meta{a} to \meta{d} are dimensionless
238 factors, \meta{e} and \meta{f} are \TeX\ dimensions
239
240 \example |\pgfsys@transformcm{1}{0}{0}{1}{1cm}{1cm}|.
241
242 This command is protocolled, see Section~\ref{section-protocols}.
243 \end{command}
244
245 \begin{command}{\pgfsys@transformshift\marg{x displacement}\marg{y displacement}}
246 This command will change the origin of the canvas to $(x,y)$.
247
248 This command has a default implementation and need not be implemented by a
249 driver file.
250
251 This command is protocolled, see Section~\ref{section-protocols}.
252 \end{command}
253
254 \begin{command}{\pgfsys@transformxyscale\marg{x scale}\marg{y scale}}
255 This command will scale the canvas (and everything that is drawn) by a
256 factor of \meta{x scale} in the $x$-direction and \meta{y scale} in the
257 $y$-direction. Note that this applies to everything, including lines. So a
258 scaled line will have a different width and may even have a different width
259 when going along the $x$-axis and when going along the $y$-axis, if the
260 scaling is different in these directions. Usually, you do not want this.
261
262 This command has a default implementation and need not be implemented by a
263 driver file.
264
265 This command is protocolled, see Section~\ref{section-protocols}.
266 \end{command}
267
268 \begin{command}{\pgfsys@viewboxmeet\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}%
269 \marg{$x'_1$}\marg{$y'_1$}\marg{$x'_2$}\marg{$y'_2$}%
270 }
271 Starts a ``view box'' scope, which must be ended using |\pgfsys@endviewbox|
272 later on (with matching scopes).
273
274 The effect of this command is as follows: Consider the rectangles $R$ with
275 lower left corner $(x_1,y_1)$ and upper right corner $(x_2,y_2)$ and $R'$
276 with corners $(x'_1,y'_1)$ and $(x'_2,y'_2)$. The command will install a
277 canvas translation and uniform scaling such that $R'$ then has the same
278 center as~$R$ and additionally, has maximum size such that it still fits
279 inside~$R$. (Think of this as ``viewing'' $R'$ through $R$ such that the
280 aspect ratio is kept.)
281
282 This command has a default implementation. Its main purpose is to allow
283 animations of the view box; for static drawings it is better to compute the
284 necessary transformations directly.
285 \end{command}
286
287 \begin{command}{\pgfsys@viewboxslice\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}%
288 \marg{$x'_1$}\marg{$y'_1$}\marg{$x'_2$}\marg{$y'_2$}%
289 }
290 Works like the previous command, but now $R'$ has minimal size such that it
291 encompasses all of $R$.
292 \end{command}
293
294 \begin{command}{\pgfsys@endviewbox}
295 Ends a viewbox previously started using |\pgfsys@viewboxmeet| or the
296 |...slice| variant.
297 \end{command}
298
299
300 \subsection{Stroking, Filling, and Clipping System Commands}
301
302 \begin{command}{\pgfsys@stroke}
303 Stroke the current path (as if it were drawn with a pen). A number of
304 graphic state parameters influence this, which can be set using appropriate
305 system commands described later.
306 %
307 \begin{description}
308 \item[Line width] The ``thickness'' of the line. A width of 0 is the
309 thinnest width renderable on the device. On a high-resolution
310 printer this may become invisible and should be avoided. A good
311 choice is 0.4pt, which is the default.
312 \item[Stroke color] This special color is used for stroking. If it is
313 not set, the current color is used.
314 \item[Cap] The cap describes how the endings of lines are drawn. A
315 round cap adds a little half circle to these endings. A butt cap
316 ends the lines exactly at the end (or start) point without anything
317 added. A rectangular cap ends the lines like the butt cap, but the
318 lines protrude over the endpoint by the line thickness. (See also
319 the \pdf\ manual.) If the path has been closed, no cap is drawn.
320 \item[Join] This describes how a bend (a join) in a path is rendered. A
321 round join draws bends using small arcs. A bevel join just draws
322 the two lines and then fills the join minimally so that it becomes
323 convex. A miter join extends the lines so that they form a single
324 sharp corner, but only up to a certain miter limit. (See the \pdf\
325 manual once more.)
326 \item[Dash] The line may be dashed according to a dashing pattern.
327 \item[Clipping area] If a clipping area is established, only those
328 parts of the path that are inside the clipping area will be drawn.
329 \end{description}
330
331 In addition to stroking a path, the path may also be used for clipping
332 after it has been stroked. This will happen if the |\pgfsys@clipnext| is
333 used prior to this command, see there for details.
334
335 This command is protocolled, see Section~\ref{section-protocols}.
336 \end{command}
337
338 \begin{command}{\pgfsys@closestroke}
339 This command should have the same effect as first closing the path and then
340 stroking it.
341
342 This command has a default implementation and need not be implemented by a
343 driver file.
344
345 This command is protocolled, see Section~\ref{section-protocols}.
346 \end{command}
347
348
349 \begin{command}{\pgfsys@fill}
350 This command fills the area surrounded by the current path. If the path has
351 not yet been closed, it is closed prior to filling. The path itself is not
352 stroked. For self-intersecting paths or paths consisting of multiple parts,
353 the nonzero winding number rule is used to determine whether a point is
354 inside or outside the path, except if |\ifpgfsys@eorule| holds -- in which
355 case the even-odd rule should be used. (See the \pdf\ or PostScript manual
356 for details.)
357
358 The following graphic state parameters influence the filling:
359 %
360 \begin{description}
361 \item[Interior rule] If |\ifpgfsys@eorule| is set, the even-odd rule is
362 used, otherwise the non-zero winding number rule.
363 \item[Fill color] If the fill color is not especially set, the current
364 color is used.
365 \item[Clipping area] If a clipping area is established, only those
366 parts of the filling area that are inside the clipping area will be
367 drawn.
368 \end{description}
369
370 In addition to filling the path, the path will also be used for clipping if
371 |\pgfsys@clipnext| is used prior to this command.
372
373 This command is protocolled, see Section~\ref{section-protocols}.
374 \end{command}
375
376 \begin{command}{\pgfsys@fillstroke}
377 First, the path is filled, then the path is stroked. If the fill and stroke
378 colors are the same (or if they are not specified and the current color is
379 used), this yields almost the same as a |\pgfsys@fill|. However, due to the
380 line thickness of the stroked path, the fill-stroked area will be slightly
381 larger.
382
383 In addition to stroking and filling the path, the path will also be used
384 for clipping if |\pgfsys@clipnext| is used prior to this command.
385
386 This command is protocolled, see Section~\ref{section-protocols}.
387 \end{command}
388
389 \begin{command}{\pgfsys@discardpath}
390 Normally, this command should ``throw away'' the current path. However,
391 after |\pgfsys@clipnext| has been called, the current path should
392 subsequently be used for clipping. See |\pgfsys@clipnext| for details.
393
394 This command is protocolled, see Section~\ref{section-protocols}.
395 \end{command}
396
397 \begin{command}{\pgfsys@clipnext}
398 This command should be issued after a path has been constructed, but before
399 it has been stroked and/or filled or discarded. When the command is used,
400 the next stroking/filling/discarding command will first be executed
401 normally. Then, afterwards, the just-used path will be used for subsequent
402 clipping. If there has already been a clipping region, this region is
403 intersected with the new clipping path (the clipping cannot get bigger).
404 The nonzero winding number rule is used to determine whether a point is
405 inside or outside the clipping area or the even-odd rule, depending on
406 whether |\ifpgfsys@eorule| holds.
407 \end{command}
408
409
410 \subsection{Graphic State Option System Commands}
411
412 \begin{command}{\pgfsys@setlinewidth\marg{width}}
413 Sets the width of lines, when stroked, to \meta{width}, which must be a
414 \TeX\ dimension.
415
416 This command is protocolled, see Section~\ref{section-protocols}.
417 \end{command}
418
419 \begin{command}{\pgfsys@buttcap}
420 Sets the cap to a butt cap. See |\pgfsys@stroke|.
421
422 This command is protocolled, see Section~\ref{section-protocols}.
423 \end{command}
424
425 \begin{command}{\pgfsys@roundcap}
426 Sets the cap to a round cap. See |\pgfsys@stroke|.
427
428 This command is protocolled, see Section~\ref{section-protocols}.
429 \end{command}
430
431 \begin{command}{\pgfsys@rectcap}
432 Sets the cap to a rectangular cap. See |\pgfsys@stroke|.
433
434 This command is protocolled, see Section~\ref{section-protocols}.
435 \end{command}
436
437 \begin{command}{\pgfsys@miterjoin}
438 Sets the join to a miter join. See |\pgfsys@stroke|.
439
440 This command is protocolled, see Section~\ref{section-protocols}.
441 \end{command}
442
443 \begin{command}{\pgfsys@setmiterlimit\marg{factor}}
444 Sets the miter limit of lines to \meta{factor}. See the \pdf\ or PostScript
445 for details on what the miter limit is.
446
447 This command is protocolled, see Section~\ref{section-protocols}.
448 \end{command}
449
450 \begin{command}{\pgfsys@roundjoin}
451 Sets the join to a round join. See |\pgfsys@stroke|.
452
453 This command is protocolled, see Section~\ref{section-protocols}.
454 \end{command}
455
456 \begin{command}{\pgfsys@beveljoin}
457 Sets the join to a bevel join. See |\pgfsys@stroke|.
458
459 This command is protocolled, see Section~\ref{section-protocols}.
460 \end{command}
461
462 \begin{command}{\pgfsys@setdash\marg{pattern}\marg{phase}}
463 Sets the dashing pattern. \meta{pattern} should be a list of \TeX\
464 dimensions separated by commas. \meta{phase} should be a single dimension.
465
466 \example |\pgfsys@setdash{3pt,3pt}{0pt}|
467
468 The list of values in \meta{pattern} is used to determine the lengths of
469 the ``on'' and ``off'' phases of the dashing. For example, if
470 \meta{pattern} is |3bp,4bp|, then the dashing pattern is ``3bp on followed
471 by 4bp off, followed by 3bp on, followed by 4bp off, and so on''. A pattern
472 of |.5pt,4pt,3pt,1.5pt| means ``.5pt on, 4pt off, 3pt on, 1.5pt off, .5pt
473 on, \dots'' If the number of entries is odd, the last one is used twice, so
474 |3pt| means ``3pt on, 3pt off, 3pt on, 3pt off, \dots'' An empty list means
475 ``always on''.
476
477 The second argument determines the ``phase'' of the pattern. For example,
478 for a pattern of |3bp,4bp| and a phase of |1bp|, the pattern would start:
479 ``2bp on, 4bp off, 3bp on, 4bp off, 3bp on, 4bp off, \dots''
480
481 This command is protocolled, see Section~\ref{section-protocols}.
482 \end{command}
483
484 {\let\ifpgfsys@eorule=\relax
485 \begin{command}{\ifpgfsys@eorule}
486 Determines whether the even odd rule is used for filling and clipping or
487 not.
488 \end{command}
489 }
490
491
492 \subsection{Color System Commands}
493
494 The \pgfname\ system layer provides a number of system commands for setting
495 colors. These command coexist with commands from the |color| and |xcolor|
496 package, which perform similar functions. However, the |color| package does not
497 support having two different colors for stroking and filling, which is a useful
498 feature that is supported by \pgfname. For this reason, the \pgfname\ system
499 layer offers commands for setting these colors separately. Also, plain \TeX\
500 profits from the fact that \pgfname\ can set colors.
501
502 For \pdf, implementing these color commands is easy since \pdf\ supports
503 different stroking and filling colors directly. For PostScript, a more
504 complicated approach is needed in which the colors need to be stored in special
505 PostScript variables that are set whenever a stroking or a filling operation is
506 done.
507
508 \begin{command}{\pgfsys@color@rgb\marg{red}\marg{green}\marg{blue}}
509 Sets the color used for stroking and filling operations to the given
510 red/green/blue tuple (numbers between 0 and 1).
511
512 This command is protocolled, see Section~\ref{section-protocols}.
513 \end{command}
514
515 \begin{command}{\pgfsys@color@rgb@stroke\marg{red}\marg{green}\marg{blue}}
516 Sets the color used for stroking operations to the given red/green/blue
517 tuple (numbers between 0 and 1).
518
519 \example Make stroked text dark red: |\pgfsys@color@rgb@stroke{0.5}{0}{0}|
520
521 The special stroking color is only used if the stroking color has been set
522 since the last |\color| or |\pgfsys@color@...| command. Thus, each |\color|
523 command will reset both the stroking and filling colors by calling
524 |\pgfsys@color@reset|.
525
526 This command is protocolled, see Section~\ref{section-protocols}.
527 \end{command}
528
529 \begin{command}{\pgfsys@color@rgb@fill\marg{red}\marg{green}\marg{blue}}
530 Sets the color used for filling operations to the given red/green/blue
531 tuple (numbers between 0 and 1). This color may be different from the
532 stroking color.
533
534 This command is protocolled, see Section~\ref{section-protocols}.
535 \end{command}
536
537 \begin{command}{\pgfsys@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
538 Sets the color used for stroking and filling operations to the given cmyk
539 tuple (numbers between 0 and 1).
540
541 This command is protocolled, see Section~\ref{section-protocols}.
542 \end{command}
543
544 \begin{command}{\pgfsys@color@cmyk@stroke\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
545 Sets the color used for stroking operations to the given cmyk tuple
546 (numbers between 0 and 1).
547
548 This command is protocolled, see Section~\ref{section-protocols}.
549 \end{command}
550
551 \begin{command}{\pgfsys@color@cmyk@fill\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
552 Sets the color used for filling operations to the given cmyk tuple (numbers
553 between 0 and 1).
554
555 This command is protocolled, see Section~\ref{section-protocols}.
556 \end{command}
557
558 \begin{command}{\pgfsys@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}}
559 Sets the color used for stroking and filling operations to the given cmy
560 tuple (numbers between 0 and 1).
561
562 This command is protocolled, see Section~\ref{section-protocols}.
563 \end{command}
564
565 \begin{command}{\pgfsys@color@cmy@stroke\marg{cyan}\marg{magenta}\marg{yellow}}
566 Sets the color used for stroking operations to the given cmy tuple (numbers
567 between 0 and 1).
568
569 This command is protocolled, see Section~\ref{section-protocols}.
570 \end{command}
571
572 \begin{command}{\pgfsys@color@cmy@fill\marg{cyan}\marg{magenta}\marg{yellow}}
573 Sets the color used for filling operations to the given cmy tuple (numbers
574 between 0 and 1).
575
576 This command is protocolled, see Section~\ref{section-protocols}.
577 \end{command}
578
579 \begin{command}{\pgfsys@color@gray\marg{black}}
580 Sets the color used for stroking and filling operations to the given black
581 value, where 0 means black and 1 means white.
582
583 This command is protocolled, see Section~\ref{section-protocols}.
584 \end{command}
585
586 \begin{command}{\pgfsys@color@gray@stroke\marg{black}}
587 Sets the color used for stroking operations to the given black value, where
588 0 means black and 1 means white.
589
590 This command is protocolled, see Section~\ref{section-protocols}.
591 \end{command}
592
593 \begin{command}{\pgfsys@color@gray@fill\marg{black}}
594 Sets the color used for filling operations to the given black value, where
595 0 means black and 1 means white.
596
597 This command is protocolled, see Section~\ref{section-protocols}.
598 \end{command}
599
600 \begin{command}{\pgfsys@color@reset}
601 This command will be called when the |\color| command is used. It should
602 purge any internal settings of stroking and filling color. After this call,
603 till the next use of a command like |\pgfsys@color@rgb@fill|, the current
604 color installed by the |\color| command should be used.
605
606 If the \TeX-if |\pgfsys@color@reset@inorder| is set to true, this command
607 may ``assume'' that any call to a color command that sets the fill or
608 stroke color came ``before'' the call to this command and may try to
609 optimize the output accordingly.
610
611 An example of an incorrect ``out of order'' call would be using
612 |\pgfsys@color@reset| at the beginning of a box that is constructed using
613 |\setbox|. Then, when the box is constructed, no special fill or stroke
614 color might be in force. However, when the box is later on inserted at some
615 point, a special fill color might already have been set. In this case, this
616 command is not guaranteed to reset the color correctly.
617 \end{command}
618
619 \begin{command}{\pgfsys@color@reset@inordertrue}
620 Sets the optimized ``in order'' version of the color resetting. This is the
621 default.
622 \end{command}
623
624 \begin{command}{\pgfsys@color@reset@inorderfalse}
625 Switches off the optimized color resetting.
626 \end{command}
627
628 \begin{command}{\pgfsys@color@unstacked\marg{\LaTeX\ color}}
629 This slightly obscure command causes the color stack to be tricked. When
630 called, this command should set the current color to \meta{\LaTeX\ color}
631 without causing any change in the color stack.
632
633 \example |\pgfsys@color@unstacked{red}|
634 \end{command}
635
636
637 \subsection{Pattern System Commands}
638
639 \begin{command}{\pgfsys@declarepattern
640 \marg{name}\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}%
641 \marg{$x$ step}\marg{$y$ step}%
642 \marg{$a$}\marg{$b$}\marg{$c$}\marg{$d$}\allowbreak\marg{$e$}\marg{$f$}%
643 \marg{code}\marg{flag}%
644 }
645 This command declares a new colored or uncolored pattern, depending on
646 whether \meta{flag} is |0|, which means uncolored, or |1|, which means
647 colored. Uncolored patterns have no inherent color, the color is provided
648 when they are set. Colored patterns have an inherent color.
649
650 The \meta{name} is a name for later use when the pattern is to be shown.
651 The pairs $(x_1,y_1)$ and $(x_2,y_2)$ must describe a bounding box of the
652 pattern \meta{code}.
653
654 The tiling step of the pattern is given by \meta{$x$ step} and \meta{$y$
655 step}.
656
657 The parameters \meta{$a$} to \meta{$f$} are entries of the transformation
658 matrix that is applied to the pattern, see |\pgfsys@patternmatrix| for more
659 information.
660
661 \example
662 %
663 \begin{codeexample}[code only]
664 \pgfsys@declarepattern
665 {hori}{-.5pt}{0pt}{.5pt}{3pt}{3pt}{3pt}%
666 {1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}%
667 {\pgfsys@moveto{0pt}{0pt}\pgfsys@lineto{0pt}{3pt}\pgfsys@stroke}
668 {0}
669 \end{codeexample}
670 %
671 \end{command}
672
673
674 \begin{command}{\pgfsys@patternmatrix}
675 For convenience \pgfname\ defines the transformation matrix that is applied
676 to all patterns defined with |\pgfdeclarepatternformonly| and
677 |\pgfdeclarepatterninherentlycolored| in a macro. This can be used as an
678 extension point for ad-hoc transformation of existing patterns. The
679 default definition is the
680 identity matrix:
681 %
682 \begin{codeexample}[code only]
683 \def\pgfsys@patternmatrix{{1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}}
684 \end{codeexample}
685 %
686 The entries of the enclosed array
687 |{|\meta{$a$}|}{|\meta{$b$}|}{|\meta{$c$}|}{|\meta{$d$}|}{|\meta{$e$}|}{|\meta{$f$}|}|
688 are entries in the transformation matrix, identified as in the following
689 transformation prescription:
690 \begin{equation*}
691 \begin{pmatrix}
692 x' \\
693 y' \\
694 1 \\
695 \end{pmatrix}
696 =
697 \begin{pmatrix}
698 a & c & e \\
699 b & d & f \\
700 0 & 0 & 1 \\
701 \end{pmatrix}
702 \begin{pmatrix}
703 x \\
704 y \\
705 1 \\
706 \end{pmatrix} .
707 \end{equation*}
708 Carrying out the matrix multiplication results in the following system of
709 equations
710 \begin{align*}
711 x' &= a x + c y + e , \\
712 y' &= b x + d y + f .
713 \end{align*}
714 Evidently, the parameters \marg{$a$} to \marg{$d$} have to be dimensionless
715 because they are scaling factors, but the parameters \marg{$e$} and
716 \marg{$f$} are offsets, therefore they have to carry a unit.
717 \end{command}
718
719 \begin{command}{\pgfsys@setpatternuncolored\marg{name}\marg{red}\marg{green}\marg{blue}}
720 Sets the fill color to the pattern named \meta{name}. This pattern must
721 previously have been declared with \meta{flag} set to |0|. The color of the
722 pattern is given in the parameters \meta{red}, \meta{green}, and
723 \meta{blue} in the usual way.
724
725 The fill color ``pattern'' will persist till the next color command that
726 modifies the fill color.
727 \end{command}
728
729 \begin{command}{\pgfsys@setpatterncolored\marg{name}}
730 Sets the fill color to the pattern named \meta{name}. This pattern must
731 have been declared with the |1| flag.
732 \end{command}
733
734
735 \subsection{Image System Commands}
736
737 The system layer provides some commands for image inclusion.
738
739 \begin{command}{\pgfsys@imagesuffixlist}
740 This macro should expand to a list of suffixes, separated by `:', that will
741 be tried when searching for an image.
742
743 \example |\def\pgfsys@imagesuffixlist{eps:epsi:ps}|
744 \end{command}
745
746 \begin{command}{\pgfsys@defineimage}
747 Called, when an image should be defined.
748
749 This command does not take any parameters. Instead, certain macros will be
750 preinstalled with appropriate values when this command is invoked. These
751 are:
752 %
753 \begin{itemize}
754 \item\declare{|\pgf@filename|} File name of the image to be defined.
755 \item\declare{|\pgf@imagewidth|} Will be set to the desired (scaled)
756 width of the image.
757 \item\declare{|\pgf@imageheight|} Will be set to the desired (scaled)
758 height of the image.
759
760 If this macro and also the height macro are empty, the image should
761 have its ``natural'' size.
762
763 If only one of them is specified, the undefined value the image is
764 scaled so that the aspect ratio is kept.
765
766 If both are set, the image is scaled in both directions
767 independently, possibly changing the aspect ratio.
768 \end{itemize}
769
770 The following macros presumable mostly make sense for drivers that
771 can handle \pdf:
772 %
773 \begin{itemize}
774 \item \declare{|\pgf@imagepage|} The desired page number to be
775 extracted from a multi-page ``image''.
776 \item\declare{|\pgf@imagemask|} If set, it will be set to
777 |/SMask x 0 R| where |x| is the \pdf\ object number of a soft mask
778 to be applied to the image.
779 \item\declare{|\pgf@imageinterpolate|} If set, it will be set to
780 |/Interpolate true| or |/Interpolate false|, indicating whether the
781 image should be interpolated in \pdf.
782 \end{itemize}
783
784 The command should now set up the macro |\pgf@image| such that calling this
785 macro will result in typesetting the image. Thus, |\pgf@image| is the
786 ``return value'' of the command.
787
788 This command has a default implementation and need not be implemented by a
789 driver file.
790 \end{command}
791
792
793 \subsection{Shading System Commands}
794
795 \begin{command}{\pgfsys@horishading\marg{name}\marg{height}\marg{specification}}
796 Declares a horizontal shading for later use. The effect of this command
797 should be the definition of a macro called |\@pgfshading|\meta{name}|!| (or
798 |\csname @pdfshading|\meta{name}|!\endcsname|, to be precise). When
799 invoked, this new macro should insert a shading at the current position.
800
801 \meta{name} is the name of the shading, which is also used in the output
802 macro name. \meta{height} is the height of the shading and must be given as
803 a TeX dimension like |2cm| or |10pt|. \meta{specification} is a shading
804 color specification as specified in Section~\ref{section-shadings}. The
805 shading specification implicitly fixes the width of the shading.
806
807 When |\@pgfshading|\meta{name}|!| is invoked, it should insert a box of
808 height \meta{height} and the width implicit in the shading declaration.
809 \end{command}
810
811 \begin{command}{\pgfsys@vertshading\marg{name}\marg{width}\marg{specification}}
812 Like the horizontal version, only for vertical shadings. This time, the
813 height of the shading is implicit in \meta{specification} and the width is
814 given as \meta{width}.
815 \end{command}
816
817 \begin{command}{\pgfsys@radialshading\marg{name}\marg{starting point}\marg{specification}}
818 Declares a radial shading. Like the previous macros, this command should
819 set up the macro |\@pgfshading|\meta{name}|!|, which upon invocation should
820 insert a radial shading whose size is implicit in \meta{specification}.
821
822 The parameter \meta{starting point} is a \pgfname\ point specifying the
823 inner starting point of the shading.
824 \end{command}
825
826 \begin{command}{\pgfsys@functionalshading\marg{name}\marg{lower left corner}\meta{upper right corner}\marg{type 4 function}}
827 Declares a shading using a PostScript-like function that provides a color
828 for each point. Like the previous macros, this command should set up the
829 macro |\@pgfshading|\meta{name}|!| so that it will produce a box containing
830 the desired shading.
831
832 Parameter \meta{name} is the name of the shading. Parameter \meta{type 4
833 function} is a Postscript-like function (type 4 function of the PDF
834 specification) as described in Section~3.9.4 of the PDF specification
835 version 1.7. Parameters \meta{lower left corner} and \meta{upper right
836 corner} are \pgfname\ points that specifies the lower left and upper right
837 corners of the shading, respectively.
838
839 When \meta{type 4 function} is evaluated, the coordinate of the current
840 point will be on the (virtual) PostScript stack in bp units. After the
841 function has been evaluated, the stack should consist of three numbers (not
842 integers! -- the Apple PDF renderer is broken in this regard, so add cvrs
843 at the end if needed) that represent the red, green, and blue components of
844 the color.
845
846 A buggy function will result is \emph{totally unpredictable chaos} during
847 rendering.
848 \end{command}
849
850
851 \subsection{Transparency System Commands}
852
853 \begin{command}{\pgfsys@opacity\marg{value}}
854 Sets the opacity of all operations, treating stroking and filling as a
855 transparency group. Some drivers support this operations, others do not and
856 set the fill and stroke individually. This difference can only be seen when
857 a path is stroked and filled at the same time: When the drawing and fill
858 opacities are set individually, the effect of filling and drawing a path at
859 the same time is the same as first filling the path and then drawing it. On
860 the other, if the opacity is set using this command, the effect should
861 rather be that same as first filling and then drawing the path without any
862 opacity in an off-screen area and then copying the result to the target
863 area with a homogeneous opacity of \meta{value}.
864
865 Since \textsc{pdf} does not support this form of opacity, this command is
866 only present on the system layer and not supported in the basic layer.
867 \end{command}
868
869 \begin{command}{\pgfsys@stroke@opacity\marg{value}}
870 Sets the opacity of stroking operations.
871 \end{command}
872
873 \begin{command}{\pgfsys@fill@opacity\marg{value}}
874 Sets the opacity of filling operations.
875 \end{command}
876
877 \begin{command}{\pgfsys@blend@mode\marg{value}}
878 Sets the blend mode, see Section~7.2.4 of the \textsc{pdf} Specification,
879 Version~1.7.
880 \end{command}
881
882 \begin{command}{\pgfsys@transparencygroupfrombox\marg{box}}
883 This takes a \TeX\ box and converts it into a transparency group. This
884 means that any transparency settings apply to the box as a whole. For
885 instance, if a box contains two overlapping black circles and you draw the
886 box and, thus, the two circles normally with 50\% transparency, then the
887 overlap will be darker than the rest. By comparison, if the circles are
888 part of a transparency group, the overlap will get the same color as the
889 rest.
890 \end{command}
891
892 A transparency group can be \emph{isolated} and/or a \emph{knockout} group (see
893 Sections~7.3.4 and 7.3.5 of the \textsc{pdf} Specification Version~1.7). Which
894 of these is the case is dictated by the current settings of the following two
895 ifs, which must be set before the above command is called:
896
897 {\let\ifpgfsys@transparency@group@isolated=\relax
898 \begin{command}{\ifpgfsys@transparency@group@isolated}
899 Determines whether a transparency group should be isolated.
900 \end{command}
901 }
902
903 {\let\ifpgfsys@transparency@group@knockout=\relax
904 \begin{command}{\ifpgfsys@transparency@group@knockout}
905 Determines whether a transparency group is a knockout group or not.
906 \end{command}
907 }
908
909 \begin{command}{\pgfsys@fadingfrombox\marg{name}\marg{box}}
910 Declares the fading \meta{name}. The \meta{box} is a \TeX-box. Its
911 content's luminosity determines the opacity of the resulting fading. This
912 means that the lighter a pixel inside the box, the more opaque the fading
913 will be at this position.
914 \end{command}
915
916 \begin{command}{\pgfsys@usefading\meta{name}\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}}
917 Installs a previously declared fading \meta{name} in the current graphics
918 state. Afterwards, all drawings will be masked by the fading. The fading
919 should be centered on the origin and have its original size, except that
920 the parameters \meta{a} to \meta{f} specify a transformation matrix that
921 should be applied additionally to the fading before it is installed. The
922 transformation should not apply to the following graphics, however.
923 \end{command}
924
925 \pagebreak[2]
926 \begin{command}{\pgfsys@clipfading}
927 This command has a default implementation and need not be implemented by
928 driver files other than |pgfsys-dvips.def|. The macro is called
929 in
930 \begin{quote}
931 |\pgfsetfadingforcurrentpath| and |\pgfsetfadingforcurrentpathstroked|
932 \end{quote}
933 of the basic layer, where it invokes the current path for clipping the
934 shading just before installing it as an opacity mask for fading. The
935 default implementation is actually a non-operation, but with |dvips| it
936 is used to clip the fading as described.
937 \end{command}
938
939 \begin{command}{\pgfsys@definemask}
940 This command declares a fading (known as a soft mask in this context) based
941 on an image and for usage with images. It works similar to
942 |\pgfsys@defineimage|: Certain macros are set when the command is called.
943 The result should be to set the macro |\pgf@mask| to a pdf object count
944 that can subsequently be used as a transparency mask. The following macros
945 will be set when this command is invoked:
946 %
947 \begin{itemize}
948 \item \declare{|\pgf@filename|}
949 File name of the mask to be defined.
950 \item \declare{|\pgf@maskmatte|}
951 The so-called matte of the mask (see the \pdf\ documentation for
952 details). The matte is a color specification consisting of 1, 3 or
953 4 numbers between 0 and 1. The number of numbers depends on the
954 number of color channels in the image (not in the mask!). It will
955 be assumed that the image has been preblended with this color.
956 \end{itemize}
957 \end{command}
958
959
960 \subsection{Animation Commands}
961
962 The animation system layer command (|\pgfsys@anim...|) are described in a
963 separate section, Section~\ref{section-pgfsys-anim}.
964
965
966 \subsection{Object Identification System Commands}
967 \label{section-sys-id}
968
969 The system layer provides commands for adding identification labels (ids) to
970 different objects in a graphic. These can be used for hyperlinking, which is
971 needed for instance in conjunction with animations.
972
973 The following ``objects'' can get an id assigned to them:
974 %
975 \begin{enumerate}
976 \item Graphic scopes (namely when |\pgfsys@begin@idscope| is called),
977 \item view boxes (namely when |\pgfsys@viewboxmeet| or
978 |\pgfsys@viewboxslice| are called),
979 \item paths (namely when |\pgfsys@fill|, |\pgfsys@stroke|, and so on are
980 called),
981 \item text boxes (namely when |\pgfsys@hbox| or |\pgfsys@hboxsynced| is
982 called), and
983 \item animations (namely when |\pgfsys@animate| is called).
984 \end{enumerate}
985
986 Creating and using ids is a two-step process. First, you create the id using
987 |\pgfsys@new@id|, which stores a fresh id in a macro. You can now pass this id
988 around and clone it. Then, at some point, you wish one of the above objects to
989 actually get this id. For this, you use |\pgfsys@use@id| just \emph{before} the
990 object since this command always influences the \emph{next} object.
991
992 The basic id management gets more powerful when you use \emph{id types}. The
993 idea is as follows: In reality, the objects from above do not get assigned only
994 an id, but rather a combination of an id and a type -- and you can set the type
995 independently of the id. This is used, for instance, to allow easy access to
996 the different parts of a node in animations: Each node has a single id, but
997 consists of several graphic objects (normally, at least a background path and a
998 text). Each of these uses the same underlying id of the node, but the path has
999 the type |path| (actually |background.path|) while the text has the type
1000 |text|. The advantage is that for each node only one id must be stored instead
1001 of a great number of the many different possible parts of a node.
1002
1003 \begin{command}{\pgfsys@new@id\marg{macro}}
1004 Creates a new id for later use and stores it in \meta{macro}. It is an
1005 internal text created by the driver and may not be changed or modified.
1006 \end{command}
1007
1008 \begin{command}{\pgfsys@use@id\marg{id}}
1009 ``Uses'' an id previously created using |\pgfsys@new@id|. This causes the
1010 \emph{next} graphic object to get the \meta{id} (not the current one). Once
1011 used, the id-type-pair becomes \emph{invalid} and will not be attached to
1012 any other graphics objects. It is, however, not an error to try this. If
1013 \meta{id} is empty, no id-type-pair is attached to the next object.
1014 \end{command}
1015
1016 \begin{command}{\pgfsys@use@type\marg{type}}
1017 Changes the type used with the next graphic object. As mentioned earlier,
1018 the id assigned to the next object is actually a pair consisting of the
1019 currently used id and the currently used type.
1020 \end{command}
1021
1022 \begin{command}{\pgfsys@append@type\marg{text}}
1023 Appends the \meta{text} to the current type.
1024 \end{command}
1025
1026 \begin{command}{\pgfsys@push@type}
1027 Pushes the current type on a global ``stack of types'' without opening a
1028 \TeX\ scope. The is useful when you temporarily wish to change the type
1029 (for instance, by appending something to it), but you cannot create a new
1030 scope.
1031 \end{command}
1032
1033 \begin{command}{\pgfsys@pop@type}
1034 Restores the most recently pushed type.
1035 \end{command}
1036
1037 \begin{command}{\pgfsys@begin@idscope}
1038 Starts a (graphics) scope whose sole purpose is to assign it an
1039 id-type-pair so that it can be referenced later. Note that this command
1040 does not always produce a graphics scope: If no id is currently in use or
1041 if the id-type-pair has already been used, a graphic scope may or may not
1042 be created as defined by the driver (but always a \TeX\ scope). This allows
1043 drivers to minimize the number of graphic scopes created.
1044
1045 When an id scope is created, any code that has been ``attached'' to it
1046 using |\pgfsys@attach@to@id| gets executed, see that command.
1047
1048 Note that |\pgfsys@beginscope| does not use the current id-type-pair. You
1049 need to call this command to attach an id to a group.
1050 \end{command}
1051
1052 \begin{command}{\pgfsys@end@idscope}
1053 Ends the graphics id scope started by |\pgfsys@end@idscope|. It must nest
1054 correctly with other graphic scopes and \TeX\ scopes.
1055 \end{command}
1056
1057 \begin{command}{\pgfsys@attach@to@id\marg{id}\marg{type}\marg{begin code}\marg{end code}\marg{setup code}}
1058 Attaches codes to the \meta{id}-\meta{type}-pair, where \meta{id} must have
1059 been created using |\pgfsys@new@id|. The effect is that just before the id
1060 scope for this pair is created, the \meta{setup code} is executed, then the
1061 scope is started, then the \meta{begin code} is executed at the beginning,
1062 and, finally, \meta{end code} gets executed just before the scope ends.
1063 Multiple calls of this macro accumulated.
1064 \end{command}
1065
1066
1067 \subsection{Resource Description Framework Annotations (RDFa)}
1068 \label{section-sys-rdf}
1069
1070 With certain output formats (in particular, with \textsc{svg}) you can insert
1071 annotations into the output file following the standard set by the
1072 \emph{resource description framework} (\textsc{rdf}), please consult the
1073 literature on \textsc{rdf} for an introduction to resource descriptions and
1074 ontologies.
1075
1076 The support for \textsc{rdf} annotations works as follows in \pgfname: You use
1077 the following commands before you create an id scope (using
1078 |\pgfsys@begin@idscope|). Then the attributes set by the commands will be added
1079 as an annotation to that object. Here is an example:
1080 %
1081 \begin{codeexample}[code only]
1082 \pgfsys@rdf@resource{/fruits/apple}
1083 \pgfsys@begin@idscope
1084 ...
1085 \pgfsys@end@idscope
1086 \end{codeexample}
1087
1088 If \textsc{svg} output is produced, this results in the following code in the
1089 \textsc{svg} file:
1090 %
1091 \begin{codeexample}[code only]
1092 <g resource="/fruits/apple">
1093 ...
1094 </g>
1095 \end{codeexample}
1096
1097 Note that a call to |\pgfsys@begin@idscope| adds all the set attributes, but
1098 then clears the settings (globally). Thus, you should set all attributes more
1099 or less right before the id scope is created. For most of these command, if you
1100 call them multiple times before starting the id scope, the ``last call wins'',
1101 that is, later values overwrite earlier ones. In contrast, for the commands
1102 |\pgfsys@rdf@property|, |\pgfsys@rdf@rel|, |\pgfsys@rdf@rev|, as well as
1103 |\pgfsys@rdf@typeof|, the calls accumulate, that is, the texts passed in each
1104 call will all be added to the output, properly separated to form a list of
1105 values. Consider for instance:
1106 %
1107 \begin{codeexample}[code only]
1108 \pgfsys@rdf@resource{/fruits/apple}
1109 \pgfsys@rdf@resource{/fruits/watermelon}
1110 \pgfsys@rdf@property{http://foo.com/props/juicy}
1111 \pgfsys@rdf@property{http://foo.com/props/green}
1112 \pgfsys@begin@idscope
1113 ...
1114 \pgfsys@end@idscope
1115 \end{codeexample}
1116
1117 In the resulting id scope, we will have:
1118 %
1119 \begin{codeexample}[code only]
1120 <g resource="/fruits/watermelon"
1121 property="http://foo.com/props/juicy http://foo.com/props/green">
1122 ...
1123 </g>
1124 \end{codeexample}
1125
1126 \begin{command}{\pgfsys@rdf@about\marg{text}}
1127 Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
1128 scope (please see the \textsc{rdf}a specification for details on the
1129 semantics of |about| in the context of the resource description framework).
1130 \end{command}
1131
1132 The following commands work the same way as the above command, except that the
1133 set attribute is different. Please see the \textsc{rdf}a specification for
1134 details on these attributes. Note that the |\pgfsys@rdf@inlist| command is the
1135 only one that takes no argument.
1136
1137 \begin{command}{\pgfsys@rdf@content\marg{text}}
1138 \end{command}
1139
1140 \begin{command}{\pgfsys@rdf@datatype\marg{text}}
1141 \end{command}
1142
1143 \begin{command}{\pgfsys@rdf@href\marg{text}}
1144 \end{command}
1145
1146 \begin{command}{\pgfsys@rdf@inlist}
1147 \end{command}
1148
1149 \begin{command}{\pgfsys@rdf@prefix\marg{text}}
1150 \end{command}
1151
1152 \begin{command}{\pgfsys@rdf@property\marg{text}}
1153 \end{command}
1154
1155 \begin{command}{\pgfsys@rdf@rel\marg{text}}
1156 \end{command}
1157
1158 \begin{command}{\pgfsys@rdf@resource\marg{text}}
1159 \end{command}
1160
1161 \begin{command}{\pgfsys@rdf@rev\marg{text}}
1162 \end{command}
1163
1164 \begin{command}{\pgfsys@rdf@src\marg{text}}
1165 \end{command}
1166
1167 \begin{command}{\pgfsys@rdf@typeof\marg{text}}
1168 \end{command}
1169
1170 \begin{command}{\pgfsys@rdf@vocab\marg{text}}
1171 \end{command}
1172
1173
1174 \subsection{Reusable Objects System Commands}
1175
1176 \begin{command}{\pgfsys@invoke\marg{literals}}
1177 This command gets protocolled literals and should insert them into the
1178 |.pdf| or |.dvi| file using an appropriate |\special|.
1179 \end{command}
1180
1181 \begin{command}{\pgfsys@defobject\marg{name}\marg{lower left}\marg{upper right}\marg{code}}
1182 Declares an object for later use. The idea is that the object can be
1183 precached in some way and then be rendered more quickly when used several
1184 times. For example, an arrow head might be defined and prerendered in this
1185 way.
1186
1187 The parameter \meta{name} is the name for later use. \meta{lower left} and
1188 \meta{upper right} are \pgfname\ points specifying a bounding box for the
1189 object. \meta{code} is the code for the object. The code should not be too
1190 fancy.
1191
1192 This command has a default implementation and need not be implemented by a
1193 driver file.
1194 \end{command}
1195
1196 \begin{command}{\pgfsys@useobject\marg{name}\marg{extra code}}
1197 Renders a previously declared object. The first parameter is the name of
1198 the object. The second parameter is extra code that should be executed
1199 right \emph{before} the object is rendered. Typically, this will be some
1200 transformation code.
1201
1202 This command has a default implementation and need not be implemented by a
1203 driver file.
1204 \end{command}
1205
1206 \begin{command}{\pgfsys@marker@declare\marg{macro}\marg{code}}
1207 Declares a \emph{marker} symbol for later use. The command is very similar
1208 to |\pgfsys@defobject|, but the use case is slightly different: The graphic
1209 object defined using the \meta{code} is stored in such a way that it can be
1210 used as an \emph{arrow tip marker symbol} in animations. The \meta{macro}
1211 is set to an identifier by which the marker can be referenced later on.
1212
1213 This command has a default implementation and need not be implemented by a
1214 driver file.
1215 \end{command}
1216
1217 \begin{command}{\pgfsys@marker@use\marg{macro}}
1218 Adds the marker object referenced by the \meta{macro} to the current
1219 output.
1220
1221 This command has a default implementation and need not be implemented by a
1222 driver file.
1223 \end{command}
1224
1225
1226 \subsection{Invisibility System Commands}
1227
1228 All drawing or stroking or text rendering between calls of the following
1229 commands should be suppressed. A similar effect can be achieved by clipping
1230 against an empty region, but the following commands do not open a graphics
1231 scope and can be opened and closed ``orthogonally'' to other scopes.
1232
1233 \begin{command}{\pgfsys@begininvisible}
1234 Between this command and the closing |\pgfsys@endinvisible| all output
1235 should be suppressed. Nothing should be drawn at all, which includes all
1236 paths, images and shadings. However, no groups (neither \TeX\ groups nor
1237 graphic state groups) should be opened by this command.
1238
1239 This command has a default implementation and need not be implemented by a
1240 driver file.
1241
1242 This command is protocolled, see Section~\ref{section-protocols}.
1243 \end{command}
1244
1245 \begin{command}{\pgfsys@endinvisible}
1246 Ends the invisibility section, unless invisibility blocks have been nested.
1247 In this case, only the ``last'' one restores visibility.
1248
1249 This command has a default implementation and need not be implemented by a
1250 driver file.
1251
1252 This command is protocolled, see Section~\ref{section-protocols}.
1253 \end{command}
1254
1255
1256 \subsection{Page Size Commands}
1257
1258 The following commands can be used to set the page size of a document in a
1259 ``portable'' way. Note, however, that many packages also (try to) set the page
1260 size.
1261
1262 These commands are typically not given inside a |{pgfpicture}|, but on the
1263 outer level of compilation.
1264
1265 \begin{command}{\pgfsys@papersize\marg{width}\marg{height}}
1266 Inserts the necessary |\special|s for the current driver into the output
1267 stream to ``locally'' change the page size. Whether such a ``local'' change
1268 is possible depends strongly on the driver. For instance, |dvips| will
1269 honor the first call to this command that is part of the shipped-out
1270 document and will ignore all other uses. In contrast, |pdftex| will use the
1271 current value of the paper size for each page and, additionally, setting
1272 the papersize is local to the current \TeX\ group.
1273 \end{command}
1274
1275 \begin{command}{\pgfsys@global@papersize\marg{width}\marg{height}}
1276 Like the previous command, only for drivers where setting the paper size
1277 parameters is a \TeX-group-local operation, |\global| is prefixed to the
1278 setting of the page sizes.
1279 \end{command}
1280
1281 \begin{command}{\pgfsys@thepageheight}
1282 This macro expands to the current page's height, provided \LaTeX\ is used,
1283 otherwise a best guess is returned (currently just |\the\vsize|).
1284 \end{command}
1285
1286 \begin{command}{\pgfsys@thepagewidth}
1287 As above.
1288 \end{command}
1289
1290
1291 \subsection{Position Tracking Commands}
1292
1293 The following commands are used to determine the position of text on a page.
1294 This is a rather complicated process in general since at the moment when the
1295 text is read by \TeX, the final position cannot be determined, yet. For
1296 example, the text might be put in a box which is later put in the headline or
1297 perhaps in the footline or perhaps even on a different page.
1298
1299 For these reasons, position tracking is typically a two-stage process. In a
1300 first stage you indicate that a certain position is of interest by
1301 \emph{marking} it. This will (depending on the details of the backend driver)
1302 cause page coordinates or this position to be written to an |.aux| file when
1303 the page is shipped. Possibly, the position might also be determined at an even
1304 later stage. Then, on a second run of \TeX, the position is read from the
1305 |.aux| file and can be used.
1306
1307 \begin{command}{\pgfsys@markposition\marg{name}}
1308 Marks a position on the page. This command should be given while normal
1309 typesetting is done such as in
1310 %
1311 \begin{codeexample}[code only]
1312 The value of $x$ is \pgfsys@markposition{here}important.
1313 \end{codeexample}
1314 %
1315 It causes the position |here| to be saved when the page is shipped out.
1316 \end{command}
1317
1318 \begin{command}{\pgfsys@getposition\marg{name}\marg{macro}}
1319 This command retrieves a position that has been marked on an earlier run of
1320 \TeX\ on the current file. The \meta{macro} must be a macro name such as
1321 |\mymacro|. It will be redefined such that it is
1322 %
1323 \begin{itemize}
1324 \item either just |\relax| or
1325 \item a |\pgfpoint...| command.
1326 \end{itemize}
1327 %
1328 The first case will happen when the position has not been marked at all or
1329 when the file is typeset for the first time, when the coordinates are not
1330 yet available.
1331
1332 In the second case, executing \meta{macro} yields the position on the page
1333 that is to be interpreted as follows: A coordinate like
1334 |\pgfpoint{2cm}{3cm}| means ``2cm to the right and 3cm up from the origin
1335 of the page''. The position of the origin of the page is not guaranteed to
1336 be at the lower left corner, it is only guaranteed that all pictures on a
1337 page use the same origin.
1338
1339 To determine the lower left corner of a page, you can call
1340 |\pgfsys@getposition| with \meta{name} set to the special name
1341 |pgfpageorigin|. By shifting all positions by the amount returned by this
1342 call you can position things absolutely on a page.
1343
1344 \example Referencing a point of the page:
1345 %
1346 \begin{codeexample}[code only]
1347 The value of $x$ is \pgfsys@markposition{here}important.
1348
1349 Lots of text.
1350
1351 \hbox{\pgfsys@markposition{myorigin}%
1352 \begin{pgfpicture}
1353 % Switch of size protocol
1354 \pgfpathmoveto{\pgfpointorigin}
1355 \pgfusepath{use as bounding box}
1356
1357 \pgfsys@getposition{here}{\hereposition}
1358 \pgfsys@getposition{myorigin}{\thispictureposition}
1359
1360 \pgftransformshift{\pgfpointscale{-1}{\thispictureposition}}
1361 \pgftransformshift{\hereposition}
1362
1363 \pgfpathcircle{\pgfpointorigin}{1cm}
1364 \pgfusepath{draw}
1365 \end{pgfpicture}}
1366 \end{codeexample}
1367 %
1368 \end{command}
1369
1370
1371 \subsection{Internal Conversion Commands}
1372
1373 The system commands take \TeX\ dimensions as input, but the dimensions that
1374 have to be inserted into \pdf\ and PostScript files need to be dimensionless
1375 values that are interpreted as multiples of $\frac{1}{72}\mathrm{in}$. For
1376 example, the \TeX\ dimension $2bp$ should be inserted as |2| into a \pdf\ file
1377 and the \TeX\ dimension $10\mathrm{pt}$ as |9.9626401|. To make this conversion
1378 easier, the following command may be useful:
1379
1380 \begin{command}{\pgf@sys@bp\marg{dimension}}
1381 Inserts how many multiples of $\frac{1}{72}\mathrm{in}$ the
1382 \meta{dimension} is into the current protocol stream (buffered).
1383
1384 \example |\pgf@sys@bp{\pgf@x}| or |\pgf@sys@bp{1cm}|.
1385 \end{command}
1386
1387 Note that this command is \emph{not} a system command that can/needs to be
1388 overwritten by a driver.
1389
1390
1391 %%% Local Variables:
1392 %%% mode: latex
1393 %%% TeX-master: "pgfmanual"
1394 %%% End: