0
# Extension Functions
1

2
Advanced mathematical and utility functions that extend PyGLM's core capabilities with specialized algorithms and operations for graphics programming, procedural generation, and scientific computing.
3

4
## Capabilities
5

6
### Color Space Functions
7

8
Functions for converting between different color spaces and gamma correction.
9

10
```python { .api }
11
def convertLinearToSRGB(color):
12
    """
13
    Convert linear RGB color to sRGB color space.
14

15
    Args:
16
        color: Linear RGB color (vec3 or vec4)
17

18
    Returns:
19
        sRGB color with gamma correction applied
20

21
    Example:
22
        linear_color = glm.vec3(0.5, 0.25, 0.75)
23
        srgb_color = glm.convertLinearToSRGB(linear_color)
24
    """
25

26
def convertSRGBToLinear(color):
27
    """
28
    Convert sRGB color to linear RGB color space.
29

30
    Args:
31
        color: sRGB color (vec3 or vec4)
32

33
    Returns:
34
        Linear RGB color with gamma correction removed
35

36
    Example:
37
        srgb_color = glm.vec3(0.73, 0.54, 0.88)
38
        linear_color = glm.convertSRGBToLinear(srgb_color)
39
    """
40
```
41

42
### ULP Functions
43

44
Functions for ultra-low precision floating-point operations and comparison.
45

46
```python { .api }
47
def next_float(x):
48
    """
49
    Return the next representable floating-point value.
50

51
    Args:
52
        x: Input float value (scalar or vector)
53

54
    Returns:
55
        Next representable float value greater than x
56
    """
57

58
def prev_float(x):
59
    """
60
    Return the previous representable floating-point value.
61

62
    Args:
63
        x: Input float value (scalar or vector)
64

65
    Returns:
66
        Previous representable float value less than x
67
    """
68

69
def float_distance(x, y):
70
    """
71
    Calculate the distance between two floats in ULPs (Units in Last Place).
72

73
    Args:
74
        x: First float value (scalar or vector)
75
        y: Second float value (same type as x)
76

77
    Returns:
78
        Distance in ULPs between x and y
79
    """
80
```
81

82
### Rounding Extensions
83

84
Advanced rounding functions for alignment and power-of-two operations.
85

86
```python { .api }
87
def ceilMultiple(value, multiple):
88
    """
89
    Round up to the nearest multiple of a given value.
90

91
    Args:
92
        value: Value to round up (scalar or vector)
93
        multiple: Multiple to round to (scalar or vector)
94

95
    Returns:
96
        Smallest multiple >= value
97

98
    Example:
99
        ceilMultiple(13, 8)  # 16
100
        ceilMultiple(glm.vec2(7, 15), 4)  # vec2(8, 16)
101
    """
102

103
def floorMultiple(value, multiple):
104
    """
105
    Round down to the nearest multiple of a given value.
106

107
    Args:
108
        value: Value to round down (scalar or vector)
109
        multiple: Multiple to round to (scalar or vector)
110

111
    Returns:
112
        Largest multiple <= value
113
    """
114

115
def roundMultiple(value, multiple):
116
    """
117
    Round to the nearest multiple of a given value.
118

119
    Args:
120
        value: Value to round (scalar or vector)
121
        multiple: Multiple to round to (scalar or vector)
122

123
    Returns:
124
        Nearest multiple to value
125
    """
126

127
def ceilPowerOfTwo(value):
128
    """
129
    Round up to the nearest power of two.
130

131
    Args:
132
        value: Value to round up (scalar or vector)
133

134
    Returns:
135
        Smallest power of two >= value
136

137
    Example:
138
        ceilPowerOfTwo(5)  # 8
139
        ceilPowerOfTwo(glm.vec2(3, 7))  # vec2(4, 8)
140
    """
141

142
def floorPowerOfTwo(value):
143
    """
144
    Round down to the nearest power of two.
145

146
    Args:
147
        value: Value to round down (scalar or vector)
148

149
    Returns:
150
        Largest power of two <= value
151
    """
152

153
def roundPowerOfTwo(value):
154
    """
155
    Round to the nearest power of two.
156

157
    Args:
158
        value: Value to round (scalar or vector)
159

160
    Returns:
161
        Nearest power of two to value
162
    """
163
```
164

