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