Doc/libgl.tex

   1 \section{Built-in Module \module{gl}}
   2 \label{module-gl}
   3 \bimodindex{gl}
   4
   5 This module provides access to the Silicon Graphics
   6 \emph{Graphics Library}.
   7 It is available only on Silicon Graphics machines.
   8
   9 \strong{Warning:}
  10 Some illegal calls to the GL library cause the Python interpreter to dump
  11 core.
  12 In particular, the use of most GL calls is unsafe before the first
  13 window is opened.
  14
  15 The module is too large to document here in its entirety, but the
  16 following should help you to get started.
  17 The parameter conventions for the C functions are translated to Python as
  18 follows:
  19
  20 \begin{itemize}
  21 \item
  22 All (short, long, unsigned) int values are represented by Python
  23 integers.
  24 \item
  25 All float and double values are represented by Python floating point
  26 numbers.
  27 In most cases, Python integers are also allowed.
  28 \item
  29 All arrays are represented by one-dimensional Python lists.
  30 In most cases, tuples are also allowed.
  31 \item
  32 \begin{sloppypar}
  33 All string and character arguments are represented by Python strings,
  34 for instance,
  35 \code{winopen('Hi There!')}
  36 and
  37 \code{rotate(900, 'z')}.
  38 \end{sloppypar}
  39 \item
  40 All (short, long, unsigned) integer arguments or return values that are
  41 only used to specify the length of an array argument are omitted.
  42 For example, the C call
  43
  44 \begin{verbatim}
  45 lmdef(deftype, index, np, props)
  46 \end{verbatim}
  47 %
  48 is translated to Python as
  49
  50 \begin{verbatim}
  51 lmdef(deftype, index, props)
  52 \end{verbatim}
  53 %
  54 \item
  55 Output arguments are omitted from the argument list; they are
  56 transmitted as function return values instead.
  57 If more than one value must be returned, the return value is a tuple.
  58 If the C function has both a regular return value (that is not omitted
  59 because of the previous rule) and an output argument, the return value
  60 comes first in the tuple.
  61 Examples: the C call
  62
  63 \begin{verbatim}
  64 getmcolor(i, &red, &green, &blue)
  65 \end{verbatim}
  66 %
  67 is translated to Python as
  68
  69 \begin{verbatim}
  70 red, green, blue = getmcolor(i)
  71 \end{verbatim}
  72 %
  73 \end{itemize}
  74
  75 The following functions are non-standard or have special argument
  76 conventions:
  77
  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 Defines a nurbs surface.
 124 The dimensions of
 125 \code{\var{ctl}[][]}
 126 are computed as follows:
 127 \code{[len(\var{s_k}) - \var{s_ord}]},
 128 \code{[len(\var{t_k}) - \var{t_ord}]}.
 129 \end{funcdesc}
 130
 131 \begin{funcdesc}{nurbscurve}{knots, ctlpoints, order, type}
 132 Defines a nurbs curve.
 133 The length of ctlpoints is
 134 \code{len(\var{knots}) - \var{order}}.
 135 \end{funcdesc}
 136
 137 \begin{funcdesc}{pwlcurve}{points, type}
 138 Defines a piecewise-linear curve.
 139 \var{points}
 140 is a list of points.
 141 \var{type}
 142 must be
 143 \code{N_ST}.
 144 \end{funcdesc}
 145
 146 \begin{funcdesc}{pick}{n}
 147 \funcline{select}{n}
 148 The only argument to these functions specifies the desired size of the
 149 pick or select buffer.
 150 \end{funcdesc}
 151
 152 \begin{funcdesc}{endpick}{}
 153 \funcline{endselect}{}
 154 These functions have no arguments.
 155 They return a list of integers representing the used part of the
 156 pick/select buffer.
 157 No method is provided to detect buffer overrun.
 158 \end{funcdesc}
 159
 160 Here is a tiny but complete example GL program in Python:
 161
 162 \begin{verbatim}
 163 import gl, GL, time
 164
 165 def main():
 166     gl.foreground()
 167     gl.prefposition(500, 900, 500, 900)
 168     w = gl.winopen('CrissCross')
 169     gl.ortho2(0.0, 400.0, 0.0, 400.0)
 170     gl.color(GL.WHITE)
 171     gl.clear()
 172     gl.color(GL.RED)
 173     gl.bgnline()
 174     gl.v2f(0.0, 0.0)
 175     gl.v2f(400.0, 400.0)
 176     gl.endline()
 177     gl.bgnline()
 178     gl.v2f(400.0, 0.0)
 179     gl.v2f(0.0, 400.0)
 180     gl.endline()
 181     time.sleep(5)
 182
 183 main()
 184 \end{verbatim}
 185 %
 186 \section{Standard Modules \module{GL} and \module{DEVICE}}
 187 \nodename{GL and DEVICE}
 188 \stmodindex{GL}
 189 \stmodindex{DEVICE}
 190
 191 These modules define the constants used by the Silicon Graphics
 192 \emph{Graphics Library}
 193 that C programmers find in the header files
 194 \file{<gl/gl.h>}
 195 and
 196 \file{<gl/device.h>}.
 197 Read the module source files for details.