165
### Norm Functions
166

167
Functions for calculating various mathematical norms and distances.
168

169
```python { .api }
170
def l1Norm(vec):
171
    """
172
    Calculate L1 norm (Manhattan distance).
173

174
    Args:
175
        vec: Input vector
176

177
    Returns:
178
        Sum of absolute values of components
179

180
    Example:
181
        l1Norm(glm.vec3(3, -4, 5))  # 12 (3 + 4 + 5)
182
    """
183

184
def l2Norm(vec):
185
    """
186
    Calculate L2 norm (Euclidean distance).
187

188
    Args:
189
        vec: Input vector
190

191
    Returns:
192
        Square root of sum of squared components (same as length())
193
    """
194

195
def lMaxNorm(vec):
196
    """
197
    Calculate L-infinity norm (maximum norm).
198

199
    Args:
200
        vec: Input vector
201

202
    Returns:
203
        Maximum absolute value of components
204

205
    Example:
206
        lMaxNorm(glm.vec3(3, -7, 2))  # 7
207
    """
208

209
def lxNorm(vec, degree):
210
    """
211
    Calculate Lx norm for arbitrary degree.
212

213
    Args:
214
        vec: Input vector
215
        degree: Norm degree (x in Lx)
216

217
    Returns:
218
        x-th root of sum of components raised to x-th power
219
    """
220
```
221

222
### Polar Coordinates
223

224
Functions for converting between Cartesian and polar coordinate systems.
225

226
```python { .api }
227
def euclidean(polar):
228
    """
229
    Convert polar coordinates to Cartesian coordinates.
230

231
    Args:
232
        polar: Polar coordinates (vec2: radius, angle)
233

234
    Returns:
235
        Cartesian coordinates (vec2: x, y)
236

237
    Example:
238
        cartesian = glm.euclidean(glm.vec2(5.0, glm.radians(45)))
239
        # Returns vec2(3.535, 3.535)
240
    """
241

242
def polar(euclidean):
243
    """
244
    Convert Cartesian coordinates to polar coordinates.
245

246
    Args:
247
        euclidean: Cartesian coordinates (vec2: x, y)
248

249
    Returns:
250
        Polar coordinates (vec2: radius, angle)
251

252
    Example:
253
        polar_coords = glm.polar(glm.vec2(3, 4))
254
        # Returns vec2(5.0, 0.927) - radius=5, angle~53°
255
    """
256
```
257

258
### Vector Orientation
259

260
Functions for calculating vector orientations and rotations.
261

262
```python { .api }
263
def orientation(forward, up):
264
    """
265
    Calculate orientation matrix from forward and up vectors.
266

267
    Args:
268
        forward: Forward direction vector (vec3)
269
        up: Up direction vector (vec3)
270

271
    Returns:
272
        3x3 orientation matrix
273

274
    Example:
275
        forward = glm.vec3(0, 0, -1)  # Looking down negative Z
276
        up = glm.vec3(0, 1, 0)        # Y is up
277
        orient = glm.orientation(forward, up)
278
    """
279
```
280

281
### Projection Functions
282

283
Advanced projection and unprojection functions for 3D graphics.
284

