Restructured library documentation

1 files changed, 197 insertions, 0 deletions

diff --git a/Doc/libgl.tex b/Doc/libgl.tex
new file mode 100644
index 0000000..e86c04b
--- /dev/null
+++ b/Doc/libgl.tex
@@ -0,0 +1,197 @@
+\section{Built-in Module \sectcode{gl}}
+\bimodindex{gl}
+
+This module provides access to the Silicon Graphics
+{\em Graphics Library}.
+It is available only on Silicon Graphics machines.
+
+\strong{Warning:}
+Some illegal calls to the GL library cause the Python interpreter to dump
+core.
+In particular, the use of most GL calls is unsafe before the first
+window is opened.
+
+The module is too large to document here in its entirety, but the
+following should help you to get started.
+The parameter conventions for the C functions are translated to Python as
+follows:
+
+\begin{itemize}
+\item
+All (short, long, unsigned) int values are represented by Python
+integers.
+\item
+All float and double values are represented by Python floating point
+numbers.
+In most cases, Python integers are also allowed.
+\item
+All arrays are represented by one-dimensional Python lists.
+In most cases, tuples are also allowed.
+\item
+\begin{sloppypar}
+All string and character arguments are represented by Python strings,
+for instance,
+\code{winopen('Hi There!')}
+and
+\code{rotate(900, 'z')}.
+\end{sloppypar}
+\item
+All (short, long, unsigned) integer arguments or return values that are
+only used to specify the length of an array argument are omitted.
+For example, the C call
+
+\bcode\begin{verbatim}
+lmdef(deftype, index, np, props)
+\end{verbatim}\ecode
+
+is translated to Python as
+
+\bcode\begin{verbatim}
+lmdef(deftype, index, props)
+\end{verbatim}\ecode
+
+\item
+Output arguments are omitted from the argument list; they are
+transmitted as function return values instead.
+If more than one value must be returned, the return value is a tuple.
+If the C function has both a regular return value (that is not omitted
+because of the previous rule) and an output argument, the return value
+comes first in the tuple.
+Examples: the C call
+
+\bcode\begin{verbatim}
+getmcolor(i, &red, &green, &blue)
+\end{verbatim}\ecode
+
+is translated to Python as
+
+\bcode\begin{verbatim}
+red, green, blue = getmcolor(i)
+\end{verbatim}\ecode
+
+\end{itemize}
+
+The following functions are non-standard or have special argument
+conventions:
+
+\renewcommand{\indexsubitem}{(in module gl)}
+\begin{funcdesc}{varray}{argument}
+%JHXXX the argument-argument added
+Equivalent to but faster than a number of
+\code{v3d()}
+calls.
+The \var{argument} is a list (or tuple) of points.
+Each point must be a tuple of coordinates
+\code{(\var{x}, \var{y}, \var{z})} or \code{(\var{x}, \var{y})}.
+The points may be 2- or 3-dimensional but must all have the
+same dimension.
+Float and int values may be mixed however.
+The points are always converted to 3D double precision points
+by assuming \code{\var{z} = 0.0} if necessary (as indicated in the man page),
+and for each point
+\code{v3d()}
+is called.
+\end{funcdesc}
+
+\begin{funcdesc}{nvarray}{}
+Equivalent to but faster than a number of
+\code{n3f}
+and
+\code{v3f}
+calls.
+The argument is an array (list or tuple) of pairs of normals and points.
+Each pair is a tuple of a point and a normal for that point.
+Each point or normal must be a tuple of coordinates
+\code{(\var{x}, \var{y}, \var{z})}.
+Three coordinates must be given.
+Float and int values may be mixed.
+For each pair,
+\code{n3f()}
+is called for the normal, and then
+\code{v3f()}
+is called for the point.
+\end{funcdesc}
+
+\begin{funcdesc}{vnarray}{}
+Similar to 
+\code{nvarray()}
+but the pairs have the point first and the normal second.
+\end{funcdesc}
+
+\begin{funcdesc}{nurbssurface}{s_k\, t_k\, ctl\, s_ord\, t_ord\, type}
+% XXX s_k[], t_k[], ctl[][]
+%\itembreak
+Defines a nurbs surface.
+The dimensions of
+\code{\var{ctl}[][]}
+are computed as follows:
+\code{[len(\var{s_k}) - \var{s_ord}]},
+\code{[len(\var{t_k}) - \var{t_ord}]}.
+\end{funcdesc}
+
+\begin{funcdesc}{nurbscurve}{knots\, ctlpoints\, order\, type}
+Defines a nurbs curve.
+The length of ctlpoints is
+\code{len(\var{knots}) - \var{order}}.
+\end{funcdesc}
+
+\begin{funcdesc}{pwlcurve}{points\, type}
+Defines a piecewise-linear curve.
+\var{points}
+is a list of points.
+\var{type}
+must be
+\code{N_ST}.
+\end{funcdesc}
+
+\begin{funcdesc}{pick}{n}
+\funcline{select}{n}
+The only argument to these functions specifies the desired size of the
+pick or select buffer.
+\end{funcdesc}
+
+\begin{funcdesc}{endpick}{}
+\funcline{endselect}{}
+These functions have no arguments.
+They return a list of integers representing the used part of the
+pick/select buffer.
+No method is provided to detect buffer overrun.
+\end{funcdesc}
+
+Here is a tiny but complete example GL program in Python:
+
+\bcode\begin{verbatim}
+import gl, GL, time
+
+def main():
+    gl.foreground()
+    gl.prefposition(500, 900, 500, 900)
+    w = gl.winopen('CrissCross')
+    gl.ortho2(0.0, 400.0, 0.0, 400.0)
+    gl.color(GL.WHITE)
+    gl.clear()
+    gl.color(GL.RED)
+    gl.bgnline()
+    gl.v2f(0.0, 0.0)
+    gl.v2f(400.0, 400.0)
+    gl.endline()
+    gl.bgnline()
+    gl.v2f(400.0, 0.0)
+    gl.v2f(0.0, 400.0)
+    gl.endline()
+    time.sleep(5)
+
+main()
+\end{verbatim}\ecode
+
+\section{Standard Modules \sectcode{GL} and \sectcode{DEVICE}}
+\stmodindex{GL}
+\stmodindex{DEVICE}
+
+These modules define the constants used by the Silicon Graphics
+{\em Graphics Library}
+that C programmers find in the header files
+\file{<gl/gl.h>}
+and
+\file{<gl/device.h>}.
+Read the module source files for details.