| 1 |
% Copyright 2010-2019 by Renée Ahrens |
| 2 |
% Copyright 2010-2019 by Olof Frahm |
| 3 |
% Copyright 2010-2019 by Jens Kluttig |
| 4 |
% Copyright 2010-2019 by Matthias Schulz |
| 5 |
% Copyright 2010-2019 by Stephan Schuster |
| 6 |
% Copyright 2019 by Jannis Pohlmann |
| 7 |
% Copyright 2019 by Till Tantau |
| 8 |
% |
| 9 |
% This file may be distributed and/or modified |
| 10 |
% |
| 11 |
% 1. under the LaTeX Project Public License and/or |
| 12 |
% 2. under the GNU Free Documentation License. |
| 13 |
% |
| 14 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 15 |
|
| 16 |
|
| 17 |
\section{The Binding Layer} |
| 18 |
\label{section-gd-binding-layer} |
| 19 |
|
| 20 |
\ifluatex |
| 21 |
\else |
| 22 |
This section of the manual can only be typeset using Lua\TeX. |
| 23 |
\expandafter\endinput |
| 24 |
\fi |
| 25 |
|
| 26 |
|
| 27 |
\subsection{Overview} |
| 28 |
|
| 29 |
This section explains how the \emph{binding} of the graph drawing system to a |
| 30 |
particular display layer works. Let me stress that all of this is important |
| 31 |
only for readers who |
| 32 |
% |
| 33 |
\begin{itemize} |
| 34 |
\item either wish to write new display system (see |
| 35 |
Section~\ref{section-gd-display-layer}) |
| 36 |
\item or wish to know more about how the graph drawing system works on the |
| 37 |
pure \pgfname\ layer (this is were the binding occurs). |
| 38 |
\end{itemize} |
| 39 |
|
| 40 |
\emph{Bindings} are used to encapsulate the details of the communication |
| 41 |
between the graph drawing system and a display system (see |
| 42 |
Section~\ref{section-gd-display-layer} for an introduction to display systems). |
| 43 |
|
| 44 |
Consider a display system that communicates with the graph drawing system. At |
| 45 |
some point, the display system would like to run an algorithm to lay out a |
| 46 |
graph. To achieve this, it will call different functions from the class |
| 47 |
|InterfaceToDisplay| and the effect of this is that a representation of the |
| 48 |
to-be-drawn graph is constructed internally and that the appropriate algorithms |
| 49 |
are run. All of this is in some sense independent of the actual display system, |
| 50 |
the class |InterfaceToDisplay| offers the same standard interface to all |
| 51 |
display systems. |
| 52 |
|
| 53 |
At some point, however, the graph drawing system may need to ``talk back'' to |
| 54 |
the display system. For instance, once the graph has been laid out, to trigger |
| 55 |
the actual rendering of the graph, the graph drawing system must ``tell'' the |
| 56 |
display layer where the vertices lie. For some display systems this is easy: if |
| 57 |
the display system itself is written in Lua, it could just access the syntactic |
| 58 |
digraph directly. However, for systems like \tikzname\ or systems written in |
| 59 |
another language, the graph drawing system needs a set of functions that it can |
| 60 |
call that will tell the display system what is going on. This is were bindings |
| 61 |
come in. |
| 62 |
|
| 63 |
The class |Binding| is an interface that defines numerous methods that will be |
| 64 |
called by the graph drawing system in different situations (see the |
| 65 |
documentation below for details). For instance, there is a function |
| 66 |
|renderVertex| that is called by the graph drawing system whenever a vertex |
| 67 |
should be rendered by the display system. The class is really just an interface |
| 68 |
in the sense of object-oriented programming. For each display system you need |
| 69 |
to create a subclass of |Binding| like |BindingToPGF| or |BindingToASCII| that |
| 70 |
implement the methods declared by |Binding|. The number of methods that need to |
| 71 |
be implemented depends on the display system. |
| 72 |
|
| 73 |
In the following, you will find the documentation of the |Binding| class in |
| 74 |
Section~\ref{section-gd-binding-doc}. Following this, we first have a quick |
| 75 |
look at how the |BindingToPGF| works and then go over a simple example of a |
| 76 |
binding to a more or less imaginary display system. This example should help |
| 77 |
readers interested in implementing their own bindings. |
| 78 |
|
| 79 |
|
| 80 |
\subsection{The Binding Class and the Interface Core} |
| 81 |
\label{section-gd-binding-doc} |
| 82 |
|
| 83 |
\includeluadocumentationof{pgf.gd.bindings.Binding} |
| 84 |
\includeluadocumentationof{pgf.gd.interface.InterfaceCore} |
| 85 |
|
| 86 |
|
| 87 |
\subsection{The Binding To PGF} |
| 88 |
|
| 89 |
\includeluadocumentationof{pgf.gd.bindings.BindingToPGF} |
| 90 |
|
| 91 |
|
| 92 |
\subsection{An Example Binding Class} |
| 93 |
|
| 94 |
\label{section-gd-binding-layer-example} |
| 95 |
|
| 96 |
In the present section a complete binding is presented to an imaginary |
| 97 |
``\textsc{ascii} art display system'' is presented. The idea is that this |
| 98 |
display system will depict graphs using just normal letters and spaces so that, |
| 99 |
when the text is typeset in a monospace font, a visualization of the graph |
| 100 |
results. For instance: |
| 101 |
|
| 102 |
\bigskip |
| 103 |
\noindent |
| 104 |
\begin{minipage}[t]{.5\textwidth} |
| 105 |
\emph{Graph rendered by |BindingToPGF|:} |
| 106 |
\medskip |
| 107 |
|
| 108 |
\tikz [anchor=base]\graph [layered layout,level distance=2.35cm,sibling |
| 109 |
distance=1.2cm,edges={rounded corners,>={Stealth[round,sep]}}] { |
| 110 |
Alice; |
| 111 |
Bob; |
| 112 |
Charly; |
| 113 |
Dave; |
| 114 |
Eve; |
| 115 |
Fritz; |
| 116 |
George; |
| 117 |
Alice -> Bob; |
| 118 |
Alice -> Charly; |
| 119 |
Charly -> Dave; |
| 120 |
Bob -> Dave; |
| 121 |
Dave -> Eve; |
| 122 |
Eve -> Fritz; |
| 123 |
Fritz -> Alice; |
| 124 |
George -> Eve; |
| 125 |
George -> Fritz; |
| 126 |
Alice -> George; |
| 127 |
}; |
| 128 |
\end{minipage}% |
| 129 |
\begin{minipage}[t]{.49\textwidth} |
| 130 |
\emph{Graph rendered by |BindingToASCII|:} |
| 131 |
|
| 132 |
\begin{verbatim} |
| 133 |
Alice |
| 134 |
....... |
| 135 |
.. . . . |
| 136 |
... . . . |
| 137 |
... .. . .. |
| 138 |
.. . . . |
| 139 |
Charly Bob . . |
| 140 |
.. . . . |
| 141 |
. . . . |
| 142 |
. . . . |
| 143 |
.. . . . |
| 144 |
.. . . |
| 145 |
Dave George . |
| 146 |
.. . ... . |
| 147 |
. . .. . |
| 148 |
. . ... |
| 149 |
.. . . ... |
| 150 |
.. . .. |
| 151 |
Eve . .. |
| 152 |
.. . .. |
| 153 |
. . . |
| 154 |
. . . |
| 155 |
.. . .. |
| 156 |
... |
| 157 |
Fritz |
| 158 |
\end{verbatim} |
| 159 |
\end{minipage} |
| 160 |
\bigskip |
| 161 |
|
| 162 |
The binding will reside in a file |BindingToASCII.lua|, whose contents is |
| 163 |
detailed below, and which is used by calling the |bind| function of |
| 164 |
|InterfaceToDisplay|, see its documentation for details. |
| 165 |
|
| 166 |
The binding's code starts with some initializations: |
| 167 |
% |
| 168 |
\begin{codeexample}[code only] |
| 169 |
-- File BindingToASCII.lua |
| 170 |
|
| 171 |
-- Imports |
| 172 |
local lib = require "pgf.gd.lib" |
| 173 |
|
| 174 |
-- Subclass the Binding class: |
| 175 |
local BindingToASCII = lib.class { base_class = require "pgf.gd.bindings.Binding" } |
| 176 |
\end{codeexample} |
| 177 |
|
| 178 |
The interesting code is the code for ``rendering'' a graph. The graph drawing |
| 179 |
system will invoke the binding's methods |renderStart| and |renderStop| to |
| 180 |
signal that the graph drawing algorithms have finished and that the vertices |
| 181 |
and edges can now be drawn. |
| 182 |
|
| 183 |
In our \textsc{ascii} renderer, we use a two-dimensional field holding |
| 184 |
characters that severs as the ``drawing canvas''. At the beginning of the |
| 185 |
rendering, we initialize it with blanks: |
| 186 |
% |
| 187 |
\begin{codeexample}[code only] |
| 188 |
local canvas |
| 189 |
|
| 190 |
function BindingToASCII:renderStart() |
| 191 |
canvas = {} |
| 192 |
-- Clear the canvas |
| 193 |
for x=-30,30 do |
| 194 |
canvas [x] = {} |
| 195 |
for y=-30,30 do |
| 196 |
canvas[x][y] = ' ' |
| 197 |
end |
| 198 |
end |
| 199 |
end |
| 200 |
\end{codeexample} |
| 201 |
|
| 202 |
In order to ``render'' a vertex, the graph drawing system will call the |
| 203 |
|renderVertex| method. The binding of \tikzname\ does a lot of complicated |
| 204 |
things in this method to retrieve the underlying node's box from internal table |
| 205 |
and to somehow reinstall the box in \TeX's output stream; for our |
| 206 |
\textsc{ascii} binding things are much simpler: We simply put the vertex's name |
| 207 |
at the canvas position corresponding to the vertex's |pos| coordinate. Note |
| 208 |
that this simple version of an \textsc{ascii} renderer does not try to scale |
| 209 |
things; thus, array out of bounds might occur here. |
| 210 |
% |
| 211 |
\begin{codeexample}[code only] |
| 212 |
function BindingToASCII:renderVertex(v) |
| 213 |
canvas [math.floor(v.pos.x)][math.floor(v.pos.y)] = v.name |
| 214 |
end |
| 215 |
\end{codeexample} |
| 216 |
|
| 217 |
The rendering of edges is a more complicated process. Given two vertices, we |
| 218 |
put dots at the canvas positions between them; provided there are no vertices |
| 219 |
(so edges are behind the nodes). Here is the essential part of the code (for |
| 220 |
the complete code, have a look at |pgf/gd/examples/BindingToASCII.lua|): |
| 221 |
% |
| 222 |
\begin{codeexample}[code only] |
| 223 |
function BindingToASCII:renderEdge(e) |
| 224 |
local function connect (p,q) |
| 225 |
-- Connect the points p and q |
| 226 |
local x1, y1, x2, y2 = math.floor(p.x+0.5), math.floor(p.y+0.5), math.floor(q.x+0.5), math.floor(q.y+0.5) |
| 227 |
... |
| 228 |
local delta_x = x2-x1 |
| 229 |
local delta_y = y2-y1 |
| 230 |
... |
| 231 |
local slope = delta_y/delta_x |
| 232 |
for i=x1,x2 do |
| 233 |
local x,y = i, math.floor(y1 + (i-x1)*slope + 0.5) |
| 234 |
|
| 235 |
if canvas[x][y] == " " then |
| 236 |
canvas[x][y] = '.' |
| 237 |
end |
| 238 |
end |
| 239 |
... |
| 240 |
end |
| 241 |
|
| 242 |
-- Iterate over all points on the path from tail to head: |
| 243 |
local p = e.tail.pos |
| 244 |
for i=1,#e.path do |
| 245 |
connect(p, e.tail.pos + e.path[i]) |
| 246 |
p = e.tail.pos + e.path[i] |
| 247 |
end |
| 248 |
connect(p, e.head.pos) |
| 249 |
end |
| 250 |
\end{codeexample} |
| 251 |
|
| 252 |
The methods |renderVertex| and |renderEdge| will be called once for each vertex |
| 253 |
and edge of the to-be-rendered graph. At the end, the |renderStop| method is |
| 254 |
called. In our case, this method will output the canvas using |print|. A slight |
| 255 |
complication arises when node names are longer than just one character. In this |
| 256 |
case, the following code ``centers'' them on their coordinate and makes sure |
| 257 |
that they do not get overwritten by the dots forming edges: |
| 258 |
% |
| 259 |
\begin{codeexample}[code only] |
| 260 |
function BindingToASCII:renderStop() |
| 261 |
for y=10,-30,-1 do |
| 262 |
local t = {} |
| 263 |
for x=-30,30 do |
| 264 |
local s = canvas[x][y] |
| 265 |
for i=1,#s do |
| 266 |
pos = x+30+i-math.floor(#s/2) |
| 267 |
if not t[pos] or t[pos] == " " or t[pos] == "." then |
| 268 |
t[pos] = string.sub(s,i,i) |
| 269 |
end |
| 270 |
end |
| 271 |
end |
| 272 |
print(table.concat(t)) |
| 273 |
end |
| 274 |
end |
| 275 |
\end{codeexample} |
| 276 |
|
| 277 |
At the end, we need to return the created object: |
| 278 |
% |
| 279 |
\begin{codeexample}[code only] |
| 280 |
return BindingToASCII |
| 281 |
\end{codeexample} |