285
```python { .api }
286
def project(obj, model, proj, viewport):
287
    """
288
    Project 3D coordinates to screen coordinates.
289

290
    Args:
291
        obj: 3D object coordinates (vec3)
292
        model: Model matrix (mat4)
293
        proj: Projection matrix (mat4)
294
        viewport: Viewport parameters (vec4: x, y, width, height)
295

296
    Returns:
297
        Screen coordinates (vec3: x, y, depth)
298
    """
299

300
def projectNO(obj, model, proj, viewport):
301
    """
302
    Project 3D coordinates to screen coordinates (NO depth range [-1,1]).
303

304
    Args:
305
        obj: 3D object coordinates (vec3)
306
        model: Model matrix (mat4)
307
        proj: Projection matrix (mat4)
308
        viewport: Viewport parameters (vec4)
309

310
    Returns:
311
        Screen coordinates with NO depth range
312
    """
313

314
def projectZO(obj, model, proj, viewport):
315
    """
316
    Project 3D coordinates to screen coordinates (ZO depth range [0,1]).
317

318
    Args:
319
        obj: 3D object coordinates (vec3)
320
        model: Model matrix (mat4)
321
        proj: Projection matrix (mat4)
322
        viewport: Viewport parameters (vec4)
323

324
    Returns:
325
        Screen coordinates with ZO depth range
326
    """
327

328
def unProject(win, model, proj, viewport):
329
    """
330
    Unproject screen coordinates to 3D coordinates.
331

332
    Args:
333
        win: Screen coordinates (vec3: x, y, depth)
334
        model: Model matrix (mat4)
335
        proj: Projection matrix (mat4)
336
        viewport: Viewport parameters (vec4)
337

338
    Returns:
339
        3D object coordinates (vec3)
340
    """
341

342
def unProjectNO(win, model, proj, viewport):
343
    """
344
    Unproject screen coordinates (NO depth range) to 3D coordinates.
345

346
    Args:
347
        win: Screen coordinates with NO depth range
348
        model: Model matrix (mat4)
349
        proj: Projection matrix (mat4)
350
        viewport: Viewport parameters (vec4)
351

352
    Returns:
353
        3D object coordinates
354
    """
355

356
def unProjectZO(win, model, proj, viewport):
357
    """
358
    Unproject screen coordinates (ZO depth range) to 3D coordinates.
359

360
    Args:
361
        win: Screen coordinates with ZO depth range
362
        model: Model matrix (mat4)
363
        proj: Projection matrix (mat4)
364
        viewport: Viewport parameters (vec4)
365

366
    Returns:
367
        3D object coordinates
368
    """
369

370
def pickMatrix(center, delta, viewport):
371
    """
372
    Create a picking matrix for selection operations.
373

374
    Args:
375
        center: Center of picking region (vec2)
376
        delta: Size of picking region (vec2)
377
        viewport: Viewport parameters (vec4)
378

379
    Returns:
380
        4x4 picking matrix
381
    """
382
```
383

384
### Euler Angles
385

386
Functions for working with Euler angle representations of rotations.
387

388
```python { .api }
389
def euler(angles):
390
    """
391
    Create rotation matrix from Euler angles.
392

393
    Args:
394
        angles: Euler angles in radians (vec3: pitch, yaw, roll)
395

396
    Returns:
397
        3x3 rotation matrix
398

399
    Example:
400
        angles = glm.vec3(glm.radians(30), glm.radians(45), glm.radians(60))
401
        rotation_matrix = glm.euler(angles)
402
    """
403

404
def eulerAngles(quat):
405
    """
406
    Extract Euler angles from quaternion.
407

408
    Args:
409
        quat: Input quaternion
410

411
    Returns:
412
        Euler angles in radians (vec3: pitch, yaw, roll)
413

414
    Example:
415
        q = glm.angleAxis(glm.radians(45), glm.vec3(0, 1, 0))
416
        angles = glm.eulerAngles(q)
417
    """
418

419
def yaw(quat):
420
    """
421
    Extract yaw angle from quaternion.
422

423
    Args:
424
        quat: Input quaternion
425

426
    Returns:
427
        Yaw angle in radians
428
    """
429

430
def pitch(quat):
431
    """
432
    Extract pitch angle from quaternion.
433

434
    Args:
435
        quat: Input quaternion
436

437
    Returns:
438
        Pitch angle in radians
439
    """
440

441
def roll(quat):
442
    """
443
    Extract roll angle from quaternion.
444

445
    Args:
446
        quat: Input quaternion
447

448
    Returns:
449
        Roll angle in radians
450
    """
451
```
452

453
### Usage Examples
454

