diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-gd-display-layer.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-gd-display-layer.tex | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-gd-display-layer.tex b/graphics/pgf/base/doc/pgfmanual-en-gd-display-layer.tex new file mode 100644 index 0000000000..c265b7f4af --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-gd-display-layer.tex @@ -0,0 +1,285 @@ +% Copyright 2010-2018 by Renée Ahrens +% Copyright 2010-2018 by Olof Frahm +% Copyright 2010-2018 by Jens Kluttig +% Copyright 2010-2018 by Matthias Schulz +% Copyright 2010-2018 by Stephan Schuster +% Copyright 2018 by Jannis Pohlmann +% 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{The Display Layer} +\label{section-gd-display-layer} + +{\noindent {\itshape{by Till Tantau}}} + +\ifluatex +\else + This section of the manual can only be typeset using Lua\TeX. + \expandafter\endinput +\fi + + +\begin{quote} + \itshape You do not need to read this section in order to write new graph + drawing algorithms. It is of interest only to those wishing to write + programs that wish to ``use'' the graph drawing system in a similar way + that \tikzname\ does for laying out graphs that are generated and then + passed down from the program to the graph drawing system. +\end{quote} + + +\subsection{Introduction: The Interplay of the Different Layers} + +The job of the graph drawing system is to run graph drawing algorithms on +graphs. Since graph drawing is useful in many different contexts, not only in +the context of \tikzname\ for which the present system was originally +developed, the graph drawing system was designed in such a way that it can be +used independently of \tikzname. To achieve this, the \emph{display layer} +provides an interface via which an arbitrary program (\tikzname, a graph +editor, a command line interface, etc.) ``talk'' to the graph drawing system. + +To better understand how this works, let us consider the following setup: +% +\begin{itemize} + \item A program would like to communicate with the graph drawing system. It + is written in Java and its job is to analyse social networks. This + software would like to use graph drawing to produce drawings of some + ``social graphs'' arising from its analyses. This software will be + called ``the display system'' in the following. + \item There are two algorithms that the display system would like to apply + to the graphs its produces. Let us call these algorithms ``A'' and + ``B''. However, the display system would also, ideally, wish to make it + possible that its user chooses other algorithms ``C'' that are not + necessarily part of its binary. + \item The display system has internally generated a ``social graph'' that + it would now like to draw. +\end{itemize} + +For this setup, the communication between the different layers of the graph +drawing system is as follows: +% +\begin{enumerate} + \item The display system, being written in Java, must embed Lua to use the + graph drawing system. + \item The display system must initialize the graph drawing system. For + this, it must use |require| on the file |InterfaceToDisplay|, which, as + the name suggests, contains the interface between the display system + and the graph drawing system. + + It must also create a so-called ``binding'' between the graph drawing + system and the display layer. See + Section~\ref{section-gd-binding-layer} for more information on + bindings. + \item The display system now needs to load the declarations of the + algorithms A and B. For this, it just needs to apply |require| to the + files in which the algorithms reside. This will cause the |declare| + function to be called. This function is declared by + |InterfaceToAlgorithms| and allows files to declare that certain + algorithms and options are now available. + + Once this is done, the graph drawing system is fully initialized and + can be used. + \item Later on, the display system wishes to lay out a social graph. Note + that this is known as ``drawing the graph'' in the graph drawing + community, even though this only means the coordinates are computed for + the nodes of the graph. The actual ``rendering'' of the graph on the + display is the job of the display system (hence the name ``display + layer''). + \item To start the layout process, the display system calls the function + |beginGraphDrawingScope| of the class |InterfaceToDisplay|. + \item Next, for each vertex the function |createVertex| of the interface + class must be called and similarly for each edge. These calls will + cause an internal model of the graph to be created on the algorithm + layer. Options that are attached to nodes and edges are also + communicated to the graph drawing system through function calls like + |pushOption|. + \item When the graph is fully specified, the method + |runGraphDrawingAlgorithm| must be called, which is once more a method + of the interface class. This function will internally discern which + algorithms have been chosen (via options) and invoke the code of the + appropriate algorithms. + \item Next, the function |renderGraph| must be called. Its job is to + ``communicate back'' which coordinates have been computed. It will use + the binding for this communication, see + Section~\ref{section-gd-binding-layer}. + \item Finally, by calling |endGraphDrawingScope|, the resources needed for + the layout process for the social graph are freed once more. +\end{enumerate} + +A few points may be noteworthy: +% +\begin{itemize} + \item The whole communication between the display system and the graph + drawing system goes through the interface class via function calls. + This makes it easy to communicate with display system whose internal + model of graphs is quite different from the one used in Lua (as is + certainly the case for \TeX, but also the ``social graph'' mentioned + above need not even exist as a separate entity inside the display + system). + + \emph{The display system should only rely on the interface class. All + communication has to go through this class, the display system may not + access the internals of the internally constructed graphs directly.} + \item New algorithms can be loaded at runtime, as long as the |require| + method is supported. + \item The display system can also use the interface class to query which + algorithms and which options are available in principle (and display + this information to the user). The display system can even get access + the documentation of the options at runtime since the documentation is + stored in fields of the declared options. +\end{itemize} + +In the following, we first present a simple display system other than +\tikzname. The remainder of the section then encompasses a documentation of the +different functions of the class |InterfaceToDisplay|. + + +\subsection{An Example Display System} + +In the following, we present the code of a very simple display system written +in Lua (another such display system is \tikzname\ itself, but the minimal +system will allow us to focus on what is really needed). You will also find it +in |pgf.gd.examples.ASCIIDisplayer|. + +The job of this display system is to parse a string that encodes a graph and to +call the appropriate functions of |InterfaceToDisplay| to lay out the graph. +The actual calls for rendering the graph are part of the binding, which is +documented in Section~\ref{section-gd-binding-layer-example}. + +The syntax of the to-be-laid-out graph is a reduced version of \tikzname's +|graph| syntax: The string must start with |graph[|\meta{algorithm's name}|]{| +and end with |}|. Between the braces, all lines must either be of the form +\meta{node name}|;| or \meta{name 1}|->|\meta{name 2}|;| with optional spaces +around the node names. + +Let us now have a look at what we must do to use the graph drawing system. +First, we load some libraries and initialize the binding (see +Section~\ref{section-gd-binding-layer-example} for details on the binding; we +can ignore it for now). +% +\begin{codeexample}[code only] +local InterfaceToDisplay = require "pgf.gd.interface.InterfaceToDisplay" +InterfaceToDisplay.bind(require "pgf.gd.examples.BindingToASCII") + +-- Load two libraries that define graph drawing algorithms. We can do this only *after* the binding +-- has been created since they call the declare function internally. +require "pgf.gd.layered.library" +require "pgf.gd.force.library" +\end{codeexample} + +Now comes some preparation code that starts a graph drawing scope and sets up +the algorithm to the string provided between the square \todosp{should +\texttt{.pushPhase} be \texttt{.pushOption}? (bug \#396)} brackets: + +% +\begin{codeexample}[code only] +local algorithm = io.read():match("%s*graph%s*%[(.-)%]") + +InterfaceToDisplay.pushPhase(algorithm, "main", 1) +InterfaceToDisplay.pushOption("level distance", 6, 2) +InterfaceToDisplay.pushOption("sibling distance", 8, 3) +InterfaceToDisplay.beginGraphDrawingScope(3) +InterfaceToDisplay.pushLayout(4) +\end{codeexample} + +The numbers |1| to |4| are the positions on the options stack at which the +options should be placed. See the description of |pushOption| for more details. + +We are now ready to create the vertices and edges via a very simple parser: +% +\begin{codeexample}[code only] +for line in io.lines() do + if line:match("}") then + break + elseif line:find("-") then + local n1, dir, n2 = string.match(line, "^%s*(.-)%s*(-.)%s*(.-)%s*;") + InterfaceToDisplay.createEdge(n1, n2, dir, 4) + else + local n1 = string.match(line, "^%s*(.-)%s*;") + InterfaceToDisplay.createVertex(n1, "rectangle", nil, 4) + end +end +\end{codeexample} + +The graph is now completely constructed inside the graph drawing system. We can +now invoke the algorithms: +% +\begin{codeexample}[code only] +InterfaceToDisplay.runGraphDrawingAlgorithm() +InterfaceToDisplay.renderGraph() +InterfaceToDisplay.endGraphDrawingScope() +\end{codeexample} + +We can now run the resulting file using the Lua interpreter. If we provide the +input shown on the left, we get the output shown on the right: + +\bigskip +\noindent +\begin{minipage}[t]{.5\textwidth} +\emph{Input given to ASCIIDisplayer:} + +\begin{verbatim} +graph [layered layout] { + Alice; + Bob; + Charly; + Dave; + Eve; + Fritz; + George; + Alice -> Bob; + Alice -> Charly; + Charly -> Dave; + Bob -> Dave; + Dave -> Eve; + Eve -> Fritz; + Fritz -> Alice; + George -> Eve; + George -> Fritz; + Alice -> George; +} +\end{verbatim} +\end{minipage}% +\begin{minipage}[t]{.49\textwidth} +\emph{Output produced by ASCIIDisplayer:} + +\begin{verbatim} + Alice + ....... + .. . . . + ... . . . + ... .. . .. + .. . . . + Charly Bob . . + .. . . . + . . . . + . . . . + .. . . . + .. . . + Dave George . + .. . ... . + . . .. . + . . ... + .. . . ... + .. . .. + Eve . .. + .. . .. + . . . + . . . + .. . .. + ... + Fritz +\end{verbatim} +\end{minipage} + + +\subsection{The Interface to Display Systems} + +\includeluadocumentationof{pgf.gd.interface.InterfaceToDisplay} |