Doc/libgl.tex

   1 \section{Built-in Module \sectcode{gl}}
   2 \bimodindex{gl}
   3
   4 This module provides access to the Silicon Graphics
   5 {\em Graphics Library}.
   6 It is available only on Silicon Graphics machines.
   7
   8 \strong{Warning:}
   9 Some illegal calls to the GL library cause the Python interpreter to dump
  10 core.
  11 In particular, the use of most GL calls is unsafe before the first
  12 window is opened.
  13
  14 The module is too large to document here in its entirety, but the
  15 following should help you to get started.
  16 The parameter conventions for the C functions are translated to Python as
  17 follows:
  18
  19 \begin{itemize}
  20 \item
  21 All (short, long, unsigned) int values are represented by Python
  22 integers.
  23 \item
  24 All float and double values are represented by Python floating point
  25 numbers.
  26 In most cases, Python integers are also allowed.
  27 \item
  28 All arrays are represented by one-dimensional Python lists.
  29 In most cases, tuples are also allowed.
  30 \item
  31 \begin{sloppypar}
  32 All string and character arguments are represented by Python strings,
  33 for instance,
  34 \code{winopen('Hi There!')}
  35 and
  36 \code{rotate(900, 'z')}.
  37 \end{sloppypar}
  38 \item
  39 All (short, long, unsigned) integer arguments or return values that are
  40 only used to specify the length of an array argument are omitted.
  41 For example, the C call
  42
  43 \bcode\begin{verbatim}
  44 lmdef(deftype, index, np, props)
  45 \end{verbatim}\ecode
  46
  47 is translated to Python as
  48
  49 \bcode\begin{verbatim}
  50 lmdef(deftype, index, props)
  51 \end{verbatim}\ecode
  52
  53 \item
  54 Output arguments are omitted from the argument list; they are
  55 transmitted as function return values instead.
  56 If more than one value must be returned, the return value is a tuple.
  57 If the C function has both a regular return value (that is not omitted
  58 because of the previous rule) and an output argument, the return value
  59 comes first in the tuple.
  60 Examples: the C call
  61
  62 \bcode\begin{verbatim}
  63 getmcolor(i, &red, &green, &blue)
  64 \end{verbatim}\ecode
  65
  66 is translated to Python as
  67
  68 \bcode\begin{verbatim}
  69 red, green, blue = getmcolor(i)
  70 \end{verbatim}\ecode
  71
  72 \end{itemize}
  73
  74 The following functions are non-standard or have special argument
  75 conventions:
  76
  77 \renewcommand{\indexsubitem}{(in module gl)}
  78 \begin{funcdesc}{varray}{argument}
  79 %JHXXX the argument-argument added
  80 Equivalent to but faster than a number of
  81 \code{v3d()}
  82 calls.
  83 The \var{argument} is a list (or tuple) of points.
  84 Each point must be a tuple of coordinates
  85 \code{(\var{x}, \var{y}, \var{z})} or \code{(\var{x}, \var{y})}.
  86 The points may be 2- or 3-dimensional but must all have the
  87 same dimension.
  88 Float and int values may be mixed however.
  89 The points are always converted to 3D double precision points
  90 by assuming \code{\var{z} = 0.0} if necessary (as indicated in the man page),
  91 and for each point
  92 \code{v3d()}
  93 is called.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{nvarray}{}
  97 Equivalent to but faster than a number of
  98 \code{n3f}
  99 and
 100 \code{v3f}
 101 calls.
 102 The argument is an array (list or tuple) of pairs of normals and points.
 103 Each pair is a tuple of a point and a normal for that point.
 104 Each point or normal must be a tuple of coordinates
 105 \code{(\var{x}, \var{y}, \var{z})}.
 106 Three coordinates must be given.
 107 Float and int values may be mixed.
 108 For each pair,
 109 \code{n3f()}
 110 is called for the normal, and then
 111 \code{v3f()}
 112 is called for the point.
 113 \end{funcdesc}
 114
 115 \begin{funcdesc}{vnarray}{}
 116 Similar to
 117 \code{nvarray()}
 118 but the pairs have the point first and the normal second.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{nurbssurface}{s_k\, t_k\, ctl\, s_ord\, t_ord\, type}
 122 % XXX s_k[], t_k[], ctl[][]
 123 %\itembreak
 124 Defines a nurbs surface.
 125 The dimensions of
 126 \code{\var{ctl}[][]}
 127 are computed as follows:
 128 \code{[len(\var{s_k}) - \var{s_ord}]},
 129 \code{[len(\var{t_k}) - \var{t_ord}]}.
 130 \end{funcdesc}
 131
 132 \begin{funcdesc}{nurbscurve}{knots\, ctlpoints\, order\, type}
 133 Defines a nurbs curve.
 134 The length of ctlpoints is
 135 \code{len(\var{knots}) - \var{order}}.
 136 \end{funcdesc}
 137
 138 \begin{funcdesc}{pwlcurve}{points\, type}
 139 Defines a piecewise-linear curve.
 140 \var{points}
 141 is a list of points.
 142 \var{type}
 143 must be
 144 \code{N_ST}.
 145 \end{funcdesc}
 146
 147 \begin{funcdesc}{pick}{n}
 148 \funcline{select}{n}
 149 The only argument to these functions specifies the desired size of the
 150 pick or select buffer.
 151 \end{funcdesc}
 152
 153 \begin{funcdesc}{endpick}{}
 154 \funcline{endselect}{}
 155 These functions have no arguments.
 156 They return a list of integers representing the used part of the
 157 pick/select buffer.
 158 No method is provided to detect buffer overrun.
 159 \end{funcdesc}
 160
 161 Here is a tiny but complete example GL program in Python:
 162
 163 \bcode\begin{verbatim}
 164 import gl, GL, time
 165
 166 def main():
 167     gl.foreground()
 168     gl.prefposition(500, 900, 500, 900)
 169     w = gl.winopen('CrissCross')
 170     gl.ortho2(0.0, 400.0, 0.0, 400.0)
 171     gl.color(GL.WHITE)
 172     gl.clear()
 173     gl.color(GL.RED)
 174     gl.bgnline()
 175     gl.v2f(0.0, 0.0)
 176     gl.v2f(400.0, 400.0)
 177     gl.endline()
 178     gl.bgnline()
 179     gl.v2f(400.0, 0.0)
 180     gl.v2f(0.0, 400.0)
 181     gl.endline()
 182     time.sleep(5)
 183
 184 main()
 185 \end{verbatim}\ecode
 186
 187 \section{Standard Modules \sectcode{GL} and \sectcode{DEVICE}}
 188 \nodename{GL and DEVICE}
 189 \stmodindex{GL}
 190 \stmodindex{DEVICE}
 191
 192 These modules define the constants used by the Silicon Graphics
 193 {\em Graphics Library}
 194 that C programmers find in the header files
 195 \file{<gl/gl.h>}
 196 and
 197 \file{<gl/device.h>}.
 198 Read the module source files for details.