0
# Graphics Rendering
1

2
Low-level graphics rendering with batched drawing, shader programs, vertex lists, and OpenGL state management.
3

4
## Quick Reference
5

6
```python
7
# Batching (recommended)
8
batch = pyglet.graphics.Batch()
9
sprite = pyglet.sprite.Sprite(img, batch=batch)
10
batch.draw()
11

12
# Groups (state management)
13
group = pyglet.graphics.Group(order=0, parent=None)
14
TextureGroup(texture, order=0, parent=None)
15
ShaderGroup(program, order=0, parent=None)
16

17
# Custom shaders
18
vert = pyglet.graphics.shader.Shader(vert_source, 'vertex')
19
frag = pyglet.graphics.shader.Shader(frag_source, 'fragment')
20
program = pyglet.graphics.shader.ShaderProgram(vert, frag)
21

22
# Vertex lists
23
vlist = program.vertex_list(count, mode, batch=batch, group=group,
24
                            position=('f', data), colors=('f', data))
25
```
26

27
## Batch Rendering
28

29
```python
30
class pyglet.graphics.Batch:
31
    __init__()
32
    def draw()  # Render all
33
    def invalidate()  # Mark for update
34
    def draw_subset(vertex_lists)  # Draw specific items (inefficient)
35

36
# Default batch
37
pyglet.graphics.get_default_batch() -> Batch
38
```
39

40
## Groups
41

42
```python
43
class pyglet.graphics.Group:
44
    __init__(order=0, parent=None)
45

46
    order: int  # Draw order (lower first)
47
    parent: Group | None
48
    visible: bool
49
    batches: tuple  # Read-only
50

51
    def set_state()  # Apply GL state
52
    def unset_state()  # Restore GL state
53

54
class TextureGroup(Group):
55
    __init__(texture, order=0, parent=None)
56

57
class ShaderGroup(Group):
58
    __init__(program, order=0, parent=None)
59
```
60

61
## Shaders
62

63
```python
64
class pyglet.graphics.shader.Shader:
65
    __init__(source_string: str, shader_type: str)
66
    # shader_type: 'vertex', 'fragment', 'geometry', 'compute',
67
    #              'tesscontrol', 'tessevaluation'
68
    def delete()
69

70
class pyglet.graphics.shader.ShaderProgram:
71
    __init__(*shaders)
72

73
    # Properties
74
    id: int  # OpenGL program ID
75
    uniforms: dict
76
    uniform_blocks: dict
77
    attributes: dict
78

79
    # Methods
80
    def use()
81
    def stop()
82
    def __setitem__(key, value)  # Set uniform: program['color'] = (1,0,0)
83
    def __getitem__(key)  # Get uniform
84
    def delete()
85

86
    # Create vertex lists
87
    def vertex_list(count, mode, batch=None, group=None, **data)
88
    def vertex_list_indexed(count, mode, indices, batch=None, group=None, **data)
89
    def vertex_list_instanced(count, mode, instance_attributes, batch=None, group=None, **data)
90
    def vertex_list_instanced_indexed(count, mode, indices, instance_attributes,
91
                                      batch=None, group=None, **data)
92

93
class pyglet.graphics.shader.ComputeShaderProgram:
94
    __init__(source: str)
95
```
96

97
**Shader Defaults:**
98

99
```python
100
pyglet.graphics.get_default_shader() -> ShaderProgram
101
pyglet.graphics.get_default_blit_shader() -> ShaderProgram
102
```
103

104
## Vertex Attribute Format
105

106
Format: `(type_string, data_array)`
107

108
**Type String:** `'<count><type>'`
109
- Count: 1-4 (components per vertex)
110
- Type: `f` (float), `d` (double), `B` (ubyte), `i` (int), etc.
111

112
**Common Attributes:**
113
```python
114
position=('f', [x1, y1, x2, y2, ...])  # 2D positions
115
position=('f', [x1, y1, z1, x2, y2, z2, ...])  # 3D positions
116
colors=('B', [r1, g1, b1, a1, r2, g2, b2, a2, ...])  # RGBA bytes
117
colors=('f', [r1, g1, b1, a1, r2, g2, b2, a2, ...])  # RGBA floats
118
tex_coords=('f', [u1, v1, u2, v2, ...])  # Texture coordinates
119
normals=('f', [nx1, ny1, nz1, nx2, ny2, nz2, ...])  # Normals
120
```
121

122
## Vertex Lists
123

124
```python
125
class pyglet.graphics.VertexList:
126
    def draw(mode)
127
    def delete()
128
    def resize(count, index_count=None)
129

130
class pyglet.graphics.IndexedVertexList:
131
    indices: list  # Index buffer (read/write)
132
    def draw(mode)
133
    def delete()
134
    def resize(count, index_count)
135
```
136

137
## Custom Shader Example
138

139
```python
140
from pyglet.gl import GL_TRIANGLES
141
from pyglet.graphics import shader
142

143
vertex_source = """
144
#version 330 core
145
in vec2 position;
146
in vec3 colors;
147
out vec3 vertex_colors;
148

149
void main() {
150
    gl_Position = vec4(position, 0.0, 1.0);
151
    vertex_colors = colors;
152
}
153
"""
154

155
fragment_source = """
156
#version 330 core
157
in vec3 vertex_colors;
158
out vec4 fragColor;
159

160
void main() {
161
    fragColor = vec4(vertex_colors, 1.0);
162
}
163
"""
164

165
# Create program
166
vert_shader = shader.Shader(vertex_source, 'vertex')
167
frag_shader = shader.Shader(fragment_source, 'fragment')
168
program = shader.ShaderProgram(vert_shader, frag_shader)
169

170
# Create vertex list
171
vertices = program.vertex_list(3, GL_TRIANGLES,
172
    position=('f', (0, 0.5, -0.5, -0.5, 0.5, -0.5)),
173
    colors=('f', (1, 0, 0, 0, 1, 0, 0, 0, 1))
174
)
175

176
@window.event
177
def on_draw():
178
    window.clear()
179
    vertices.draw(GL_TRIANGLES)
180
```
181

182
## Performance Tips
183

184
1. **Use batching**: Group all objects in Batch
185
2. **Minimize state changes**: Group by texture/shader
186
3. **Use indexed vertices**: Reduce duplicate vertex data
187
4. **Persistent buffers**: For frequently updated data (GL 4.4+)
188
5. **Avoid draw_subset**: Inefficient, use visibility or separate batches
189

190
For complete reference including buffer objects, uniform blocks, and advanced features, see original pyglet documentation.
191