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