1
2
3 """
4 The Blender.BGL submodule (the OpenGL wrapper).
5
6 B{New}: some GLU functions: L{gluLookAt}, etc.
7
8 The Blender.BGL submodule
9 =========================
10 (when accessing it from the Game Engine use BGL instead of Blender.BGL)
11
12 This module wraps OpenGL constants and functions, making them available from
13 within Blender Python.
14
15 The complete list can be retrieved from the module itself, by listing its
16 contents: dir(Blender.BGL). A simple search on the net can point to more
17 than enough material to teach OpenGL programming, from books to many
18 collections of tutorials.
19
20 The "red book": "I{OpenGL Programming Guide: The Official Guide to Learning
21 OpenGL}" and the online NeHe tutorials are two of the best resources.
22
23 Example::
24 import Blender
25 from Blender.BGL import *
26 from Blender import Draw
27 R = G = B = 0
28 A = 1
29 title = "Testing BGL + Draw"
30 instructions = "Use mouse buttons or wheel to change the background color."
31 quitting = " Press ESC or q to quit."
32 len1 = Draw.GetStringWidth(title)
33 len2 = Draw.GetStringWidth(instructions + quitting)
34 #
35 def show_win():
36 glClearColor(R,G,B,A) # define color used to clear buffers
37 glClear(GL_COLOR_BUFFER_BIT) # use it to clear the color buffer
38 glColor3f(0.35,0.18,0.92) # define default color
39 glBegin(GL_POLYGON) # begin a vertex data list
40 glVertex2i(165, 158)
41 glVertex2i(252, 55)
42 glVertex2i(104, 128)
43 glEnd()
44 glColor3f(0.4,0.4,0.4) # change default color
45 glRecti(40, 96, 60+len1, 113)
46 glColor3f(1,1,1)
47 glRasterPos2i(50,100) # move cursor to x = 50, y = 100
48 Draw.Text(title) # draw this text there
49 glRasterPos2i(350,40) # move cursor again
50 Draw.Text(instructions + quitting) # draw another msg
51 glBegin(GL_LINE_LOOP) # begin a vertex-data list
52 glVertex2i(46,92)
53 glVertex2i(120,92)
54 glVertex2i(120,115)
55 glVertex2i(46,115)
56 glEnd() # close this list
57 #
58 def ev(evt, val): # event callback for Draw.Register()
59 global R,G,B,A # ... it handles input events
60 if evt == Draw.ESCKEY or evt == Draw.QKEY:
61 Draw.Exit() # this quits the script
62 elif not val: return
63 elif evt == Draw.LEFTMOUSE: R = 1 - R
64 elif evt == Draw.MIDDLEMOUSE: G = 1 - G
65 elif evt == Draw.RIGHTMOUSE: B = 1 - B
66 elif evt == Draw.WHEELUPMOUSE:
67 R += 0.1
68 if R > 1: R = 1
69 elif evt == Draw.WHEELDOWNMOUSE:
70 R -= 0.1
71 if R < 0: R = 0
72 else:
73 return # don't redraw if nothing changed
74 Draw.Redraw(1) # make changes visible.
75 #
76 Draw.Register(show_win, ev, None) # start the main loop
77
78 @note: you can use the L{Image} module and L{Image.Image} BPy object to load
79 and set textures. See L{Image.Image.glLoad} and L{Image.Image.glFree},
80 for example.
81 @see: U{www.opengl.org}
82 @see: U{nehe.gamedev.net}
83 """
84
86 """
87 Operate on the accumulation buffer
88 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/accum.html}
89
90 @type op: Enumerated constant
91 @param op: The accumulation buffer operation.
92 @type value: float
93 @param value: a value used in the accumulation buffer operation.
94 """
95
97 """
98 Specify the alpha test function
99 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/alphafunc.html}
100
101 @type func: Enumerated constant
102 @param func: Specifies the alpha comparison function.
103 @type ref: float
104 @param ref: The reference value that incoming alpha values are compared to.
105 Clamped between 0 and 1.
106 """
107
108 -def glAreTexturesResident(n, textures, residences):
109 """
110 Determine if textures are loaded in texture memory
111 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/aretexturesresident.html}
112
113 @type n: int
114 @param n: Specifies the number of textures to be queried.
115 @type textures: Buffer object I{type GL_INT}
116 @param textures: Specifies an array containing the names of the textures to be queried
117 @type residences: Buffer object I{type GL_INT}(boolean)
118 @param residences: An array in which the texture residence status in returned.The residence status of a
119 texture named by an element of textures is returned in the corresponding element of residences.
120 """
121
123 """
124 Delimit the vertices of a primitive or a group of like primatives
125 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/begin.html}
126
127 @type mode: Enumerated constant
128 @param mode: Specifies the primitive that will be create from vertices between glBegin and
129 glEnd.
130 """
131
132 -def glBindTexture(target, texture):
133 """
134 Bind a named texture to a texturing target
135 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/bindtexture.html}
136
137 @type target: Enumerated constant
138 @param target: Specifies the target to which the texture is bound.
139 @type texture: unsigned int
140 @param texture: Specifies the name of a texture.
141 """
142
143 -def glBitmap(width, height, xorig, yorig, xmove, ymove, bitmap):
144 """
145 Draw a bitmap
146 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/bitmap.html}
147
148 @type width, height: int
149 @param width, height: Specify the pixel width and height of the bitmap image.
150 @type xorig, yorig: float
151 @param xorig, yorig: Specify the location of the origin in the bitmap image. The origin is measured
152 from the lower left corner of the bitmap, with right and up being the positive axes.
153 @type xmove, ymove: float
154 @param xmove, ymove: Specify the x and y offsets to be added to the current raster position after
155 the bitmap is drawn.
156 @type bitmap: Buffer object I{type GL_BYTE}
157 @param bitmap: Specifies the address of the bitmap image.
158 """
159
161 """
162 Specify pixel arithmetic
163 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/blendfunc.html}
164
165 @type sfactor: Enumerated constant
166 @param sfactor: Specifies how the red, green, blue, and alpha source blending factors are
167 computed.
168 @type dfactor: Enumerated constant
169 @param dfactor: Specifies how the red, green, blue, and alpha destination blending factors are
170 computed.
171 """
172
174 """
175 Execute a display list
176 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/calllist.html}
177
178 @type list: unsigned int
179 @param list: Specifies the integer name of the display list to be executed.
180 """
181
183 """
184 Execute a list of display lists
185 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/calllists.html}
186
187 @type n: int
188 @param n: Specifies the number of display lists to be executed.
189 @type type: Enumerated constant
190 @param type: Specifies the type of values in lists.
191 @type lists: Buffer object
192 @param lists: Specifies the address of an array of name offsets in the display list.
193 The pointer type is void because the offsets can be bytes, shorts, ints, or floats,
194 depending on the value of type.
195 """
196
198 """
199 Clear buffers to preset values
200 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/clear.html}
201
202 @type mask: Enumerated constant(s)
203 @param mask: Bitwise OR of masks that indicate the buffers to be cleared.
204 """
205
207 """
208 Specify clear values for the accumulation buffer
209 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/clearaccum.html}
210
211 @type red, green, blue, alpha: float
212 @param red, green, blue, alpha: Specify the red, green, blue, and alpha values used when the
213 accumulation buffer is cleared. The initial values are all 0.
214 """
215
217 """
218 Specify clear values for the color buffers
219 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/clearcolor.html}
220
221 @type red, green, blue, alpha: float
222 @param red, green, blue, alpha: Specify the red, green, blue, and alpha values used when the
223 color buffers are cleared. The initial values are all 0.
224 """
225
227 """
228 Specify the clear value for the depth buffer
229 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/cleardepth.html}
230
231 @type depth: int
232 @param depth: Specifies the depth value used when the depth buffer is cleared.
233 The initial value is 1.
234 """
235
237 """
238 Specify the clear value for the color index buffers
239 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/clearindex.html}
240
241 @type c: float
242 @param c: Specifies the index used when the color index buffers are cleared.
243 The initial value is 0.
244 """
245
247 """
248 Specify the clear value for the stencil buffer
249 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/clearstencil.html}
250
251 @type s: int
252 @param s: Specifies the index used when the stencil buffer is cleared. The initial value is 0.
253 """
254
256 """
257 Specify a plane against which all geometry is clipped
258 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/clipplane.html}
259
260 @type plane: Enumerated constant
261 @param plane: Specifies which clipping plane is being positioned.
262 @type equation: Buffer object I{type GL_FLOAT}(double)
263 @param equation: Specifies the address of an array of four double- precision floating-point
264 values. These values are interpreted as a plane equation.
265 """
266
267 -def glColor (red, green, blue, alpha):
268 """
269 B{glColor3b, glColor3d, glColor3f, glColor3i, glColor3s, glColor3ub, glColor3ui, glColor3us,
270 glColor4b, glColor4d, glColor4f, glColor4i, glColor4s, glColor4ub, glColor4ui, glColor4us,
271 glColor3bv, glColor3dv, glColor3fv, glColor3iv, glColor3sv, glColor3ubv, glColor3uiv,
272 glColor3usv, glColor4bv, glColor4dv, glColor4fv, glColor4iv, glColor4sv, glColor4ubv,
273 glColor4uiv, glColor4usv}
274
275 Set a new color.
276 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/color.html}
277
278 @type red, green, blue, alpha: Depends on function prototype.
279 @param red, green, blue: Specify new red, green, and blue values for the current color.
280 @param alpha: Specifies a new alpha value for the current color. Included only in the
281 four-argument glColor4 commands. (With '4' colors only)
282 """
283
285 """
286 Enable and disable writing of frame buffer color components
287 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/colormask.html}
288
289 @type red, green, blue, alpha: int (boolean)
290 @param red, green, blue, alpha: Specify whether red, green, blue, and alpha can or cannot be
291 written into the frame buffer. The initial values are all GL_TRUE, indicating that the
292 color components can be written.
293 """
294
296 """
297 Cause a material color to track the current color
298 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/colormaterial.html}
299
300 @type face: Enumerated constant
301 @param face: Specifies whether front, back, or both front and back material parameters should
302 track the current color.
303 @type mode: Enumerated constant
304 @param mode: Specifies which of several material parameters track the current color.
305 """
306
308 """
309 Copy pixels in the frame buffer
310 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/copypixels.html}
311
312 @type x, y: int
313 @param x, y: Specify the window coordinates of the lower left corner of the rectangular
314 region of pixels to be copied.
315 @type width, height: int
316 @param width,height: Specify the dimensions of the rectangular region of pixels to be copied.
317 Both must be non-negative.
318 @type type: Enumerated constant
319 @param type: Specifies whether color values, depth values, or stencil values are to be copied.
320 """
321
323 """
324 Specify whether front- or back-facing facets can be culled
325 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/cullface.html}
326
327 @type mode: Enumerated constant
328 @param mode: Specifies whether front- or back-facing facets are candidates for culling.
329 """
330
332 """
333 Delete a contiguous group of display lists
334 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/deletelists.html}
335
336 @type list: unsigned int
337 @param list: Specifies the integer name of the first display list to delete
338 @type range: int
339 @param range: Specifies the number of display lists to delete
340 """
341
342 -def glDeleteTextures(n, textures):
343 """
344 Delete named textures
345 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/deletetextures.html}
346
347 @type n: int
348 @param n: Specifies the number of textures to be deleted
349 @type textures: Buffer I{GL_INT}
350 @param textures: Specifies an array of textures to be deleted
351 """
352
354 """
355 Specify the value used for depth buffer comparisons
356 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/depthfunc.html}
357
358 @type func: Enumerated constant
359 @param func: Specifies the depth comparison function.
360 """
361
363 """
364 Enable or disable writing into the depth buffer
365 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/depthmask.html}
366
367 @type flag: int (boolean)
368 @param flag: Specifies whether the depth buffer is enabled for writing. If flag is GL_FALSE,
369 depth buffer writing is disabled. Otherwise, it is enabled. Initially, depth buffer
370 writing is enabled.
371 """
372
374 """
375 Specify mapping of depth values from normalized device coordinates to window coordinates
376 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/depthrange.html}
377
378 @type zNear: int
379 @param zNear: Specifies the mapping of the near clipping plane to window coordinates.
380 The initial value is 0.
381 @type zFar: int
382 @param zFar: Specifies the mapping of the far clipping plane to window coordinates.
383 The initial value is 1.
384 """
385
387 """
388 Disable server-side GL capabilities
389 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/enable.html}
390
391 @type cap: Enumerated constant
392 @param cap: Specifies a symbolic constant indicating a GL capability.
393 """
394
396 """
397 Specify which color buffers are to be drawn into
398 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/drawbuffer.html}
399
400 @type mode: Enumerated constant
401 @param mode: Specifies up to four color buffers to be drawn into.
402 """
403
405 """
406 Write a block of pixels to the frame buffer
407 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/drawpixels.html}
408
409 @type width, height: int
410 @param width, height: Specify the dimensions of the pixel rectangle to be
411 written into the frame buffer.
412 @type format: Enumerated constant
413 @param format: Specifies the format of the pixel data.
414 @type type: Enumerated constant
415 @param type: Specifies the data type for pixels.
416 @type pixels: Buffer object
417 @param pixels: Specifies a pointer to the pixel data.
418 """
419
421 """
422 B{glEdgeFlag, glEdgeFlagv}
423
424 Flag edges as either boundary or non-boundary
425 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/edgeflag.html}
426
427 @type flag: Depends of function prototype
428 @param flag: Specifies the current edge flag value.The initial value is GL_TRUE.
429 """
430
432 """
433 Enable server-side GL capabilities
434 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/enable.html}
435
436 @type cap: Enumerated constant
437 @param cap: Specifies a symbolic constant indicating a GL capability.
438 """
439
441 """
442 Delimit the vertices of a primitive or group of like primitives
443 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/begin.html}
444 """
445
447 """
448 Create or replace a display list
449 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/newlist.html}
450 """
451
453 """
454 B{glEvalCoord1d, glEvalCoord1f, glEvalCoord2d, glEvalCoord2f, glEvalCoord1dv, glEvalCoord1fv,
455 glEvalCoord2dv, glEvalCoord2fv}
456
457 Evaluate enabled one- and two-dimensional maps
458 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/evalcoord.html}
459
460 @type u: Depends on function prototype.
461 @param u: Specifies a value that is the domain coordinate u to the basis function defined
462 in a previous glMap1 or glMap2 command. If the function prototype ends in 'v' then
463 u specifies a pointer to an array containing either one or two domain coordinates. The first
464 coordinate is u. The second coordinate is v, which is present only in glEvalCoord2 versions.
465 @type v: Depends on function prototype. (only with '2' prototypes)
466 @param v: Specifies a value that is the domain coordinate v to the basis function defined
467 in a previous glMap2 command. This argument is not present in a glEvalCoord1 command.
468 """
469
471 """
472 B{glEvalMesh1 or glEvalMesh2}
473
474 Compute a one- or two-dimensional grid of points or lines
475 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/evalmesh.html}
476
477 @type mode: Enumerated constant
478 @param mode: In glEvalMesh1, specifies whether to compute a one-dimensional
479 mesh of points or lines.
480 @type i1, i2: int
481 @param i1, i2: Specify the first and last integer values for the grid domain variable i.
482 """
483
485 """
486 B{glEvalPoint1 and glEvalPoint2}
487
488 Generate and evaluate a single point in a mesh
489 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/evalpoint.html}
490
491 @type i: int
492 @param i: Specifies the integer value for grid domain variable i.
493 @type j: int (only with '2' prototypes)
494 @param j: Specifies the integer value for grid domain variable j (glEvalPoint2 only).
495 """
496
498 """
499 Controls feedback mode
500 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/feedbackbuffer.html}
501
502 @type size: int
503 @param size:Specifies the maximum number of values that can be written into buffer.
504 @type type: Enumerated constant
505 @param type:Specifies a symbolic constant that describes the information that
506 will be returned for each vertex.
507 @type buffer: Buffer object I{GL_FLOAT}
508 @param buffer: Returns the feedback data.
509 """
510
512 """
513 Block until all GL execution is complete
514 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/finish.html}
515 """
516
518 """
519 Force Execution of GL commands in finite time
520 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/flush.html}
521 """
522
523 -def glFog (pname, param):
524 """
525 B{glFogf, glFogi, glFogfv, glFogiv}
526
527 Specify fog parameters
528 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/fog.html}
529
530 @type pname: Enumerated constant
531 @param pname: Specifies a single-valued fog parameter. If the function prototype
532 ends in 'v' specifies a fog parameter.
533 @type param: Depends on function prototype.
534 @param param: Specifies the value or values to be assigned to pname. GL_FOG_COLOR
535 requires an array of four values. All other parameters accept an array containing
536 only a single value.
537 """
538
540 """
541 Define front- and back-facing polygons
542 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/frontface.html}
543
544 @type mode: Enumerated constant
545 @param mode: Specifies the orientation of front-facing polygons.
546 """
547
548 -def glFrustum(left, right, bottom, top, zNear, zFar):
549 """
550 Multiply the current matrix by a perspective matrix
551 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/frustum.html}
552
553 @type left, right: double (float)
554 @param left, right: Specify the coordinates for the left and right vertical
555 clipping planes.
556 @type top, bottom: double (float)
557 @param top, bottom: Specify the coordinates for the bottom and top horizontal
558 clipping planes.
559 @type zNear, zFar: double (float)
560 @param zNear, zFar: Specify the distances to the near and far depth clipping planes.
561 Both distances must be positive.
562 """
563
565 """
566 Generate a contiguous set of empty display lists
567 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/genlists.html}
568
569 @type range: int
570 @param range: Specifies the number of contiguous empty display lists to be generated.
571 """
572
573 -def glGenTextures(n, textures):
574 """
575 Generate texture names
576 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/gentextures.html}
577
578 @type n: int
579 @param n: Specifies the number of textures name to be generated.
580 @type textures: Buffer object I{type GL_INT}
581 @param textures: Specifies an array in which the generated textures names are stored.
582 """
583
584 -def glGet (pname, param):
585 """
586 B{glGetBooleanv, glGetfloatv, glGetFloatv, glGetIntegerv}
587
588 Return the value or values of a selected parameter
589 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/get.html}
590
591 @type pname: Enumerated constant
592 @param pname: Specifies the parameter value to be returned.
593 @type param: Depends on function prototype.
594 @param param: Returns the value or values of the specified parameter.
595 """
596
598 """
599 Return the coefficients of the specified clipping plane
600 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getclipplane.html}
601
602 @type plane: Enumerated constant
603 @param plane: Specifies a clipping plane. The number of clipping planes depends on the
604 implementation, but at least six clipping planes are supported. They are identified by
605 symbolic names of the form GL_CLIP_PLANEi where 0 < i < GL_MAX_CLIP_PLANES.
606 @type equation: Buffer object I{type GL_FLOAT}
607 @param equation: Returns four float (double)-precision values that are the coefficients of the
608 plane equation of plane in eye coordinates. The initial value is (0, 0, 0, 0).
609 """
610
612 """
613 Return error information
614 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/geterror.html}
615 """
616
618 """
619 B{glGetLightfv and glGetLightiv}
620
621 Return light source parameter values
622 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getlight.html}
623
624 @type light: Enumerated constant
625 @param light: Specifies a light source. The number of possible lights depends on the
626 implementation, but at least eight lights are supported. They are identified by symbolic
627 names of the form GL_LIGHTi where 0 < i < GL_MAX_LIGHTS.
628 @type pname: Enumerated constant
629 @param pname: Specifies a light source parameter for light.
630 @type params: Buffer object. Depends on function prototype.
631 @param params: Returns the requested data.
632 """
633
635 """
636 B{glGetMapdv, glGetMapfv, glGetMapiv}
637
638 Return evaluator parameters
639 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getmap.html}
640
641 @type target: Enumerated constant
642 @param target: Specifies the symbolic name of a map.
643 @type query: Enumerated constant
644 @param query: Specifies which parameter to return.
645 @type v: Buffer object. Depends on function prototype.
646 @param v: Returns the requested data.
647 """
648
650 """
651 B{glGetMaterialfv, glGetMaterialiv}
652
653 Return material parameters
654 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getmaterial.html}
655
656 @type face: Enumerated constant
657 @param face: Specifies which of the two materials is being queried.
658 representing the front and back materials, respectively.
659 @type pname: Enumerated constant
660 @param pname: Specifies the material parameter to return.
661 @type params: Buffer object. Depends on function prototype.
662 @param params: Returns the requested data.
663 """
664
666 """
667 B{glGetPixelMapfv, glGetPixelMapuiv, glGetPixelMapusv}
668
669 Return the specified pixel map
670 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getpixelmap.html}
671
672 @type map: Enumerated constant
673 @param map: Specifies the name of the pixel map to return.
674 @type values: Buffer object. Depends on function prototype.
675 @param values: Returns the pixel map contents.
676 """
677
679 """
680 Return the polygon stipple pattern
681 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getpolygonstipple.html}
682
683 @type mask: Buffer object I{type GL_BYTE}
684 @param mask: Returns the stipple pattern. The initial value is all 1's.
685 """
686
688 """
689 Return a string describing the current GL connection
690 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getstring.html}
691
692 @type name: Enumerated constant
693 @param name: Specifies a symbolic constant.
694
695 """
696
698 """
699 B{glGetTexEnvfv, glGetTexEnviv}
700
701 Return texture environment parameters
702 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/gettexenv.html}
703
704 @type target: Enumerated constant
705 @param target: Specifies a texture environment. Must be GL_TEXTURE_ENV.
706 @type pname: Enumerated constant
707 @param pname: Specifies the symbolic name of a texture environment parameter.
708 @type params: Buffer object. Depends on function prototype.
709 @param params: Returns the requested data.
710 """
711
713 """
714 B{glGetTexGendv, glGetTexGenfv, glGetTexGeniv}
715
716 Return texture coordinate generation parameters
717 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/gettexgen.html}
718
719 @type coord: Enumerated constant
720 @param coord: Specifies a texture coordinate.
721 @type pname: Enumerated constant
722 @param pname: Specifies the symbolic name of the value(s) to be returned.
723 @type params: Buffer object. Depends on function prototype.
724 @param params: Returns the requested data.
725 """
726
728 """
729 Return a texture image
730 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/getteximage.html}
731
732 @type target: Enumerated constant
733 @param target: Specifies which texture is to be obtained.
734 @type level: int
735 @param level: Specifies the level-of-detail number of the desired image.
736 Level 0 is the base image level. Level n is the nth mipmap reduction image.
737 @type format: Enumerated constant
738 @param format: Specifies a pixel format for the returned data.
739 @type type: Enumerated constant
740 @param type: Specifies a pixel type for the returned data.
741 @type pixels: Buffer object.
742 @param pixels: Returns the texture image. Should be a pointer to an array of the
743 type specified by type
744 """
745
747 """
748 B{glGetTexLevelParameterfv, glGetTexLevelParameteriv}
749
750 return texture parameter values for a specific level of detail
751 @see: U{opengl.org/developers/documentation/man_pages/hardcopy/GL/html/gl/gettexlevelparameter.html}
752
753 @type target: Enumerated constant
754 @param target: Specifies the symbolic name of the target texture.
755 @type level: int
756 @param level: Specifies the level-of-detail number of the desired image.
757 Level 0 is the base image level. Level n is the nth mipmap reduction image.
758 @type pname: Enumerated constant
759 @param pname: Specifies the symbolic name of a texture parameter.
760 @type params: Buffer object. Depends on function prototype.
761 @param params: Returns the requested data.
762 """
763
765 """
766 B{glGetTexParameterfv, glGetTexParameteriv}
767
768 Return texture parameter values
769 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/gettexparameter.html}
770
771 @type target: Enumerated constant
772 @param target: Specifies the symbolic name of the target texture.
773 @type pname: Enumerated constant
774 @param pname: Specifies the symbolic name the target texture.
775 @type params: Buffer object. Depends on function prototype.
776 @param params: Returns the texture parameters.
777 """
778
780 """
781 Specify implementation-specific hints
782 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/hint.html}
783
784 @type target: Enumerated constant
785 @param target: Specifies a symbolic constant indicating the behavior to be
786 controlled.
787 @type mode: Enumerated constant
788 @param mode: Specifies a symbolic constant indicating the desired behavior.
789 """
790
792 """
793 B{glIndexd, glIndexf, glIndexi, glIndexs, glIndexdv, glIndexfv, glIndexiv, glIndexsv}
794
795 Set the current color index
796 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/index_.html}
797
798 @type c: Buffer object. Depends on function prototype.
799 @param c: Specifies a pointer to a one element array that contains the new value for
800 the current color index.
801 """
802
804 """
805 Initialize the name stack
806 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/initnames.html}
807 """
808
810 """
811 Test whether a capability is enabled
812 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/isenabled.html}
813
814 @type cap: Enumerated constant
815 @param cap: Specifies a constant representing a GL capability.
816 """
817
819 """
820 Determine if a name corresponds to a display-list
821 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/islist.html}
822
823 @type list: unsigned int
824 @param list: Specifies a potential display-list name.
825 """
826
827 -def glIsTexture(texture):
828 """
829 Determine if a name corresponds to a texture
830 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/istexture.html}
831
832 @type texture: unsigned int
833 @param texture: Specifies a value that may be the name of a texture.
834 """
835
837 """
838 B{glLightf,glLighti, glLightfv, glLightiv}
839
840 Set the light source parameters
841 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/light.html}
842
843 @type light: Enumerated constant
844 @param light: Specifies a light. The number of lights depends on the implementation,
845 but at least eight lights are supported. They are identified by symbolic names of the
846 form GL_LIGHTi where 0 < i < GL_MAX_LIGHTS.
847 @type pname: Enumerated constant
848 @param pname: Specifies a single-valued light source parameter for light.
849 @type param: Depends on function prototype.
850 @param param: Specifies the value that parameter pname of light source light will be set to.
851 If function prototype ends in 'v' specifies a pointer to the value or values that
852 parameter pname of light source light will be set to.
853 """
854
856 """
857 B{glLightModelf, glLightModeli, glLightModelfv, glLightModeliv}
858
859 Set the lighting model parameters
860 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/lightmodel.html}
861
862 @type pname: Enumerated constant
863 @param pname: Specifies a single-value light model parameter.
864 @type param: Depends on function prototype.
865 @param param: Specifies the value that param will be set to. If function prototype ends in 'v'
866 specifies a pointer to the value or values that param will be set to.
867 """
868
870 """
871 Specify the line stipple pattern
872 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/linestipple.html}
873
874 @type factor: int
875 @param factor: Specifies a multiplier for each bit in the line stipple pattern.
876 If factor is 3, for example, each bit in the pattern is used three times before
877 the next bit in the pattern is used. factor is clamped to the range [1, 256] and
878 defaults to 1.
879 @type pattern: unsigned short int
880 @param pattern: Specifies a 16-bit integer whose bit pattern determines which fragments
881 of a line will be drawn when the line is rasterized. Bit zero is used first; the default
882 pattern is all 1's.
883 """
884
886 """
887 Specify the width of rasterized lines.
888 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/linewidth.html}
889
890 @type width: float
891 @param width: Specifies the width of rasterized lines. The initial value is 1.
892 """
893
895 """
896 Set the display-list base for glCallLists
897 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/listbase.html}
898
899 @type base: unsigned int
900 @param base: Specifies an integer offset that will be added to glCallLists
901 offsets to generate display-list names. The initial value is 0.
902 """
903
905 """
906 Replace the current matrix with the identity matrix
907 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/loadidentity.html}
908 """
909
911 """
912 B{glLoadMatrixd, glLoadMatixf}
913
914 Replace the current matrix with the specified matrix
915 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/loadmatrix.html}
916
917 @type m: Buffer object. Depends on function prototype.
918 @param m: Specifies a pointer to 16 consecutive values, which are used as the elements
919 of a 4x4 column-major matrix.
920 """
921
923 """
924 Load a name onto the name stack.
925 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/loadname.html}
926
927 @type name: unsigned int
928 @param name: Specifies a name that will replace the top value on the name stack.
929 """
930
932 """
933 Specify a logical pixel operation for color index rendering
934 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/logicop.html}
935
936 @type opcode: Enumerated constant
937 @param opcode: Specifies a symbolic constant that selects a logical operation.
938 """
939
940 -def glMap1 (target, u1, u2, stride, order, points):
941 """
942 B{glMap1d, glMap1f}
943
944 Define a one-dimensional evaluator
945 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/map1.html}
946
947 @type target: Enumerated constant
948 @param target: Specifies the kind of values that are generated by the evaluator.
949 @type u1, u2: Depends on function prototype.
950 @param u1,u2: Specify a linear mapping of u, as presented to glEvalCoord1, to ^, t
951 he variable that is evaluated by the equations specified by this command.
952 @type stride: int
953 @param stride: Specifies the number of floats or float (double)s between the beginning
954 of one control point and the beginning of the next one in the data structure
955 referenced in points. This allows control points to be embedded in arbitrary data
956 structures. The only constraint is that the values for a particular control point must
957 occupy contiguous memory locations.
958 @type order: int
959 @param order: Specifies the number of control points. Must be positive.
960 @type points: Buffer object. Depends on function prototype.
961 @param points: Specifies a pointer to the array of control points.
962 """
963
964 -def glMap2 (target, u1, u2, ustride, uorder, v1, v2, vstride, vorder, points):
965 """
966 B{glMap2d, glMap2f}
967
968 Define a two-dimensional evaluator
969 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/map2.html}
970
971 @type target: Enumerated constant
972 @param target: Specifies the kind of values that are generated by the evaluator.
973 @type u1, u2: Depends on function prototype.
974 @param u1,u2: Specify a linear mapping of u, as presented to glEvalCoord2, to ^, t
975 he variable that is evaluated by the equations specified by this command. Initially
976 u1 is 0 and u2 is 1.
977 @type ustride: int
978 @param ustride: Specifies the number of floats or float (double)s between the beginning
979 of control point R and the beginning of control point R ij, where i and j are the u
980 and v control point indices, respectively. This allows control points to be embedded
981 in arbitrary data structures. The only constraint is that the values for a particular
982 control point must occupy contiguous memory locations. The initial value of ustride is 0.
983 @type uorder: int
984 @param uorder: Specifies the dimension of the control point array in the u axis.
985 Must be positive. The initial value is 1.
986 @type v1, v2: Depends on function prototype.
987 @param v1, v2: Specify a linear mapping of v, as presented to glEvalCoord2, to ^,
988 one of the two variables that are evaluated by the equations specified by this command.
989 Initially, v1 is 0 and v2 is 1.
990 @type vstride: int
991 @param vstride: Specifies the number of floats or float (double)s between the beginning of control
992 point R and the beginning of control point R ij, where i and j are the u and v control
993 point(indices, respectively. This allows control points to be embedded in arbitrary data
994 structures. The only constraint is that the values for a particular control point must
995 occupy contiguous memory locations. The initial value of vstride is 0.
996 @type vorder: int
997 @param vorder: Specifies the dimension of the control point array in the v axis.
998 Must be positive. The initial value is 1.
999 @type points: Buffer object. Depends on function prototype.
1000 @param points: Specifies a pointer to the array of control points.
1001 """
1002
1004 """
1005 B{glMapGrid1d, glMapGrid1f, glMapGrid2d, glMapGrid2f}
1006
1007 Define a one- or two-dimensional mesh
1008 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/mapgrid.html}
1009
1010 @type un: int
1011 @param un: Specifies the number of partitions in the grid range interval
1012 [u1, u2]. Must be positive.
1013 @type u1, u2: Depends on function prototype.
1014 @param u1, u2: Specify the mappings for integer grid domain values i=0 and i=un.
1015 @type vn: int
1016 @param vn: Specifies the number of partitions in the grid range interval [v1, v2]
1017 (glMapGrid2 only).
1018 @type v1, v2: Depends on function prototype.
1019 @param v1, v2: Specify the mappings for integer grid domain values j=0 and j=vn
1020 (glMapGrid2 only).
1021 """
1022
1024 """
1025 Specify material parameters for the lighting model.
1026 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/material.html}
1027
1028 @type face: Enumerated constant
1029 @param face: Specifies which face or faces are being updated. Must be one of:
1030 @type pname: Enumerated constant
1031 @param pname: Specifies the single-valued material parameter of the face
1032 or faces that is being updated. Must be GL_SHININESS.
1033 @type params: int
1034 @param params: Specifies the value that parameter GL_SHININESS will be set to.
1035 If function prototype ends in 'v' specifies a pointer to the value or values that
1036 pname will be set to.
1037 """
1038
1040 """
1041 Specify which matrix is the current matrix.
1042 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/matrixmode.html}
1043
1044 @type mode: Enumerated constant
1045 @param mode: Specifies which matrix stack is the target for subsequent matrix operations.
1046 """
1047
1049 """
1050 B{glMultMatrixd, glMultMatrixf}
1051
1052 Multiply the current matrix with the specified matrix
1053 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/multmatrix.html}
1054
1055 @type m: Buffer object. Depends on function prototype.
1056 @param m: Points to 16 consecutive values that are used as the elements of a 4x4 column
1057 major matrix.
1058 """
1059
1061 """
1062 Create or replace a display list
1063 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/newlist.html}
1064
1065 @type list: unsigned int
1066 @param list: Specifies the display list name
1067 @type mode: Enumerated constant
1068 @param mode: Specifies the compilation mode.
1069 """
1070
1072 """
1073 B{Normal3b, Normal3bv, Normal3d, Normal3dv, Normal3f, Normal3fv, Normal3i, Normal3iv,
1074 Normal3s, Normal3sv}
1075
1076 Set the current normal vector
1077 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/normal.html}
1078
1079 @type nx, ny, nz: Depends on function prototype. (non - 'v' prototypes only)
1080 @param nx, ny, nz: Specify the x, y, and z coordinates of the new current normal.
1081 The initial value of the current normal is the unit vector, (0, 0, 1).
1082 @type v: Buffer object. Depends on function prototype. ('v' prototypes)
1083 @param v: Specifies a pointer to an array of three elements: the x, y, and z coordinates
1084 of the new current normal.
1085 """
1086
1087 -def glOrtho(left, right, bottom, top, zNear, zFar):
1088 """
1089 Multiply the current matrix with an orthographic matrix
1090 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/ortho.html}
1091
1092 @type left, right: double (float)
1093 @param left, right: Specify the coordinates for the left and
1094 right vertical clipping planes.
1095 @type bottom, top: double (float)
1096 @param bottom, top: Specify the coordinates for the bottom and top
1097 horizontal clipping planes.
1098 @type zNear, zFar: double (float)
1099 @param zNear, zFar: Specify the distances to the nearer and farther
1100 depth clipping planes. These values are negative if the plane is to be behind the viewer.
1101 """
1102
1104 """
1105 Place a marker in the feedback buffer
1106 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/passthrough.html}
1107
1108 @type token: float
1109 @param token: Specifies a marker value to be placed in the feedback
1110 buffer following a GL_PASS_THROUGH_TOKEN.
1111 """
1112
1114 """
1115 B{glPixelMapfv, glPixelMapuiv, glPixelMapusv}
1116
1117 Set up pixel transfer maps
1118 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pixelmap.html}
1119
1120 @type map: Enumerated constant
1121 @param map: Specifies a symbolic map name.
1122 @type mapsize: int
1123 @param mapsize: Specifies the size of the map being defined.
1124 @type values: Buffer object. Depends on function prototype.
1125 @param values: Specifies an array of mapsize values.
1126 """
1127
1129 """
1130 B{glPixelStoref, glPixelStorei}
1131
1132 Set pixel storage modes
1133 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pixelstore.html}
1134
1135 @type pname: Enumerated constant
1136 @param pname: Specifies the symbolic name of the parameter to be set.
1137 Six values affect the packing of pixel data into memory.
1138 Six more affect the unpacking of pixel data from memory.
1139 @type param: Depends on function prototype.
1140 @param param: Specifies the value that pname is set to.
1141 """
1142
1144 """
1145 B{glPixelTransferf, glPixelTransferi}
1146
1147 Set pixel transfer modes
1148 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pixeltransfer.html}
1149
1150 @type pname: Enumerated constant
1151 @param pname: Specifies the symbolic name of the pixel transfer parameter to be set.
1152 @type param: Depends on function prototype.
1153 @param param: Specifies the value that pname is set to.
1154 """
1155
1157 """
1158 Specify the pixel zoom factors
1159 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pixelzoom.html}
1160
1161 @type xfactor, yfactor: float
1162 @param xfactor, yfactor: Specify the x and y zoom factors for pixel write operations.
1163 """
1164
1166 """
1167 Specify the diameter of rasterized points
1168 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pointsize.html}
1169
1170 @type size: float
1171 @param size: Specifies the diameter of rasterized points. The initial value is 1.
1172 """
1173
1175 """
1176 Select a polygon rasterization mode
1177 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/polygonmode.html}
1178
1179 @type face: Enumerated constant
1180 @param face: Specifies the polygons that mode applies to.
1181 Must be GL_FRONT for front-facing polygons, GL_BACK for back- facing polygons,
1182 or GL_FRONT_AND_BACK for front- and back-facing polygons.
1183 @type mode: Enumerated constant
1184 @param mode: Specifies how polygons will be rasterized.
1185 The initial value is GL_FILL for both front- and back- facing polygons.
1186 """
1187
1189 """
1190 Set the scale and units used to calculate depth values
1191 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/polygonoffset.html}
1192
1193 @type factor: float
1194 @param factor: Specifies a scale factor that is used to create a variable depth
1195 offset for each polygon. The initial value is 0.
1196 @type units: float
1197 @param units: Is multiplied by an implementation-specific value to create a constant
1198 depth offset. The initial value is 0.
1199 """
1200
1202 """
1203 Set the polygon stippling pattern
1204 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/polygonstipple.html}
1205
1206 @type mask: Buffer object I{type GL_BYTE}
1207 @param mask: Specifies a pointer to a 32x32 stipple pattern that will be unpacked
1208 from memory in the same way that glDrawPixels unpacks pixels.
1209 """
1210
1212 """
1213 Pop the server attribute stack
1214 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushattrib.html}
1215 """
1216
1218 """
1219 Pop the client attribute stack
1220 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushclientattrib.html}
1221 """
1222
1224 """
1225 Pop the current matrix stack
1226 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushmatrix.html}
1227 """
1228
1230 """
1231 Pop the name stack
1232 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushname.html}
1233 """
1234
1235 -def glPrioritizeTextures(n, textures, priorities):
1236 """
1237 Set texture residence priority
1238 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/prioritizetextures.html}
1239
1240 @type n: int
1241 @param n:Specifies the number of textures to be prioritized.
1242 @type textures: Buffer I{type GL_INT}
1243 @param textures: Specifies an array containing the names of the textures to be prioritized.
1244 @type priorities: Buffer I{type GL_FLOAT}
1245 @param priorities: Specifies an array containing the texture priorities. A priority given
1246 in an element of priorities applies to the texture named by the corresponding element of textures.
1247 """
1248
1250 """
1251 Push the server attribute stack
1252 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushattrib.html}
1253
1254 @type mask: Enumerated constant(s)
1255 @param mask: Specifies a mask that indicates which attributes to save.
1256 """
1257
1259 """
1260 Push the client attribute stack
1261 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushclientattrib.html}
1262
1263 @type mask: Enumerated constant(s)
1264 @param mask: Specifies a mask that indicates which attributes to save.
1265 """
1266
1268 """
1269 Push the current matrix stack
1270 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushmatrix.html}
1271 """
1272
1274 """
1275 Push the name stack
1276 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/pushname.html}
1277
1278 @type name: unsigned int
1279 @param name: Specifies a name that will be pushed onto the name stack.
1280 """
1281
1283 """
1284 B{glRasterPos2d, glRasterPos2f, glRasterPos2i, glRasterPos2s, glRasterPos3d,
1285 glRasterPos3f, glRasterPos3i, glRasterPos3s, glRasterPos4d, glRasterPos4f,
1286 glRasterPos4i, glRasterPos4s, glRasterPos2dv, glRasterPos2fv, glRasterPos2iv,
1287 glRasterPos2sv, glRasterPos3dv, glRasterPos3fv, glRasterPos3iv, glRasterPos3sv,
1288 glRasterPos4dv, glRasterPos4fv, glRasterPos4iv, glRasterPos4sv}
1289
1290 Specify the raster position for pixel operations
1291 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/rasterpos.html}
1292
1293 @type x, y, z, w: Depends on function prototype. (z and w for '3' and '4' prototypes only)
1294 @param x, y, z, w: Specify the x,y,z, and w object coordinates (if present) for the
1295 raster position. If function prototype ends in 'v' specifies a pointer to an array of two,
1296 three, or four elements, specifying x, y, z, and w coordinates, respectively.
1297 @note:
1298 If you are drawing to the 3d view with a Scriptlink of a space handler
1299 the zoom level of the panels will scale the glRasterPos by the view matrix.
1300 so a X of 10 will not always offset 10 pixels as you would expect.
1301
1302 To work around this get the scale value of the view matrix and use it to scale your pixel values.
1303
1304 Workaround::
1305
1306 import Blender
1307 from Blender.BGL import *
1308 xval, yval= 100, 40
1309 # Get the scale of the view matrix
1310 viewMatrix = Buffer(GL_FLOAT, 16)
1311 glGetFloatv(GL_MODELVIEW_MATRIX, viewMatrix)
1312 f = 1/viewMatrix[0]
1313 glRasterPos2f(xval*f, yval*f) # Instead of the usual glRasterPos2i(xval, yval)
1314 """
1315
1317 """
1318 Select a color buffer source for pixels.
1319 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/readbuffer.html}
1320
1321 @type mode: Enumerated constant
1322 @param mode: Specifies a color buffer.
1323 """
1324
1325 -def glReadPixels(x, y, width, height, format, type, pixels):
1326 """
1327 Read a block of pixels from the frame buffer
1328 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/readpixels.html}
1329
1330 @type x, y: int
1331 @param x, y:Specify the window coordinates of the first pixel that is read
1332 from the frame buffer. This location is the lower left corner of a rectangular
1333 block of pixels.
1334 @type width, height: int
1335 @param width, height: Specify the dimensions of the pixel rectangle. width and
1336 height of one correspond to a single pixel.
1337 @type format: Enumerated constant
1338 @param format: Specifies the format of the pixel data.
1339 @type type: Enumerated constant
1340 @param type: Specifies the data type of the pixel data.
1341 @type pixels: Buffer object
1342 @param pixels: Returns the pixel data.
1343 """
1344
1345 -def glRect (x1,y1,x2,y2,v1,v2):
1346 """
1347 B{glRectd, glRectf, glRecti, glRects, glRectdv, glRectfv, glRectiv, glRectsv}
1348
1349 Draw a rectangle
1350 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/rect.html}
1351
1352 @type x1, y1: Depends on function prototype. (for non 'v' prototypes only)
1353 @param x1, y1: Specify one vertex of a rectangle
1354 @type x2, y2: Depends on function prototype. (for non 'v' prototypes only)
1355 @param x2, y2: Specify the opposite vertex of the rectangle
1356 @type v1, v2: Depends on function prototype. (for 'v' prototypes only)
1357 @param v1, v2: Specifies a pointer to one vertex of a rectangle and the pointer
1358 to the opposite vertex of the rectangle
1359 """
1360
1362 """
1363 Set rasterization mode
1364 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/rendermode.html}
1365
1366 @type mode: Enumerated constant
1367 @param mode: Specifies the rasterization mode.
1368 """
1369
1371 """
1372 B{glRotated, glRotatef}
1373
1374 Multiply the current matrix by a rotation matrix
1375 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/rotate.html}
1376
1377 @type angle: Depends on function prototype.
1378 @param angle: Specifies the angle of rotation in degrees.
1379 @type x, y, z: Depends on function prototype.
1380 @param x, y, z: Specify the x, y, and z coordinates of a vector respectively.
1381 """
1382
1384 """
1385 B{glScaled, glScalef}
1386
1387 Multiply the current matrix by a general scaling matrix
1388 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/scale.html}
1389
1390 @type x, y, z: Depends on function prototype.
1391 @param x, y, z: Specify scale factors along the x, y, and z axes, respectively.
1392 """
1393
1395 """
1396 Define the scissor box
1397 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/scissor.html}
1398
1399 @type x, y: int
1400 @param x, y: Specify the lower left corner of the scissor box. Initially (0, 0).
1401 @type width, height: int
1402 @param width height: Specify the width and height of the scissor box. When a
1403 GL context is first attached to a window, width and height are set to the
1404 dimensions of that window.
1405 """
1406
1408 """
1409 Establish a buffer for selection mode values
1410 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/selectbuffer.html}
1411
1412 @type size: int
1413 @param size: Specifies the size of buffer
1414 @type buffer: Buffer I{type GL_INT}
1415 @param buffer: Returns the selection data
1416 """
1417
1419 """
1420 Select flat or smooth shading
1421 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/shademodel.html}
1422
1423 @type mode: Enumerated constant
1424 @param mode: Specifies a symbolic value representing a shading technique.
1425 """
1426
1428 """
1429 Set function and reference value for stencil testing
1430 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/stencilfunc.html}
1431
1432 @type func: Enumerated constant
1433 @param func:Specifies the test function.
1434 @type ref: int
1435 @param ref:Specifies the reference value for the stencil test. ref is clamped to
1436 the range [0,2n-1], where n is the number of bitplanes in the stencil buffer.
1437 The initial value is 0.
1438 @type mask: unsigned int
1439 @param mask:Specifies a mask that is ANDed with both the reference value and
1440 the stored stencil value when the test is done. The initial value is all 1's.
1441 """
1442
1444 """
1445 Control the writing of individual bits in the stencil planes
1446 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/stencilmask.html}
1447
1448 @type mask: unsigned int
1449 @param mask: Specifies a bit mask to enable and disable writing of individual bits
1450 in the stencil planes. Initially, the mask is all 1's.
1451 """
1452
1454 """
1455 Set stencil test actions
1456 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/stencilop.html}
1457
1458 @type fail: Enumerated constant
1459 @param fail: Specifies the action to take when the stencil test fails.
1460 The initial value is GL_KEEP.
1461 @type zfail: Enumerated constant
1462 @param zfail: Specifies the stencil action when the stencil test passes, but the
1463 depth test fails. zfail accepts the same symbolic constants as fail.
1464 The initial value is GL_KEEP.
1465 @type zpass: Enumerated constant
1466 @param zpass: Specifies the stencil action when both the stencil test and the
1467 depth test pass, or when the stencil test passes and either there is no depth
1468 buffer or depth testing is not enabled. zpass accepts the same symbolic constants
1469 as fail. The initial value is GL_KEEP.
1470 """
1471
1473 """
1474 B{glTexCoord1d, glTexCoord1f, glTexCoord1i, glTexCoord1s, glTexCoord2d, glTexCoord2f,
1475 glTexCoord2i, glTexCoord2s, glTexCoord3d, glTexCoord3f, glTexCoord3i, glTexCoord3s,
1476 glTexCoord4d, glTexCoord4f, glTexCoord4i, glTexCoord4s, glTexCoord1dv, glTexCoord1fv,
1477 glTexCoord1iv, glTexCoord1sv, glTexCoord2dv, glTexCoord2fv, glTexCoord2iv,
1478 glTexCoord2sv, glTexCoord3dv, glTexCoord3fv, glTexCoord3iv, glTexCoord3sv,
1479 glTexCoord4dv, glTexCoord4fv, glTexCoord4iv, glTexCoord4sv}
1480
1481 Set the current texture coordinates
1482 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/texcoord.html}
1483
1484 @type s, t, r, q: Depends on function prototype. (r and q for '3' and '4' prototypes only)
1485 @param s, t, r, q: Specify s, t, r, and q texture coordinates. Not all parameters are
1486 present in all forms of the command.
1487 @type v: Buffer object. Depends on function prototype. (for 'v' prototypes only)
1488 @param v: Specifies a pointer to an array of one, two, three, or four elements,
1489 which in turn specify the s, t, r, and q texture coordinates.
1490 """
1491
1493 """
1494 B{glTextEnvf, glTextEnvi, glTextEnvfv, glTextEnviv}
1495
1496 Set texture environment parameters
1497 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/texenv.html}
1498
1499 @type target: Enumerated constant
1500 @param target: Specifies a texture environment. Must be GL_TEXTURE_ENV.
1501 @type pname: Enumerated constant
1502 @param pname: Specifies the symbolic name of a single-valued texture environment
1503 parameter. Must be GL_TEXTURE_ENV_MODE.
1504 @type param: Depends on function prototype.
1505 @param param: Specifies a single symbolic constant. If function prototype ends in 'v'
1506 specifies a pointer to a parameter array that contains either a single symbolic
1507 constant or an RGBA color
1508 """
1509
1511 """
1512 B{glTexGend, glTexGenf, glTexGeni, glTexGendv, glTexGenfv, glTexGeniv}
1513
1514 Control the generation of texture coordinates
1515 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/texgen.html}
1516
1517 @type coord: Enumerated constant
1518 @param coord: Specifies a texture coordinate.
1519 @type pname: Enumerated constant
1520 @param pname: Specifies the symbolic name of the texture- coordinate generation function.
1521 @type param: Depends on function prototype.
1522 @param param: Specifies a single-valued texture generation parameter.
1523 If function prototype ends in 'v' specifies a pointer to an array of texture
1524 generation parameters. If pname is GL_TEXTURE_GEN_MODE, then the array must
1525 contain a single symbolic constant. Otherwise, params holds the coefficients
1526 for the texture-coordinate generation function specified by pname.
1527 """
1528
1529 -def glTexImage1D(target, level, internalformat, width, border, format, type, pixels):
1530 """
1531 Specify a one-dimensional texture image
1532 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/teximage1d.html}
1533
1534 @type target: Enumerated constant
1535 @param target: Specifies the target texture.
1536 @type level: int
1537 @param level: Specifies the level-of-detail number. Level 0 is the base image level.
1538 Level n is the nth mipmap reduction image.
1539 @type internalformat: int
1540 @param internalformat: Specifies the number of color components in the texture.
1541 @type width: int
1542 @param width: Specifies the width of the texture image. Must be 2n+2(border) for
1543 some integer n. All implementations support texture images that are at least 64
1544 texels wide. The height of the 1D texture image is 1.
1545 @type border: int
1546 @param border: Specifies the width of the border. Must be either 0 or 1.
1547 @type format: Enumerated constant
1548 @param format: Specifies the format of the pixel data.
1549 @type type: Enumerated constant
1550 @param type: Specifies the data type of the pixel data.
1551 @type pixels: Buffer object.
1552 @param pixels: Specifies a pointer to the image data in memory.
1553 """
1554
1555 -def glTexImage2D(target, level, internalformat, width, height, border, format, type, pixels):
1556 """
1557 Specify a two-dimensional texture image
1558 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/teximage2d.html}
1559
1560 @type target: Enumerated constant
1561 @param target: Specifies the target texture.
1562 @type level: int
1563 @param level: Specifies the level-of-detail number. Level 0 is the base image level.
1564 Level n is the nth mipmap reduction image.
1565 @type internalformat: int
1566 @param internalformat: Specifies the number of color components in the texture.
1567 @type width: int
1568 @param width: Specifies the width of the texture image. Must be 2n+2(border) for
1569 some integer n. All implementations support texture images that are at least 64
1570 texels wide.
1571 @type height: int
1572 @param height: Specifies the height of the texture image. Must be 2m+2(border) for
1573 some integer m. All implementations support texture images that are at least 64
1574 texels high.
1575 @type border: int
1576 @param border: Specifies the width of the border. Must be either 0 or 1.
1577 @type format: Enumerated constant
1578 @param format: Specifies the format of the pixel data.
1579 @type type: Enumerated constant
1580 @param type: Specifies the data type of the pixel data.
1581 @type pixels: Buffer object.
1582 @param pixels: Specifies a pointer to the image data in memory.
1583 """
1584
1586 """
1587 B{glTexParameterf, glTexParameteri, glTexParameterfv, glTexParameteriv}
1588
1589 Set texture parameters
1590 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/texparameter.html}
1591
1592 @type target: Enumerated constant
1593 @param target: Specifies the target texture.
1594 @type pname: Enumerated constant
1595 @param pname: Specifies the symbolic name of a single-valued texture parameter.
1596 @type param: Depends on function prototype.
1597 @param param: Specifies the value of pname. If function prototype ends in 'v' specifies
1598 a pointer to an array where the value or values of pname are stored.
1599 """
1600
1602 """
1603 B{glTranslatef, glTranslated}
1604
1605 Multiply the current matrix by a translation matrix
1606 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/translate.html}
1607
1608 @type x, y, z: Depends on function prototype.
1609 @param x, y, z: Specify the x, y, and z coordinates of a translation vector.
1610 """
1611
1613 """
1614 B{glVertex2d, glVertex2f, glVertex2i, glVertex2s, glVertex3d, glVertex3f, glVertex3i,
1615 glVertex3s, glVertex4d, glVertex4f, glVertex4i, glVertex4s, glVertex2dv, glVertex2fv,
1616 glVertex2iv, glVertex2sv, glVertex3dv, glVertex3fv, glVertex3iv, glVertex3sv, glVertex4dv,
1617 glVertex4fv, glVertex4iv, glVertex4sv}
1618
1619 Specify a vertex
1620 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/vertex.html}
1621
1622 @type x, y, z, w: Depends on function prototype (z and w for '3' and '4' prototypes only)
1623 @param x, y, z, w: Specify x, y, z, and w coordinates of a vertex. Not all parameters
1624 are present in all forms of the command.
1625 @type v: Buffer object. Depends of function prototype (for 'v' prototypes only)
1626 @param v: Specifies a pointer to an array of two, three, or four elements. The
1627 elements of a two-element array are x and y; of a three-element array, x, y, and z;
1628 and of a four-element array, x, y, z, and w.
1629 """
1630
1632 """
1633 Set the viewport
1634 @see: U{www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/viewport.html}
1635
1636 @type x, y: int
1637 @param x, y: Specify the lower left corner of the viewport rectangle,
1638 in pixels. The initial value is (0,0).
1639 @type width, height: int
1640 @param width, height: Specify the width and height of the viewport. When a GL context
1641 is first attached to a window, width and height are set to the dimensions of that window.
1642 """
1643
1645 """
1646 Set up a perspective projection matrix.
1647 @see: U{http://biology.ncsa.uiuc.edu/cgi-bin/infosrch.cgi?cmd=getdoc&coll=0650&db=bks&fname=/SGI_Developer/OpenGL_RM/ch06.html#id5577288}
1648
1649 @type fovY: double
1650 @param fovY: Specifies the field of view angle, in degrees, in the y direction.
1651 @type aspect: double
1652 @param aspect: Specifies the aspect ratio that determines the field of view in the x direction.
1653 The aspect ratio is the ratio of x (width) to y (height).
1654 @type zNear: double
1655 @param zNear: Specifies the distance from the viewer to the near clipping plane (always positive).
1656 @type zFar: double
1657 @param zFar: Specifies the distance from the viewer to the far clipping plane (always positive).
1658 """
1659
1660 -def gluLookAt(eyex, eyey, eyez, centerx, centery, centerz, upx, upy, upz):
1661 """
1662 Define a viewing transformation
1663 @see: U{http://biology.ncsa.uiuc.edu/cgi-bin/infosrch.cgi?cmd=getdoc&coll=0650&db=bks&fname=/SGI_Developer/OpenGL_RM/ch06.html#id5573042}
1664
1665 @type eyex, eyey, eyez: double
1666 @param eyex, eyey, eyez: Specifies the position of the eye point.
1667 @type centerx, centery, centerz: double
1668 @param centerx, centery, centerz: Specifies the position of the reference point.
1669 @type upx, upy, upz: double
1670 @param upx, upy, upz: Specifies the direction of the up vector.
1671 """
1672
1674 """
1675 Define a 2-D orthographic projection matrix
1676 @see: U{http://biology.ncsa.uiuc.edu/cgi-bin/infosrch.cgi?cmd=getdoc&coll=0650&db=bks&fname=/SGI_Developer/OpenGL_RM/ch06.html#id5578074}
1677
1678 @type left, right: double
1679 @param left, right: Specify the coordinates for the left and right vertical clipping planes.
1680 @type bottom, top: double
1681 @param bottom, top: Specify the coordinates for the bottom and top horizontal clipping planes.
1682 """
1683
1685 """
1686 Define a picking region
1687 @see: U{http://biology.ncsa.uiuc.edu/cgi-bin/infosrch.cgi?cmd=getdoc&coll=0650&db=bks&fname=/SGI_Developer/OpenGL_RM/ch06.html#id5578074}
1688
1689 @type x, y: double
1690 @param x, y: Specify the center of a picking region in window coordinates.
1691 @type width, height: double
1692 @param width, height: Specify the width and height, respectively, of the picking region in window coordinates.
1693 @type viewport: Buffer object. [int]
1694 @param viewport: Specifies the current viewport.
1695 """
1696
1697 -def gluProject(objx, objy, objz, modelMatrix, projMatrix, viewport, winx, winy, winz):
1698 """
1699 Map object coordinates to window coordinates.
1700 @see: U{http://biology.ncsa.uiuc.edu/cgi-bin/infosrch.cgi?cmd=getdoc&coll=0650&db=bks&fname=/SGI_Developer/OpenGL_RM/ch06.html#id5578074}
1701
1702 @type objx, objy, objz: double
1703 @param objx, objy, objz: Specify the object coordinates.
1704 @type modelMatrix: Buffer object. [double]
1705 @param modelMatrix: Specifies the current modelview matrix (as from a glGetDoublev call).
1706 @type projMatrix: Buffer object. [double]
1707 @param projMatrix: Specifies the current projection matrix (as from a glGetDoublev call).
1708 @type viewport: Buffer object. [int]
1709 @param viewport: Specifies the current viewport (as from a glGetIntegerv call).
1710 @type winx, winy, winz: Buffer object. [double]
1711 @param winx, winy, winz: Return the computed window coordinates.
1712 """
1713
1714 -def gluUnProject(winx, winy, winz, modelMatrix, projMatrix, viewport, objx, objy, objz):
1715 """
1716 Map object coordinates to window
1717 coordinates.
1718 @see: U{http://biology.ncsa.uiuc.edu/cgi-bin/infosrch.cgi?cmd=getdoc&coll=0650&db=bks&fname=/SGI_Developer/OpenGL_RM/ch06.html#id5582204}
1719
1720 @type winx, winy, winz: double
1721 @param winx, winy, winz: Specify the window coordinates to be mapped.
1722 @type modelMatrix: Buffer object. [double]
1723 @param modelMatrix: Specifies the current modelview matrix (as from a glGetDoublev call).
1724 @type projMatrix: Buffer object. [double]
1725 @param projMatrix: Specifies the current projection matrix (as from a glGetDoublev call).
1726 @type viewport: Buffer object. [int]
1727 @param viewport: Specifies the current viewport (as from a glGetIntegerv call).
1728 @type objx, objy, objz: Buffer object. [double]
1729 @param objx, objy, objz: Return the computed object coordinates.
1730 """
1731
1733 """
1734 The Buffer object is simply a block of memory that is delineated and initialized by the
1735 user. Many OpenGL functions return data to a C-style pointer, however, because this
1736 is not possible in python the Buffer object can be used to this end. Wherever pointer
1737 notation is used in the OpenGL functions the Buffer object can be used in it's BGL
1738 wrapper. In some instances the Buffer object will need to be initialized with the template
1739 parameter, while in other instances the user will want to create just a blank buffer
1740 which will be zeroed by default.
1741
1742 Example with Buffer::
1743 import Blender
1744 from Blender import BGL
1745 myByteBuffer = BGL.Buffer(BGL.GL_BYTE, [32,32])
1746 BGL.glGetPolygonStipple(myByteBuffer)
1747 print myByteBuffer.dimensions
1748 print myByteBuffer.list
1749 sliceBuffer = myByteBuffer[0:16]
1750 print sliceBuffer
1751
1752 @ivar list: The contents of the Buffer.
1753 @ivar dimensions: The size of the Buffer.
1754 """
1755
1756 - def __init__(type, dimensions, template = None):
1757 """
1758 This will create a new Buffer object for use with other BGL OpenGL commands.
1759 Only the type of argument to store in the buffer and the dimensions of the buffer
1760 are necessary. Buffers are zeroed by default unless a template is supplied, in
1761 which case the buffer is initialized to the template.
1762
1763 @type type: int
1764 @param type: The format to store data in. The type should be one of
1765 GL_BYTE, GL_SHORT, GL_INT, or GL_FLOAT.
1766 @type dimensions: An int or sequence object specifying the dimensions of the buffer.
1767 @param dimensions: If the dimensions are specified as an int a linear array will
1768 be created for the buffer. If a sequence is passed for the dimensions, the buffer
1769 becomes n-Dimensional, where n is equal to the number of parameters passed in the
1770 sequence. Example: [256,2] is a two- dimensional buffer while [256,256,4] creates
1771 a three- dimensional buffer. You can think of each additional dimension as a sub-item
1772 of the dimension to the left. i.e. [10,2] is a 10 element array each with 2 sub-items.
1773 [(0,0), (0,1), (1,0), (1,1), (2,0), ...] etc.
1774 @type template: A python sequence object (optional)
1775 @param template: A sequence of matching dimensions which will be used to initialize
1776 the Buffer. If a template is not passed in all fields will be initialized to 0.
1777 @rtype: Buffer object
1778 @return: The newly created buffer as a PyObject.
1779 """
1780