/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
 14This module provides access to the Silicon Graphics *Graphics Library*. It is
 15available 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
 23The module is too large to document here in its entirety, but the following
 24should help you to get started. The parameter conventions for the C functions
 25are 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
 60The 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
124Here 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
174This modules defines the constants used by the Silicon Graphics *Graphics
175Library* that C programmers find in the header file ``<gl/device.h>``. Read the
176module 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
191This module contains constants used by the Silicon Graphics *Graphics Library*
192from the C header file ``<gl/gl.h>``. Read the module source file for details.
193