1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
% 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{Design Principles}
This section describes the basic layer of \pgfname. This layer is
build on top of the system layer. Whereas the system layer just
provides the absolute minimum for drawing graphics, the basic
layer provides numerous commands that make it possible to create
sophisticated graphics easily and also quickly.
The basic layer does not provide a convenient syntax for describing
graphics, which is left to frontends like \tikzname. For this reason, the
basic layer is typically used only by ``other programs.'' For example,
the \textsc{beamer} package uses the basic layer extensively, but does
not need a convenient input syntax. Rather, speed and flexibility are
needed when \textsc{beamer} creates graphics.
The following basic design principles underlie the basic layer:
\begin{enumerate}
\item Structuring into a core and several optional packages.
\item Consistently named \TeX\ macros for all graphics commands.
\item Path-centered description of graphics.
\item Coordinate transformation system.
\end{enumerate}
\subsection{Core and Optional Packages}
The basic layer consists of a \emph{core package}, called |pgfcore|,
which provides the most basic commands, and several optional package
like |pgfbaseshade| that offer more special-purpose commands.
You can include the core by saying |\usepackage{pgfcore}| or, as a
plain \TeX\ user, |\input pgfcore.tex|.
The following optional packages are provided by the basic layer:
\begin{itemize}
\item
|pgfbaseplot| provides commands for plotting functions.
\item
|pgfbaseshapes| provides commands for drawing shapes and
nodes.
\item
|pgfbaseimage| provides commands for including external
images. The |graphicx| package does a much better job at this than
the |pgfbaseimage| package does, so you should normally use
|\includegraphics| and not |\pgfimage|. However, in some situations
(like when masking is needed or when plain \TeX\ is used) this
package is needed.
\item
|pgfbaselayers| provides commands for creating layered
graphics. Using layers you can later on say that a certain path
should be behind a path that was specified earlier.
\item
|pgfbasesnakes| provides commands for adding snaked lines to the
path. Such lines are not straight but rather wind in some specific
fashion.
\end{itemize}
If you say |\usepackage{pgf}| or |\input pgf.tex|, all of the optional
packages are loaded (as well as the core and the system layer).
\subsection{Communicating with the Basic Layer via Macros}
In order to ``communicate'' with the basic layer you use long
sequences of commands that start with |\pgf|. You are only allowed to
give these commands inside a |{pgfpicture}| environment. (Note that
|{tikzpicture}| opens a |{pgfpicture}| internally, so you can freely
mix \pgfname\ commands and \tikzname\ commands inside a
|{tikzpicture}|.) It is possible to ``do other things'' between the
commands. For example, you might use one command to move to a certain
point, then have a complicated computation of the next point, and then
move there.
\begin{codeexample}[]
\newdimen\myypos
\begin{pgfpicture}
\pgfpathmoveto{\pgfpoint{0cm}{\myypos}}
\pgfpathlineto{\pgfpoint{1cm}{\myypos}}
\advance \myypos by 1cm
\pgfpathlineto{\pgfpoint{1cm}{\myypos}}
\pgfpathclose
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
The following naming conventions are used in the basic layer:
\begin{enumerate}
\item
All commands and environments start with |pgf|.
\item
All commands that specify a point (a coordinate) start with |\pgfpoint|.
\item
All commands that extend the current path start with |\pgfpath|.
\item
All commands that set/change a graphics parameter start with |\pgfset|.
\item
All commands that use a previously declared object (like a path,
image or shading) start with |\pgfuse|.
\item
All commands having to do with coordinate transformations start with
|\pgftransform|.
\item
All commands having to do with arrow tips start with |\pgfarrows|.
\item
All commands for ``quickly'' extending or drawing a path start with
|\pgfpathq| or |\pgfusepathq|.
\end{enumerate}
\subsection{Path-Centered Approach}
In \pgfname\ the most important entity is the \emph{path}. All
graphics are composed of numerous paths that can be stroked,
filled, shaded, or clipped against. Paths can be closed or open, they
can self-intersect and consist of unconnected parts.
Paths are first \emph{constructed} and then \emph{used}. In order to
construct a path, you can use commands starting with |\pgfpath|. Each
time such a command is called, the current path is extended in some
way.
Once a path has been completely constructed, you can use it using the
command |\pgfusepath|. Depending on the parameters given to this
command, the path will be stroked (drawn) or filled or subsequent
drawings will be clipped against this path.
\subsection{Coordinate Versus Canvas Transformations}
\label{section-design-transformations}
\pgfname\ provides two transformation systems: \pgfname's own
\emph{coordinate} transformation matrix and \pdf's or PostScript's
\emph{canvas} transformation matrix. These two systems are quite
different. Whereas a scaling by a factor of, say, $2$ of the canvas
causes \emph{everything} to be scaled by this factor (including
the thickness of lines and text), a scaling of two in the coordinate
system causes only the \emph{coordinates} to be scaled, but not the
line width nor text.
By default, all transformations only apply to the coordinate
transformation system. However, using the command |\pgflowlevel|
it is possible to apply a transformation to the canvas.
Coordinate transformations are often preferable over canvas
transformations. Text and lines that are transformed using canvas
transformations suffer from differing sizes and lines whose thickness
differs depending on whether the line is horizontal or vertical. To
appreciate the difference, consider the following two ``circles'' both
of which have been scaled in the $x$-direction by a factor of $3$ and
by a factor of $0.5$ in the $y$-direction. The left circle uses a
canvas transformation, the right uses \pgfname's coordinate
transformation (some viewers will render the left graphic incorrectly
since they do no apply the low-level transformation the way they
should):
\begin{tikzpicture}[line width=5pt]
\useasboundingbox (-1.75,-1) rectangle (14,1);
\begin{scope}
\pgflowlevel{\pgftransformxscale{3}}
\pgflowlevel{\pgftransformyscale{.5}}
\draw (0,0) circle (0.5cm);
\draw (.55cm,0pt) node[right] {canvas};
\end{scope}
\begin{scope}[xshift=9cm,xscale=3,yscale=.5]
\draw (0,0) circle (0.5cm);
\draw (.55cm,0pt) node[right] {coordinate};
\end{scope}
\end{tikzpicture}
|
