<!-- -*-  mode: nxml -*- -->
<!--
    api-c.xml: "The Specialized C API for PLplot" chapter

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999, 2000, 2001, 2002, 2003  Alan W. Irwin
Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004  Rafael Laboissiere
Copyright (C) 2003  Joao Cardoso
Copyright (C) 2008  Andrew Ross

Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs,
converted to HTML, PDF, PostScript, and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="API-C">
  <title>The Specialized C API for PLplot</title>

  <para>
    The purpose of this chapter is to document the PLplot C functions that are
    currently not part of the common API, 
    either because they are C/C++ specific utility 
    functions (e.g. &plAlloc2dGrid;, &plFree2dGrid;) or because they are not
    easily implemented in other languages (e.g. &plGetCursor;). Some of these 
    functions are used in the examples and may be helpful for other users of 
    plplot.
  </para>
  <para>
    This chapter also documents some of the data types and structures 
    defined by plplot and used by the functions.
  </para>

  <sect1 id="plabort" renderas="sect3">
    <title>
      <function>plabort</function>: Error abort
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plabort</function>
	  </funcdef>
	  <paramdef><parameter>message</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This routine is to be used when something goes wrong that doesn't
      require calling &plexit; but for which there is no useful recovery.
      It calls the abort handler defined via &plsabort;, does some cleanup
      and returns. The user can supply his/her own abort handler and pass it
      in via &plsabort;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>message</parameter>
	  (<literal>char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Abort message.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, f95 and python.
    </para>

    <para>
      This function is used in example 20.
    </para>
    
  </sect1>

  <sect1 id="plAlloc2dGrid" renderas="sect3">
    <title>
      <function>plAlloc2dGrid</function>: Allocate a block of memory
    for use as a 2-d grid of type PLFLT.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plAlloc2dGrid</function>
	  </funcdef>
	  <paramdef><parameter>f</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
    Allocates a block of memory for use as a 2-d grid of type
    PLFLT. The grid is a vectored 2-d C-style array and so can be accessed
    using syntax like <literal>*f[i][j]</literal>. The memory associated
    with the grid must be freed by 
    calling &plFree2dGrid; once it is no longer required.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>f</parameter>
	  (<literal>PLFLT ***</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to a PLFLT grid. On success <literal>f</literal>
	  will point to a pointer to the vectored 2-d array
	  of type PLFLT. If the allocation fails
	  <literal>f</literal> will be NULL.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  Dimensions of grid to be allocated.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, perl and tk.
    </para>

    <para>
      This function is used in examples 8, 9, 11, 14, 16, 20, 21, 22, 28, 30.
    </para>
    
  </sect1>
  
  <sect1 id="plClearOpts" renderas="sect3">
    <title>
      <function>plClearOpts</function>: Clear internal option table info 
      structure.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plClearOpts</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
      Clear the internal options table info structure. This removes any
      option added with &plMergeOpts; as well as all default entries. 
    </para>

    <para>
      This function returns 0 on success.
    </para>

    <para>
      This function is currently available in C, C++ and Ocaml.
    </para>

    <para>
      This function is not used in any examples.
    </para>
      
  </sect1>

  <sect1 id="plexit" renderas="sect3">
    <title>
      <function>plexit</function>: Error exit
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plexit</function>
	  </funcdef>
	  <paramdef><parameter>message</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This routine is called in case an error is encountered during
      execution of a PLplot routine.  It prints the error message, tries to
      release allocated resources, calls the handler provided by &plsexit;
      and then exits.  If cleanup needs to be done in the driver program
      then the user may want to supply his/her own exit handler and pass it
      in via &plsexit;.  This function should either call &plend; before
      exiting, or simply return.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>message</parameter>
	  (<literal>char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Error message.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C and ada.
    </para>

    <para> 
      This function is not used in any examples.
    </para>

  </sect1>
  
  <sect1 id="plFree2dGrid" renderas="sect3">
    <title>
        <function>plFree2dGrid</function>: Free the memory associated
	with a 2-d grid allocated using &plAlloc2dGrid;.
    </title>
    
    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plFree2dGrid</function>
	  </funcdef>
	  <paramdef><parameter>f</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
    Frees a block of memory allocated using &plAlloc2dGrid;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>f</parameter>
	  (<literal>PLFLT **</literal>, input)
	</term>
	<listitem>
	  <para>
	    PLFLT grid to be freed. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  Dimensions of grid to be freed.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, perl and tk.
    </para>

    <para>
      This function is used in examples 8, 9, 11, 14, 16, 20, 21, 22, 28, 30.
    </para>
    
  </sect1>



  <sect1 id="plGetCursor" renderas="sect3">
    <title>
      <function>plGetCursor</function>: Wait for graphics input event and translate to world coordinates.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>int
	    <function>plGetCursor</function>
	  </funcdef>
	  <paramdef><parameter>gin</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Wait for graphics input event and translate to world coordinates.
      Returns 0 if no translation to world coordinates is possible.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>gin</parameter>
	  (<literal>&PLGraphicsIn; *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to &PLGraphicsIn; structure which will contain the 
	    output. The structure is not allocated by the routine 
	    and must exist before the function is called.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function returns 1 on success and 0 if no translation to world 
      coordinates is possible.
    </para>

    <para>
      This function is currently only available with the C, C++, Ocaml, 
      Octave, Perl, Python and Ada language bindings.
    </para>

    <para> 
      This function is used in examples 1 and 20.
    </para>

    

  </sect1>

  <sect1 id="plgfile" renderas="sect3">
    <title>
      <function>plgfile</function>: Get output file handle
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgfile</function>
	  </funcdef>
	  <paramdef><parameter>file</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets the current output file handle, if applicable.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>file</parameter>
	  (<literal>FILE **</literal>, output)
	</term>
	<listitem>
	  <para>
	    File pointer to current output file.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++ and Ocaml.
    </para>

    <para> 
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plMergeOpts" renderas="sect3">
    <title>
      <function>plMergeOpts</function>: Merge use option table into
      internal info structure.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>int
	    <function>plMergeOpts</function>
	  </funcdef>
	  <paramdef><parameter>options</parameter></paramdef>
	  <paramdef><parameter>name</parameter></paramdef>
	  <paramdef><parameter>notes</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
      Merges in a set of user supplied command line options with the 
      internal options table. This allows use options to be used along 
      with the built-in plplot options to set device driver, output file 
      etc. See &plparseopts; for details of how to parse these options in 
      a program. 
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>options</parameter>
	  (<literal>PLOptionTable *</literal>, input)
	</term>
	<listitem>
	  <para>
	    User option table to merge. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>name</parameter>
	  (<literal>const char *name</literal>, input)
	</term>
	<listitem>
	  <para>
	  Label to preface the options in the program help.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>notes</parameter>
	  (<literal>const char **</literal>, input)
	</term>
	<listitem>
	  <para>
	    A null-terminated array of notes which appear after
	    the options in the program help.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++ and Ocaml.
    </para>

    <para>
      This function is used in examples 1, 8, 16, 20 and 21.
    </para>
      
  </sect1>

  <sect1 id="plMinMax2dGrid" renderas="sect3">
    <title>
      <function>plMinMax2dGrid</function>: Find the minimum and
    maximum of a 2d grid allocated using &plAlloc2dGrid;.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plMinMax2dGrid</function>
	  </funcdef>
	  <paramdef><parameter>f</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>fmax</parameter></paramdef>
	  <paramdef><parameter>fmin</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
    Find the minimum and maximum of a 2d grid allocated using &plAlloc2dGrid;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>f</parameter>
	  (<literal>PLFLT **</literal>, input)
	</term>
	<listitem>
	  <para>
	    PLFLT grid to find the maximum / minimum of.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  Dimensions of <literal>f</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fmax, fmin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	  Maximum and minimum values in the grid
	  <literal>f</literal>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, Java, Ocaml 
      and Python.
    </para>

    <para>
      This function is used in examples 8, 11, 20 and 21.
    </para>
      
  </sect1>

  <sect1 id="plOptUsage" renderas="sect3">
    <title>
      <function>plOptUsage</function>: Print usage and syntax message.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plOptUsage</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
      Prints the usage and syntax message. The message can also be 
      display using the -h command line option. There is a default
      message describing the default plplot options. The usage
      message is also modified by &plSetUsage; and &plMergeOpts;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>program_string</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    String to appear as the name of program. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>usage_string</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	  String to appear as the usage text.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, Java, Ocaml, Octave
      and Python.
    </para>

    <para>
      This function is not used in any examples.
    </para>
      
  </sect1>

  <sect1 id="plResetOpts" renderas="sect3">
    <title>
      <function>plMergeOpts</function>: Reset internal option table
      info structure. 
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plResetOpts</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
      Resets the internal command line options table to the default 
      built in value. Any user options added with &plMergeOpts; will be 
      cleared. See &plparseopts; for details of how to parse these 
      options in a program. 
    </para>

    <para>
      This function is currently available in C, C++, Java, Ocaml and
      Octave, although it is not much use in Java or Octave since they 
      don't have plMergeOpts.
    </para>

    <para>
      This function is not used in any examples.
    </para>
      
  </sect1>

  <sect1 id="plsabort" renderas="sect3">
    <title>
      <function>plsabort</function>: Set abort handler
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsabort</function>
	  </funcdef>
	  <paramdef><parameter>handler</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets an optional user abort handler.  See &plabort; for details.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>handler</parameter>
	  (<literal>void (*) (char *)</literal>, input)
	</term>
	<listitem>
	  <para>
	    Error abort handler.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C and Ocaml.
    </para>

    <para> 
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plSetUsage" renderas="sect3">
    <title>
      <function>plSetUsage</function>: Set the strings used in usage
      and syntax messages.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plSetUsage</function>
	  </funcdef>
	  <paramdef><parameter>program_string</parameter></paramdef>
	  <paramdef><parameter>usage_string</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    
    <para>
      Sets the program string and usage string displayed by the command 
      line help option (-h) and by &plOptUsage;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>program_string</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    String to appear as the name of program. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>usage_string</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	  String to appear as the usage text.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, Java, Ocaml, Octave
      and Python.
    </para>

    <para>
      This function is not used in any examples.
    </para>
      
  </sect1>

  <sect1 id="plsexit" renderas="sect3">
    <title>
      <function>plsexit</function>: Set exit handler
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsexit</function>
	  </funcdef>
	  <paramdef><parameter>handler</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets an optional user exit handler.  See &plexit; for details.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>handler</parameter>
	  (<literal>int (*) (char *)</literal>, input)
	</term>
	<listitem>
	  <para>
	    Error exit handler.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++ and Ocaml.
    </para>

    <para> 
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plsfile" renderas="sect3">
    <title>
      <function>plsfile</function>: Set output file handle
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsfile</function>
	  </funcdef>
	  <paramdef><parameter>file</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the current output file handle, if applicable.  If the file has
      has not been previously opened and is required by the driver, the
      user will be prompted for the file name.  This routine, if used, must
      be called before initializing PLplot.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>file</parameter>
	  (<literal>FILE *</literal>, input)
	</term>
	<listitem>
	  <para>
	    File pointer. The type (i.e. text or binary) doesn't matter
	    on *ix systems. On systems where it might matter it should
	    match the type of file that the output driver would produce,
	    i.e. text for the postscript driver.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++ and Ocaml.
    </para>

    <para> 
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="pltr0" renderas="sect3">
    <title>
      <function>pltr0</function>: Identity transformation for grid to world
      mapping
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pltr0</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>tx</parameter></paramdef>
	  <paramdef><parameter>ty</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Identity transformation for grid to world mapping.
      This routine can be used both for &plcont; and &plshade;.
      See also <xref linkend="contour-plots-c"/> and
      <xref linkend="shade-plots-c"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X-position in grid coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y-position in grid coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>tx</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    X-position in world coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ty</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Y-position in world coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to additional input data that is passed as an argument
	    to &plcont; or &plshade; and then on to the grid to world
	    transformation routine.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, Ocaml, Perl, Python 
      and Tcl.
    </para>

    <para> 
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="pltr1" renderas="sect3">
    <title>
      <function>pltr1</function>: Linear interpolation for grid to world
      mapping using singly dimensioned coordinate arrays
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pltr1</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>tx</parameter></paramdef>
	  <paramdef><parameter>ty</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Linear interpolation for grid to world mapping using singly
      dimensioned coordinate arrays.
      This routine can be used both for &plcont; and &plshade;.
      See also <xref linkend="contour-plots-c"/> and
      <xref linkend="shade-plots-c"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X-position in grid coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y-position in grid coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>tx</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    X-position in world coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ty</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Y-position in world coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to additional input data that is passed as an argument
	    to &plcont; or &plshade; and then on to the grid to world
	    transformation routine.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, Ocaml, Perl, Python 
      and Tcl.
    </para>

    <para> 
      This function is used in examples 9 and 16.
    </para>

  </sect1>

  <sect1 id="pltr2" renderas="sect3">
    <title>
      <function>pltr2</function>: Linear interpolation for grid to world
      mapping using doubly dimensioned coordinate arrays (column
      dominant, as per normal C 2d arrays)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pltr2</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>tx</parameter></paramdef>
	  <paramdef><parameter>ty</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Linear interpolation for grid to world mapping using doubly
      dimensioned coordinate arrays (column dominant, as per normal C 2d arrays).
      This routine can be used both for &plcont; and &plshade;.
      See also <xref linkend="contour-plots-c"/> and
      <xref linkend="shade-plots-c"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X-position in grid coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y-position in grid coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>tx</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    X-position in world coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ty</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Y-position in world coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to additional input data that is passed as an argument
	    to &plcont; or &plshade; and then on to the grid to world
	    transformation routine.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is currently available in C, C++, Ocaml, Perl, Python 
      and Tcl.
    </para>

    <para> 
      This function is used in example 22.
    </para>

  </sect1>

  <sect1 id="PLGraphicsIn" renderas="sect3">
    <title><structname>PLGraphicsIn</structname>: PLplot Graphics Input structure</title>

    <para>
      The <structname>PLGraphicsIn</structname> structure is used by 
      &plGetCursor; to return information 
      on the current cursor position and key / button state for 
      interactive drivers. The structure contains the following fields:
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <structfield>type</structfield>
	  (<literal>int</literal>)
	</term>
	<listitem>
	  <para>
	    Type of event (currently unused?).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>state</structfield>
	  (<literal>unsigned int</literal>)
	</term>
	<listitem>
	  <para>
	    Key or button mask.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>keysym</structfield>
	  (<literal>unsigned int</literal>)
	</term>
	<listitem>
	  <para>
	    Key selected.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>button</structfield>
	  (<literal>unsigned int</literal>)
	</term>
	<listitem>
	  <para>
	    Mouse button selected.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>subwindow</structfield>
	  (<literal>PLINT</literal>)
	</term>
	<listitem>
	  <para>
	    Subwindow (or subpage / subplot) number.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>string</structfield>
	  (<literal>char [PL_MAXKEY]</literal>)
	</term>
	<listitem>
	  <para>
	    Translated string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>pX, pY</structfield>
	  (<literal>int</literal>)
	</term>
	<listitem>
	  <para>
	    Absolute device coordinates of pointer.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>dX, dY</structfield>
	  (<literal>PLFLT</literal>)
	</term>
	<listitem>
	  <para>
	    relative device coordinates of pointer.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>wX, wY</structfield>
	  (<literal>PLFLT</literal>)
	</term>
	<listitem>
	  <para>
	    World coordinates of pointer.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    </sect1>

  <sect1 id="PLOptionTable" renderas="sect3">
    <title><structname>PLOptionTable</structname>: PLplot command line options table structure</title>

    <para>
      The <structname>PLOptionTable</structname> structure is used by 
      &plMergeOpts; to pass information on user-defined command line 
      options to plplot. The structure contains the following fields:
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <structfield>opt</structfield>
	  (<literal>const char*</literal>)
	</term>
	<listitem>
	  <para>
	    Name of option.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>handler</structfield>
	  (<literal>int (*func) (const char *, const char *, void *)</literal>)
	</term>
	<listitem>
	  <para>
	    User-defined handler function to be called when option is set. A 
	    NULL value indicates that no user-defined handler is required.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>client_data</structfield>
	  (<literal>void *</literal>)
	</term>
	<listitem>
	  <para>
	    Pointer to client data. A 
	    NULL value indicates that no client data is required.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>var</structfield>
	  (<literal>void *</literal>)
	</term>
	<listitem>
	  <para>
	    Pointer to variable to set to the value specified on the 
	    command line option.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>mode</structfield>
	  (<literal>long</literal>)
	</term>
	<listitem>
	  <para>
	    Type of variable <parameter>var</parameter>. Allowed values
	    are PL_OPT_FUNC, PL_OPT_BOOL, PL_OPT_INT, PL_OPT_FLOAT, 
	    PL_OPT_STRING.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>syntax</structfield>
	  (<literal>const char *</literal>)
	</term>
	<listitem>
	  <para>
	    Syntax for option (used in the usage message).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <structfield>desc</structfield>
	  (<literal>const char *</literal>)
	</term>
	<listitem>
	  <para>
	    Description of the option (used in the usage message).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    </sect1>

</chapter>
