% Copyright 2018 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 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.
\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).


\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|.
    \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.


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