summaryrefslogtreecommitdiffstats
path: root/Doc/libgl.tex
blob: b1686819369e326002662228aa33f0478852b174 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
\section{Built-in Module \sectcode{gl}}
\label{module-gl}
\bimodindex{gl}

This module provides access to the Silicon Graphics
\emph{Graphics Library}.
It is available only on Silicon Graphics machines.

\strong{Warning:}
Some illegal calls to the GL library cause the Python interpreter to dump
core.
In particular, the use of most GL calls is unsafe before the first
window is opened.

The module is too large to document here in its entirety, but the
following should help you to get started.
The parameter conventions for the C functions are translated to Python as
follows:

\begin{itemize}
\item
All (short, long, unsigned) int values are represented by Python
integers.
\item
All float and double values are represented by Python floating point
numbers.
In most cases, Python integers are also allowed.
\item
All arrays are represented by one-dimensional Python lists.
In most cases, tuples are also allowed.
\item
\begin{sloppypar}
All string and character arguments are represented by Python strings,
for instance,
\code{winopen('Hi There!')}
and
\code{rotate(900, 'z')}.
\end{sloppypar}
\item
All (short, long, unsigned) integer arguments or return values that are
only used to specify the length of an array argument are omitted.
For example, the C call

\bcode\begin{verbatim}
lmdef(deftype, index, np, props)
\end{verbatim}\ecode
%
is translated to Python as

\bcode\begin{verbatim}
lmdef(deftype, index, props)
\end{verbatim}\ecode
%
\item
Output arguments are omitted from the argument list; they are
transmitted as function return values instead.
If more than one value must be returned, the return value is a tuple.
If the C function has both a regular return value (that is not omitted
because of the previous rule) and an output argument, the return value
comes first in the tuple.
Examples: the C call

\bcode\begin{verbatim}
getmcolor(i, &red, &green, &blue)
\end{verbatim}\ecode
%
is translated to Python as

\bcode\begin{verbatim}
red, green, blue = getmcolor(i)
\end{verbatim}\ecode
%
\end{itemize}

The following functions are non-standard or have special argument
conventions:

\renewcommand{\indexsubitem}{(in module gl)}
\begin{funcdesc}{varray}{argument}
%JHXXX the argument-argument added
Equivalent to but faster than a number of
\code{v3d()}
calls.
The \var{argument} is a list (or tuple) of points.
Each point must be a tuple of coordinates
\code{(\var{x}, \var{y}, \var{z})} or \code{(\var{x}, \var{y})}.
The points may be 2- or 3-dimensional but must all have the
same dimension.
Float and int values may be mixed however.
The points are always converted to 3D double precision points
by assuming \code{\var{z} = 0.0} if necessary (as indicated in the man page),
and for each point
\code{v3d()}
is called.
\end{funcdesc}

\begin{funcdesc}{nvarray}{}
Equivalent to but faster than a number of
\code{n3f}
and
\code{v3f}
calls.
The argument is an array (list or tuple) of pairs of normals and points.
Each pair is a tuple of a point and a normal for that point.
Each point or normal must be a tuple of coordinates
\code{(\var{x}, \var{y}, \var{z})}.
Three coordinates must be given.
Float and int values may be mixed.
For each pair,
\code{n3f()}
is called for the normal, and then
\code{v3f()}
is called for the point.
\end{funcdesc}

\begin{funcdesc}{vnarray}{}
Similar to 
\code{nvarray()}
but the pairs have the point first and the normal second.
\end{funcdesc}

\begin{funcdesc}{nurbssurface}{s_k\, t_k\, ctl\, s_ord\, t_ord\, type}
% XXX s_k[], t_k[], ctl[][]
Defines a nurbs surface.
The dimensions of
\code{\var{ctl}[][]}
are computed as follows:
\code{[len(\var{s_k}) - \var{s_ord}]},
\code{[len(\var{t_k}) - \var{t_ord}]}.
\end{funcdesc}

\begin{funcdesc}{nurbscurve}{knots\, ctlpoints\, order\, type}
Defines a nurbs curve.
The length of ctlpoints is
\code{len(\var{knots}) - \var{order}}.
\end{funcdesc}

\begin{funcdesc}{pwlcurve}{points\, type}
Defines a piecewise-linear curve.
\var{points}
is a list of points.
\var{type}
must be
\code{N_ST}.
\end{funcdesc}

\begin{funcdesc}{pick}{n}
\funcline{select}{n}
The only argument to these functions specifies the desired size of the
pick or select buffer.
\end{funcdesc}

\begin{funcdesc}{endpick}{}
\funcline{endselect}{}
These functions have no arguments.
They return a list of integers representing the used part of the
pick/select buffer.
No method is provided to detect buffer overrun.
\end{funcdesc}

Here is a tiny but complete example GL program in Python:

\bcode\begin{verbatim}
import gl, GL, time

def main():
    gl.foreground()
    gl.prefposition(500, 900, 500, 900)
    w = gl.winopen('CrissCross')
    gl.ortho2(0.0, 400.0, 0.0, 400.0)
    gl.color(GL.WHITE)
    gl.clear()
    gl.color(GL.RED)
    gl.bgnline()
    gl.v2f(0.0, 0.0)
    gl.v2f(400.0, 400.0)
    gl.endline()
    gl.bgnline()
    gl.v2f(400.0, 0.0)
    gl.v2f(0.0, 400.0)
    gl.endline()
    time.sleep(5)

main()
\end{verbatim}\ecode
%
\section{Standard Modules \sectcode{GL} and \sectcode{DEVICE}}
\nodename{GL and DEVICE}
\stmodindex{GL}
\stmodindex{DEVICE}

These modules define the constants used by the Silicon Graphics
\emph{Graphics Library}
that C programmers find in the header files
\file{<gl/gl.h>}
and
\file{<gl/device.h>}.
Read the module source files for details.