summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
commitf07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch)
tree6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
parent007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff)
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
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.tex183
1 files changed, 183 insertions, 0 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
new file mode 100644
index 00000000000..1318c780235
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
@@ -0,0 +1,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}
+