0
# PyOpenGL
1

2
A comprehensive ctypes-based OpenGL binding for Python, providing complete access to OpenGL, GLU, and GLUT functionality. PyOpenGL enables 3D graphics programming with support for OpenGL versions 1.0 through 4.6, extensive vendor-specific extensions, and robust array handling for high-performance graphics applications.
3

4
## Package Information
5

6
- **Package Name**: PyOpenGL
7
- **Language**: Python
8
- **Installation**: `pip install PyOpenGL PyOpenGL_accelerate`
9

10
## Core Imports
11

12
```python
13
import OpenGL
14
```
15

16
Common import patterns for OpenGL functionality:
17

18
```python
19
from OpenGL.GL import *
20
from OpenGL.GLU import *
21
from OpenGL.GLUT import *
22
```
23

24
Namespace imports for cleaner code:
25

26
```python
27
from OpenGL import GL, GLU, GLUT
28
import OpenGL.GL as gl
29
```
30

31
Array and utility imports:
32

33
```python
34
from OpenGL.arrays import vbo
35
from OpenGL.GL import shaders
36
from OpenGL.error import GLError
37
```
38

39
## Basic Usage
40

41
```python
42
import pygame
43
from OpenGL.GL import *
44
from OpenGL.GLU import *
45
from OpenGL.GLUT import *
46
import numpy as np
47

48
# Initialize display with OpenGL context
49
pygame.init()
50
display = (800, 600)
51
pygame.display.set_mode(display, pygame.DOUBLEBUF | pygame.OPENGL)
52

53
# Set up 3D perspective
54
gluPerspective(45, (display[0]/display[1]), 0.1, 50.0)
55
glTranslatef(0.0, 0.0, -5)
56

57
# Basic rendering setup
58
glEnable(GL_DEPTH_TEST)
59
glClearColor(0.0, 0.0, 0.0, 1.0)
60

61
# Simple triangle vertices
62
vertices = np.array([
63
    [0.0, 1.0, 0.0],   # Top vertex
64
    [-1.0, -1.0, 0.0], # Bottom left
65
    [1.0, -1.0, 0.0]   # Bottom right
66
], dtype=np.float32)
67

68
# Render loop
69
running = True
70
while running:
71
    for event in pygame.event.get():
72
        if event.type == pygame.QUIT:
73
            running = False
74
    
75
    # Clear buffers
76
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
77
    
78
    # Draw triangle
79
    glBegin(GL_TRIANGLES)
80
    for vertex in vertices:
81
        glVertex3fv(vertex)
82
    glEnd()
83
    
84
    pygame.display.flip()
85
    pygame.time.wait(10)
86

87
pygame.quit()
88
```
89

90
## Architecture
91

92
PyOpenGL's modular architecture provides complete OpenGL access with Python-friendly enhancements:
93

94
- **OpenGL.GL**: Core OpenGL functions organized by version (1.0-4.6) with extensive extensions
95
- **OpenGL.GLU**: Utility functions for common operations (perspective, tessellation, quadrics)
96
- **OpenGL.GLUT**: Window management and user interface toolkit
97
- **OpenGL.arrays**: Unified array handling supporting NumPy, ctypes, and Python built-ins
98
- **OpenGL.platform**: Cross-platform abstraction for context creation and library loading
99
- **OpenGL.raw**: Low-level ctypes bindings providing direct access to native OpenGL functions
100

101
## Configuration
102

103
```python { .api }
104
# Global configuration flags
105
ERROR_CHECKING: bool  # Enable/disable error checking (default: True)
106
USE_ACCELERATE: bool  # Use Cython acceleration if available (default: True)
107
CONTEXT_CHECKING: bool  # Validate OpenGL context on calls (default: False)
108
ERROR_ON_COPY: bool  # Prevent implicit data copying (default: False)
109
STORE_POINTERS: bool  # Memory management for arrays (default: True)
110
FULL_LOGGING: bool  # Comprehensive call logging (default: False)
111
```
112

