From a1c6e46a9a09848e28c8f146efdd9ace9c235ebb Mon Sep 17 00:00:00 2001 From: erg Date: Thu, 24 Aug 2006 21:27:52 +0000 Subject: [PATCH] Update libguide to reflect plug-in architecture --- doc/libguide/drivers.tex | 134 ++++++++++++++++++++++----------------- 1 file changed, 76 insertions(+), 58 deletions(-) diff --git a/doc/libguide/drivers.tex b/doc/libguide/drivers.tex index c6b808730..d3f19947c 100644 --- a/doc/libguide/drivers.tex +++ b/doc/libguide/drivers.tex @@ -1,89 +1,107 @@ -\section{Using the output drivers} -\label{sec:drivers} +\section{The \gviz\ context} +\label{sec:gvc} -If an application decides to avail itself of the code generators -in the \gviz\ libraries, the simplest way is to pass a graph -which has been laid out to the function \verb+dotneato_write+. -This will generate and write the appropriate graphics instructions. +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 +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. -The \gviz\ architecture uses a data structure {\tt GVC\_t} to -define a rendering environment or context. Among other parameters, -this specifies what output formats are created and in which files. -A single {\tt GVC\_t} value can be used with multiple graphs. -An instance of an environment can be created by a call to +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 +be called before using {\tt gvLayout()} again, even on the same graph. + +An instance of a \gvc\ can be created by a call to \begin{verbatim} extern GVC_t *gvNEWcontext(char **info, char *user); \end{verbatim} -The first argument is an array of 3 character pointers -providing version information; see Appendix~\ref{sec:info} for a +The first argument is an array of three character pointers +providing version information; see Section~\ref{sec:info} below for a description of this data. The second argument is a string giving a name for the user. If desired, the application can call the library -function {\tt username} to obtain this value. +function {\tt gvUsername()} to obtain this value. These strings +are stored in the \gvc\ and used in various messages and comments. For convenience, the \gviz\ library provides a simple way to -create an environment: +create a context: \begin{verbatim} extern GVC_t *gvContext(); \end{verbatim} -This uses the {\tt Info} created when \gviz\ was built, plus -an empty string for the user's name. +which is what we have used in the examples shown here. +This uses version information created when \gviz\ was built, plus +the value returned by {\tt gvUsername()}. -To initialize the environment, the application should -call the function \verb+dotneato_initialize+ : +One can initialize a \gvc\ to record a list of graphs, layout algorithms +and renderers. To do this, the application should +call the function {\tt gvParseArgs}: \begin{verbatim} - extern void dotneato_initialize(GVC_t* gvc, int argc, char* argv[]); + extern void gvParseArgs(GVC_t* gvc, int argc, char* argv[]); \end{verbatim} -This function takes the environment value, plus an array of strings. -It calls {\tt aginit} to initialize the \graph\ library, and then -uses the values in {\tt argv} to set the appropriate values in {\tt gvc}. -These strings should be the flags commonly accepted by the various -\gviz\ programs such as {\tt "-T"} and {\tt "-o"}. +This function takes the context value, plus an array of strings +using the same conventions as the parameters to {\tt main} function +in a C program. In particular, {\tt argc} should be the number of +values in {\tt argv}. If {\tt argv[0]} is the name of one of the +layout algorithms, this will be bound to the \gvc\ value and used +at layout time. +The remaining {\tt argv} values, if any, are interpreted exactly like +the allowed command line flags for any \gviz\ program. +Thus, {\tt "-T"} can be used to set the output type, and {\tt "-o"} +can be used to specify the output files. For example, the application can use a synthetic argument list \begin{verbatim} GVC_t* gvc = gcContext(); char* args[] = { - "command", + "dot", "-Tgif", /* gif output */ - "-oabc.gif" /* output to file abc.gif */ + "-oabc.gif" /* output to file abc.gif */ }; - dotneato_initialize (gvc, sizeof(args)/sizeof(char*), args); + gvParseArgs (gvc, sizeof(args)/sizeof(char*), args); \end{verbatim} -to specify {\tt GIF} output written to the file {\tt abc.gif}. -Another approach is to use the program's actual argument list, +to specify a dot layout in {\tt GIF} output written to the file {\tt abc.gif}. +Another approach is to use a program's actual argument list, after removing flags not handled by \gviz. -Most of the information is stored in {\tt gvc} for use later. However, -if the {\tt argv} array contains non-flag arguments, these are taken -to be input files and are stored in {\tt char* Files[]}. This is a -{\tt NULL}-terminated array of all the non-flag values. +Most of the information is stored in a \gvc\ value for use during +rendering. However, +if the {\tt argv} array contains non-flag arguments, i.e., strings +after the first not beginning with {\tt "-"}, these are taken +to be input files defining a stream of graphs to be drawn. +These graphs can be accessed by calls to {\tt gvNextInputGraph}. + +Once the \gvc\ has been initialized this way, the application can +call {\tt gvNextInputGraph} to get each input graph in sequence, and +then invoke {\tt gvLayoutJobs} and {\tt gvRenderJobs} +to do the specified layouts and renderings. See +Appendix~\ref{sec:dot} for a typical example of this approach. + +We note that {\tt gvLayout} basically attaches the graph +and layout algorithm to the \gvc, as would be done by +{\tt gvParseArgs}, and then invokes {\tt gvLayoutJobs}. A similar +remark holds for {\tt gvRender} and {\tt gvRenderJobs}. + +\subsection{Application-specific data} +\label{sec:info} -Sometime before calling \verb+dotneato_write+, the application -needs to bind the environment and graph together. For this, it uses -the function: +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 +the application providing an array \begin{verbatim} - extern void gvBindContext(GVC_t* gvc, Agraph_t* g); + extern char* Info[3]; \end{verbatim} - -With this setup, and after a call to a layout algorithm, the -application can generate output by calling \verb+dotneato_write+: +giving the desired version information. +The three strings should be the name of the application, the version +of the application, and a build date. For example, \dot\ might provide \begin{verbatim} - extern void dotneato_write (GVC_t *gvc); + char *Info[] = { + "dot", /* Program */ + "1.8.10", /* Version */ + "16 Dec 2006" /* Build Date */ + }; \end{verbatim} -This function relies on a variety of implicit parameters which -are used to control the concrete representation. Most of these are -specified as graph attributes. These are noted in -Tables~\ref{tab:nattr_geom}, \ref{tab:eattr_geom} and -\ref{tab:gattr_geom}. - -If an application uses \verb+dotneato_write+, -it should afterwards call \verb+dotneato_eof+. -This tells the code generator -that output is finished, so it can emit any needed trailers. -If appropriate, this can be achieved by a call to \verb+dotneato_terminate+, -which invokes \verb+dotneato_eof+ and then exits with an exit value reflecting -any errors that arose in using the \gviz\ libraries. - -The Appendices~\ref{sec:simple}, \ref{sec:dot}, and \ref{sec:demo} -show how all of these pieces fit together. -- 2.50.1