Doc/lib/libgl.tex

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