113
## Capabilities
114

115
### Core OpenGL Functions
116

117
Complete OpenGL API including drawing primitives, state management, transformations, texturing, lighting, and vertex operations. Supports all OpenGL versions from 1.0 through 4.6 with comprehensive extension coverage.
118

119
```python { .api }
120
def glBegin(mode): ...
121
def glEnd(): ...
122
def glVertex3f(x: float, y: float, z: float): ...
123
def glColor3f(red: float, green: float, blue: float): ...
124
def glEnable(cap): ...
125
def glDisable(cap): ...
126
def glClear(mask): ...
127
def glLoadIdentity(): ...
128
def glTranslatef(x: float, y: float, z: float): ...
129
def glRotatef(angle: float, x: float, y: float, z: float): ...
130
```
131

132
[Core OpenGL](./core-opengl.md)
133

134
### OpenGL Utility Functions (GLU)
135

136
High-level utility functions for perspective projection, object rendering, tessellation, and coordinate transformations that simplify common OpenGL operations.
137

138
```python { .api }
139
def gluPerspective(fovy: float, aspect: float, zNear: float, zFar: float): ...
140
def gluLookAt(eyeX: float, eyeY: float, eyeZ: float, 
141
              centerX: float, centerY: float, centerZ: float,
142
              upX: float, upY: float, upZ: float): ...
143
def gluSphere(quad: GLUquadric, radius: float, slices: int, stacks: int): ...
144
def gluNewQuadric() -> GLUquadric: ...
145
```
146

147
[GLU Utilities](./glu-utilities.md)
148

149
### Window Management (GLUT)
150

151
Complete window management and event handling system for creating OpenGL applications with keyboard, mouse, and timer support.
152

153
```python { .api }
154
def glutInit(argv: list): ...
155
def glutCreateWindow(title: str) -> int: ...
156
def glutDisplayFunc(func): ...
157
def glutMainLoop(): ...
158
def glutInitDisplayMode(mode): ...
159
def glutSwapBuffers(): ...
160
```
161

162
[GLUT Window Management](./glut-window.md)
163

164
### Array Handling
165

166
Unified array interface supporting NumPy arrays, Python lists, ctypes arrays, and other data formats with automatic conversion and memory management.
167

168
```python { .api }
169
class VBO:
170
    def __init__(self, data, usage=GL_STATIC_DRAW, target=GL_ARRAY_BUFFER): ...
171
    def bind(self): ...
172
    def unbind(self): ...
173
    def delete(self): ...
174
    def __enter__(self): ...
175
    def __exit__(self, exc_type, exc_val, exc_tb): ...
176
```
177

178
[Array Operations](./array-operations.md)
179

180
### Shader Programming
181

182
Modern OpenGL shader support with compilation, linking, and program management utilities for vertex and fragment shaders.
183

184
```python { .api }
185
def compileShader(source: str, shaderType) -> int: ...
186
def compileProgram(*shaders) -> int: ...
187
def glUseProgram(program: int): ...
188
def glGetUniformLocation(program: int, name: str) -> int: ...
189
def glUniform1f(location: int, value: float): ...
190
```
191

192
[Shaders](./shaders.md)
193

194
### Error Handling
195

196
Comprehensive error detection and reporting with OpenGL-specific exceptions, context validation, and debugging utilities.
197

198
```python { .api }
199
class GLError(Exception):
200
    def __init__(self, err, result, cArguments, name): ...
201

202
class NoContext(Exception): ...
203
class CopyError(Exception): ...
204

205
def glGetError() -> int: ...
206
```
207

208
[Error Handling](./error-handling.md)
209

210
### Platform Integration
211

212
Cross-platform support for Windows (WGL), Linux/X11 (GLX), macOS (CGL), and embedded systems (EGL) with automatic platform detection.
213

214
```python { .api }
215
def setPlatform(key: str): ...
216
def GetCurrentPlatform(): ...
217
```
218

219
[Platform Support](./platform-support.md)