/Doc/library/gl.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 193 lines · 124 code · 69 blank · 0 comment · 0 complexity · f0ec52d01a419c5681e4b6013009c1d7 MD5 · raw file

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