-\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.
projects / graphviz / commitdiff