Doc/library/gl.rst

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