From ece697fb7b79f308386e116b1613843f90db22ec Mon Sep 17 00:00:00 2001 From: erg Date: Fri, 25 Aug 2006 19:39:12 +0000 Subject: [PATCH] Integrate John's comments --- doc/libguide/drivers.tex | 15 +++++++++++---- doc/libguide/plugins.tex | 19 ++++++++++++++----- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/doc/libguide/drivers.tex b/doc/libguide/drivers.tex index d3f19947c..778be4a62 100644 --- a/doc/libguide/drivers.tex +++ b/doc/libguide/drivers.tex @@ -4,13 +4,19 @@ Up to now, we have used a \gviz\ context \gvc\ without considering its purpose. As suggested earlier, this value is used to store various layout information that is independent of a particular -graph and its attributes. In particular, it maintains lists of the +graph and its attributes. +It holds the data associated with plugins, parsed-command lines, +script engines, and anything else with a scope potentially larger +than one graph, up to the scope of the application. +In addition, it maintains lists of the available layout algorithms and renderers; it also records the most recent layout algorithm applied to a graph. It can be used to specify multiple renderings of a given graph layout into different associated files. It is also used to store various global information used during rendering. +There should be just one \gvc\ created for the entire +duration of an application. A single \gvc\ value can be used with multiple graphs, though with only one graph at a time. In addition, if {\tt gvLayout()} was invoked for a graph and \gvc, then {\tt gvFreeLayout()} should @@ -88,8 +94,9 @@ remark holds for {\tt gvRender} and {\tt gvRenderJobs}. \subsection{Application-specific data} \label{sec:info} -When possible, the code generators in the library log how an image file -was created in the output file. To do this, they rely on +It is sometimes useful to supply version information. +For example, some renderers in \gviz\ the library version used +to create the output file. To do this, they rely on the application providing an array \begin{verbatim} extern char* Info[3]; @@ -101,7 +108,7 @@ of the application, and a build date. For example, \dot\ might provide char *Info[] = { "dot", /* Program */ "1.8.10", /* Version */ - "16 Dec 2006" /* Build Date */ + "16 Dec 2006" /* Build Date */ }; \end{verbatim} diff --git a/doc/libguide/plugins.tex b/doc/libguide/plugins.tex index 488a53cb8..f966eb4e2 100644 --- a/doc/libguide/plugins.tex +++ b/doc/libguide/plugins.tex @@ -44,13 +44,14 @@ void *features; \\ The fields have the following meanings. \begin{description} \item[{\tt id}] -Unique identifier for a given plug-in within a given package and with -a given API kind. +Identifier for a given plug-in within a given package and with +a given API kind. Note that the {\tt id} need only be unique within +its plug-in package, as these packages are assumed to be independent. \item[{\tt type}] Name for a given plug-in, used during plug-in lookup. \item[{\tt quality}] An arbitrary integer used for ordering plug-ins with the same {\tt type}. -Plug-ins with smaller values will be chosen before plug-ins with larger +Plug-ins with larger values will be chosen before plug-ins with smaller values. \item[{\tt engine}] Points to the related engine structure. @@ -128,6 +129,13 @@ In our example, the ``3'' in the library's filename gives the version number. Finally, the library must be installed in the \gviz\ library directory, and {\tt dot -c} must be run to add the package to the \gviz\ configuration. +Note that both of these steps typically assume that one has installer +privileges.\footnote{ +Normally, for builds intended for local installation {\tt dot -c} is run +during {\tt make install}. +It may be necessary to run this manually if cross-compiling or otherwise +manually moving binaries to a different system. +} In the remainder of this section, we shall look at the first three types of plug-in APIs in more detail. @@ -215,13 +223,14 @@ output can contain multiple renderings \\ {\tt GVRENDER\_DOES\_TRUECOLOR} & Supports a truecolor color model \\ {\tt GVRENDER\_Y\_GOES\_DOWN} & Output coordinate system has the origin in the upper left corner \\ -{\tt GVRENDER\_X11\_EVENTS} & {\bf ASK} \\ +{\tt GVRENDER\_X11\_EVENTS} & For GUI plug-ins, defers actual rendering until +the GUI event loop invokes {\tt job->callbacks->refresh()} \\ {\tt GVRENDER\_DOES\_TRANSFORM} & Can handle transformation (scaling, translation, rotation) from universal to device coordinates. If false, the library will do the transformation before passing any coordinates to the renderer \\ {\tt GVRENDER\_DOES\_LABELS} & Wants an object's label, if any, provided -as text during rendering {\bf ASK} \\ +as text during rendering \\ {\tt GVRENDER\_DOES\_MAPS} & Supports regions to which URLs can be attached. If true, URLs are provided to the renderer, either as part of the {\tt job->obj} or via the renderer's {\tt begin\_anchor} -- 2.40.0