.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: libploticus api</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>libploticus API</h2></td>
  <td align=right>
  <small>
  <a href="../doc/Welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  <a href="../doc/Welcome.html">Welcome</a> &nbsp; &nbsp;
  <a href="../gallery/index.html">Gallery</a> &nbsp; &nbsp;
  <a href="../doc/Contents.html">Handbook</a> 
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH libploticus_API PL "21-MAY-2003   PL ploticus.sourceforge.net"

.SH libploticus
This simple C language API 
has all of the funcionality of the
.ig >>
<a href="pl.1.html">
.>>
\0pl program
.ig >>
</a>
.>>
and is similarly covered by the General Public License.
.LP
\fBlibploticus\fR is built using \fCMakefile_api\fR.
.LP
.nf
 \0 make clean
 \0 make -f Makefile_api
.fi
.LP
Applications linking to \fBlibploticus\fR may need additional libraries
such as \fCzlib\fR, but this depends on exactly how \fBlibploticus\fR was built.  
The specifics are noted in \fCMakefile_api\fR.
The externally visible symbols in \fBlibploticus\fR begin with these prefixes: \fCploticus\fR,
\fCPL\fR, \fCTDH\fR, \fCDT\fR, and \fCGL\fR.
.LP
No header file is required.
.LP
All functions return 0 when successful, or a non-zero error code.
.LP
As of version 2.11 multiple sequential plot "jobs" can be performed by a single OS process.
Each plot job should begin with a \fCploticus_init()\fR call and terminate with a
\fCploticus_end()\fR call.  
.LP


.ig >>
<br><br><br>
.>>
.SH Examples
Here's a simple example (it may be found in \fC./pltestsuite/api_examp.c\fR)
.nf
 \0 main()
 \0 {
 \0 int stat;
 \0 stat = ploticus_init( "png", "hello.png" );
 \0 stat += ploticus_arg( "-scale", "0.8" );
 \0 if( stat != 0 ) { 
 \0	printf( "error in pl setup\\n" ); 
 \0     exit(1); 
 \0     }
 \0 ploticus_execline( "#proc annotate" );
 \0 ploticus_execline( "  location: 2 2" );
 \0 ploticus_execline( "  text: hello" );
 \0 ploticus_execline( "  world" );
 \0 ploticus_execline( "" );
 \0 ploticus_end();
 \0 }
.fi
.SH Multi-job example
Another included example, which invokes a series of 25+ plot jobs, is in \fC./src/api_test.c
To build:
.LP
.nf
 \0 make clean
 \0 make -f Makefile_api
 \0 make api_test -f Makefile_api
.fi
Then, go to the \fCpltestsuite\fR directory and type: \fC../src/api_test\fR

.ig >>
<br><br><br>
.>>

.SH libploticus API

.LP
\fCploticus_init( char *device, char *outfilename )\fR
.IP \0
Initialize, read your 
.ig >>
<a href="config.html">
.>>
\0ploticus config file
.ig >>
</a>
.>>
if any, and set the output \fCdevice\fR to one of 
\fCpng\fR, \fCgif\fR, \fCx11\fR, \fCsvg\fR, \fCjpeg\fR, \fCeps\fR, or \fCswf\fR.
(Not all devices may be available, depending on the build.)
\fCoutfilename\fR is the pathname of the file where the
result will be written.  
Example: 
.nf
 \0 stat = ploticus_init( "png", "bargraph.png" );
 \0 if( stat != 0 ) \fIerror\fR
.fi

.ig >>
<br><br><br>
.>>

