| 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} |