% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\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
  |pgfbasepatterns| provides commands for declaring and using tiling
  patterns. 
\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}

