diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex | 202 |
1 files changed, 92 insertions, 110 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex index 63d6ebeacf7..72dc66db700 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex @@ -10,54 +10,51 @@ \section{Design Principles} -This section describes the basic layer of \pgfname. This layer is -built 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. +This section describes the basic layer of \pgfname. This layer is built 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 modules. -\item Consistently named \TeX\ macros for all graphics commands. -\item Path-centered description of graphics. -\item Coordinate transformation system. + \item Structuring into a core and modules. + \item Consistently named \TeX\ macros for all graphics commands. + \item Path-centered description of graphics. + \item Coordinate transformation system. \end{enumerate} - \subsection{Core and Modules} -The basic layer consists of a \emph{core package}, called |pgfcore|, -which provides the most basic commands, and several -\emph{modules} like commands for plotting (in the |plot| module). -Modules are loaded using the |\usepgfmodule| command. - -If you say |\usepackage{pgf}| or |\input pgf.tex| or -|\usemodule[pgf]|, the |plot| and |shapes| modules are preloaded (as -well as the core and the system layer). +The basic layer consists of a \emph{core package}, called |pgfcore|, which +provides the most basic commands, and several \emph{modules} like commands for +plotting (in the |plot| module). Modules are loaded using the |\usepgfmodule| +command. +If you say |\usepackage{pgf}| or |\input pgf.tex| or |\usemodule[pgf]|, the +|plot| and |shapes| modules are preloaded (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. - +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} @@ -71,94 +68,79 @@ move there. \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|. -\item - All commands having to do with matrices start with |\pgfmatrix|. + \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|. + \item All commands having to do with matrices start with |\pgfmatrix|. \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. +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): +\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} + \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} - |