455
```python
456
from pyglm import glm
457

458
# === Color Space Conversion ===
459

460
# Convert from linear RGB to sRGB for display
461
linear_color = glm.vec3(0.5, 0.25, 0.75)
462
display_color = glm.convertLinearToSRGB(linear_color)
463

464
# Convert sRGB texture data to linear for calculations
465
texture_color = glm.vec3(0.73, 0.54, 0.88)
466
linear_texture = glm.convertSRGBToLinear(texture_color)
467

468
# === Rounding for Memory Alignment ===
469

470
# Align buffer size to 16-byte boundaries
471
buffer_size = 137
472
aligned_size = glm.ceilMultiple(buffer_size, 16)  # 144
473

474
# Round texture dimensions to power of two
475
width, height = 300, 200
476
pow2_width = glm.ceilPowerOfTwo(width)   # 512
477
pow2_height = glm.ceilPowerOfTwo(height) # 256
478

479
# === Norm Calculations ===
480

481
vector = glm.vec3(3, -4, 5)
482
manhattan_dist = glm.l1Norm(vector)  # 12 (|3| + |-4| + |5|)
483
euclidean_dist = glm.l2Norm(vector)  # ~7.07 (same as glm.length())
484
max_component = glm.lMaxNorm(vector) # 5 (max of |3|, |-4|, |5|)
485

486
# === Coordinate System Conversion ===
487

488
# Convert 2D Cartesian to polar
489
cartesian_point = glm.vec2(3, 4)
490
polar_coords = glm.polar(cartesian_point)  # vec2(5.0, 0.927)
491
radius = polar_coords.x    # 5.0
492
angle = polar_coords.y     # ~0.927 radians (~53 degrees)
493

494
# Convert back to Cartesian
495
back_to_cartesian = glm.euclidean(polar_coords)  # vec2(3, 4)
496

497
# === 3D Projection ===
498

499
# Project 3D world coordinates to screen coordinates
500
world_pos = glm.vec3(1, 2, -5)
501
model_matrix = glm.mat4()  # Identity
502
view_matrix = glm.lookAt(glm.vec3(0, 0, 0), glm.vec3(0, 0, -1), glm.vec3(0, 1, 0))
503
proj_matrix = glm.perspective(glm.radians(45), 1.33, 0.1, 100.0)
504
viewport = glm.vec4(0, 0, 800, 600)  # x, y, width, height
505

506
# Combine model and view
507
modelview = view_matrix * model_matrix
508
screen_pos = glm.project(world_pos, modelview, proj_matrix, viewport)
509

510
# Unproject screen coordinates back to world space
511
world_pos_back = glm.unProject(screen_pos, modelview, proj_matrix, viewport)
512

513
# === Euler Angle Rotation ===
514

515
# Create rotation from Euler angles
516
pitch = glm.radians(30)  # Around X-axis
517
yaw = glm.radians(45)    # Around Y-axis
518
roll = glm.radians(60)   # Around Z-axis
519

520
euler_angles = glm.vec3(pitch, yaw, roll)
521
rotation_matrix = glm.euler(euler_angles)
522

523
# Convert to quaternion for smooth interpolation
524
rotation_quat = glm.quat_cast(rotation_matrix)
525

526
# Extract individual angles from quaternion
527
extracted_yaw = glm.yaw(rotation_quat)
528
extracted_pitch = glm.pitch(rotation_quat)
529
extracted_roll = glm.roll(rotation_quat)
530

531
# Get all angles at once
532
all_angles = glm.eulerAngles(rotation_quat)
533

534
# === Picking for Mouse Selection ===
535

536
# Create picking matrix for mouse selection
537
mouse_pos = glm.vec2(400, 300)  # Mouse position
538
pick_size = glm.vec2(5, 5)      # 5x5 pixel selection area
539
viewport = glm.vec4(0, 0, 800, 600)
540

541
picking_matrix = glm.pickMatrix(mouse_pos, pick_size, viewport)
542
# Multiply with projection matrix for actual picking projection
543
pick_proj = proj_matrix * picking_matrix
544
```