Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-design.tex

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