0
# Images and Textures
1

2
Image loading, texture management, and texture atlases.
3

4
## Quick Reference
5

6
```python
7
# Load image
8
image = pyglet.image.load('file.png')
9
anim = pyglet.image.load_animation('file.gif')
10

11
# Get texture
12
texture = image.get_texture()
13

14
# Transform
15
flipped = image.get_transform(flip_x=False, flip_y=True, rotate=90)
16

17
# Draw
18
image.blit(x=100, y=100)
19

20
# Create from data
21
image = pyglet.image.ImageData(width, height, 'RGBA', pixel_data, pitch=None)
22

23
# Texture atlas
24
atlas = pyglet.image.atlas.TextureAtlas(1024, 1024)
25
region = atlas.add(image)
26
```
27

28
## Loading Functions
29

30
```python
31
def pyglet.image.load(filename: str, file=None, decoder=None) -> AbstractImage
32
def pyglet.image.load_animation(filename: str, file=None, decoder=None) -> Animation
33
def pyglet.image.create(width: int, height: int, pattern=None) -> ImageData
34
def pyglet.image.get_max_texture_size() -> int
35
def pyglet.image.get_max_array_texture_layers() -> int
36
```
37

38
## Image Classes
39

40
```python
41
class pyglet.image.AbstractImage:
42
    width, height: int
43
    anchor_x, anchor_y: int
44

45
    def get_image_data() -> ImageData
46
    def get_texture() -> Texture
47
    def get_mipmapped_texture() -> Texture
48
    def get_region(x, y, width, height) -> AbstractImage
49
    def save(filename, file=None, encoder=None)
50
    def get_transform(flip_x=False, flip_y=False, rotate=0) -> AbstractImage
51
    def blit(x, y, z=0)
52

53
class pyglet.image.ImageData(AbstractImage):
54
    """Raw pixel data"""
55
    __init__(width, height, fmt, data, pitch=None)
56

57
    format: str  # 'RGB', 'RGBA', etc.
58
    pitch: int  # Bytes per row
59

60
    def get_data(fmt=None, pitch=None) -> bytes
61
    def set_data(fmt, pitch, data)
62
    def set_mipmap_data(level, data)
63

64
class pyglet.image.Texture(AbstractImage):
65
    """OpenGL texture"""
66
    id: int  # GL texture ID
67
    target: int  # GL_TEXTURE_2D, etc.
68

69
    def blit(x, y, z=0, width=None, height=None)
70
```
71

72
## Texture Atlas
73

74
```python
75
class pyglet.image.atlas.TextureAtlas:
76
    """Pack multiple images into single texture"""
77
    __init__(width=2048, height=2048)
78

79
    def add(img: AbstractImage) -> TextureRegion
80
    # Returns None if doesn't fit
81

82
# Atlas bin (manages multiple atlases)
83
class pyglet.image.atlas.TextureBin:
84
    """Manages multiple texture atlases"""
85
    __init__(texture_width=2048, texture_height=2048)
86

87
    def add(img: AbstractImage) -> TextureRegion
88
```
89

90
## Animations
91

92
```python
93
class pyglet.image.Animation:
94
    frames: list  # AnimationFrame objects
95

96
    @classmethod
97
    def from_image_sequence(images, duration, loop=True) -> Animation
98

99
    def get_duration() -> float
100
    def get_transform(flip_x=False, flip_y=False, rotate=0) -> Animation
101

102
class pyglet.image.AnimationFrame:
103
    image: AbstractImage
104
    duration: float  # Seconds
105
```
106

107
## Image Patterns
108

109
```python
110
# Solid color
111
pattern = pyglet.image.SolidColorImagePattern(color=(255, 255, 255, 255))
112
image = pyglet.image.create(100, 100, pattern)
113

114
# Checkerboard
115
pattern = pyglet.image.CheckerImagePattern(colors=((255,255,255,255), (0,0,0,255)))
116
image = pyglet.image.create(100, 100, pattern)
117
```
118

119
## Examples
120

121
### Load and Display
122
```python
123
image = pyglet.image.load('sprite.png')
124

125
@window.event
126
def on_draw():
127
    window.clear()
128
    image.blit(100, 100)
129
```
130

131
### Texture Coordinates
132
```python
133
texture = image.get_texture()
134
# Access texture coordinates for sprite/shader use
135
tex_coords = texture.tex_coords  # (u0, v0, u1, v1, ...)
136
```
137

138
### Save Screenshot
139
```python
140
@window.event
141
def on_key_press(symbol, modifiers):
142
    if symbol == pyglet.window.key.F12:
143
        pyglet.image.get_buffer_manager().get_color_buffer().save('screenshot.png')
144
```
145

146
### Texture Atlas Usage
147
```python
148
# Create atlas
149
atlas = pyglet.image.atlas.TextureAtlas(1024, 1024)
150

151
# Add images
152
images = [pyglet.image.load(f'sprite{i}.png') for i in range(10)]
153
regions = [atlas.add(img) for img in images]
154

155
# Use with sprites
156
sprites = [pyglet.sprite.Sprite(region, x=i*50, y=100) for i, region in enumerate(regions)]
157
```
158

159
### Animated Sprite
160
```python
161
# From GIF
162
anim = pyglet.image.load_animation('explosion.gif')
163
sprite = pyglet.sprite.Sprite(anim, x=100, y=100)
164

165
# From image sequence
166
frames = [pyglet.image.load(f'frame{i:02d}.png') for i in range(10)]
167
anim = pyglet.image.Animation.from_image_sequence(frames, duration=0.1, loop=True)
168
sprite = pyglet.sprite.Sprite(anim)
169
```
170

171
### Image Transformations
172
```python
173
# Flip
174
flipped = image.get_transform(flip_y=True)
175

176
# Rotate (0, 90, 180, 270 only)
177
rotated = image.get_transform(rotate=90)
178

179
# Combine
180
transformed = image.get_transform(flip_x=True, rotate=180)
181
```
182

183
## Performance Tips
184

185
1. **Use texture atlases**: Reduces texture switches
186
2. **Power-of-2 textures**: Better GPU performance (not required on modern GPUs)
187
3. **Mipmapping**: Use for scaled textures
188
4. **Minimize blits**: Use sprites with batching instead
189
5. **Preload images**: Load during init, not per-frame
190

191
## Common Issues
192

193
1. **Image upside down**: Use `get_transform(flip_y=True)`
194
2. **Max texture size**: Check with `get_max_texture_size()`
195
3. **Atlas full**: Returns None, need new atlas or larger size
196
4. **Anchor point**: Default (0,0) is bottom-left
197
5. **Pixel formats**: 'RGB', 'RGBA', 'BGRA', 'BGR', 'ALPHA', 'LUMINANCE'
198