.LP
\fCploticus_arg( name, value )\fR
.IP \0
Specify a 
.ig >>
<a href="pl.1.html#options">
.>>
\0pl command line argument.
.ig >>
</a>
.>>
\fCname\fR specifies the argument name and \fCvalue\fR an argument value.
If there is no argument value, \fCvalue\fR should be passed as \fC""\fR.
All arguments are supported except \fC-f\fR, \fC-prefab\fR, and \fC-ver\fR.
If needed, this function should be called after \fCploticus_init()\fR
but before any other ploticus function.
It may be called as many times as necessary.
Example: 
.nf
  \0 stat = ploticus_arg( "-debug", "" );
  \0 stat += ploticus_arg( "-diagfile", "stdout" );
  \0 stat += ploticus_arg( "-scale", "0.8" );
  \0 if( stat != 0 ) \fIerror\fR
.fi

.ig >>
<br><br>
.>>

.LP
\fCploticus_begin( )\fR
.IP \0
This function is no longer necessary.  Old code that uses it will still be OK.
.ig >>
<small>
.>>
.IP
Perform further initializations that take into account command line arguments.
This must be used after any calls to \fCploticus_arg()\fR and before any other
ploticus functions.
.br
Example: \fCploticus_begin();\fR
.ig >>
</small>
.>>

.ig >>
<br><br><br>
.>>

.LP
\fCploticus_execline( char *line )\fR
.IP \0
Interpret one "raw" ploticus script line.  \fCploticus_execline()\fR is generally 
called multiple times, and allows ploticus scripts to be generated programatically.
"Raw" ploticus script lines may contain no @variable references, and
the only directives supported are \fC #proc\fR, \fC #procdef\fR, \fC #endproc\fR, 
\fC #clone\fR and \fC #saveas\fR.
Lines may be terminated with a newline character, but don't have to be.
Intermingling with \fCploticus_execscript()\fR is not allowed.
Example:
.nf
  \0 ploticus_execline( "#proc annotate" );
  \0 ploticus_execline( "  location: 2 2" );
  \0 ploticus_execline( "  text: hello" );
  \0 ploticus_execline( "  world" );
  \0 ploticus_execline( "" );
.fi

.ig >>
<br><br><br>
.>>

.LP
\fCploticus_execscript( char *scriptfile, int prefabflag )\fR
.IP \0
Interpret an entire ploticus script file or prefab.  \fCscriptfile\fR is the name
of the script file.  \fCprefabflag\fR is \fC1\fR, then \fCscriptfile\fR is taken to be a
.ig >>
<a href="prefabs.html">
.>>
\0ploticus prefab
.ig >>
</a>
.>>
name such as \fCvbars\fR.  
If \fCprefabflag\fR is \fC0\fR, then \fCscriptfile\fR should be a pathname.
Intermingling with \fCploticus_execline()\fR is not allowed.
.br
Example: \fCstat = ploticus_execscript( "vbars", 1 );\fR
.br
Example: \fCstat = ploticus_execscript( "/home/steve/plfiles/myscript.pl", 0 );\fR

.ig >>
<br><br><br>
.>>

.LP
\fCploticus_end()\fR
.IP \0
Finish up the graphic result, write it to the output file, and free up allocated memory.

.ig >>
<br><br><br>
.>>
.SH These functions are also available:


.LP
\fCploticus_getvar( char *name, char *value )\fR
.IP \0
Get the contents of ploticus variable \fCname\fR.
Result is copied into \fCvalue\fR.
.br
Example: \fCstat = ploticus_getvar( "XFINAL", xf );\fR

.ig >>
<br><br><br>
.>>
.LP
\fCploticus_setvar( char *name, char *value )\fR
.IP \0
Set ploticus variable \fCname\fR to \fCvalue\fR.

.ig >>
<br><br><br>
.>>
.LP
\fCgdImagePtr PLGG_getimg( int *width, int *height )\fR
.IP \0
Returns a pointer to the working GD image, for situations
where the host application wants to directly issue gd drawing calls.
The \fCwidth\fR and \fCheight\fR of the working image (in pixels)
are also provided.  Note that the result image is generally cropped
based on the extent of ploticus drawing actions, before being written out.
Only valid in applications built with GD,
when ploticus was initialized with one of the GD image devices
(eg. \fCpng\fR or \fCjpeg\fR).

.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/Welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
.>>
