0
# Shaders
1

2
Shader compilation, uniform management, and program linking with full WebGL shader support. The shader system handles GLSL shader compilation, uniform binding, and GPU program management.
3

4
## Capabilities
5

6
### Shader
7

8
Main shader class that combines a compiled program with uniform data for GPU rendering.
9

10
```typescript { .api }
11
/**
12
 * Shader combines a compiled program with uniforms for rendering
13
 * Manages shader programs and uniform data binding
14
 */
15
class Shader extends EventEmitter {
16
  /** The compiled shader program */
17
  program: Program;
18
  /** Uniform data for the shader */
19
  uniforms: Dict<any>;
20

21
  /**
22
   * Create a new Shader
23
   * @param program - Compiled shader program
24
   * @param uniforms - Uniform values
25
   */
26
  constructor(program: Program, uniforms?: Dict<any>);
27

28
  /** Check if shader program is valid */
29
  checkUniformExists(name: string, group: UniformGroup): boolean;
30

31
  /** Destroy shader and cleanup resources */
32
  destroy(): void;
33

34
  /**
35
   * Create shader from source code
36
   * @param vertexSrc - Vertex shader source
37
   * @param fragmentSrc - Fragment shader source  
38
   * @param uniforms - Uniform values
39
   * @param name - Shader name for debugging
40
   */
41
  static from(vertexSrc?: string, fragmentSrc?: string, uniforms?: Dict<any>, name?: string): Shader;
42
}
43

44
type Dict<T> = {[key: string]: T};
45
```
46

47
### Program
48

49
Program class that manages GLSL shader compilation and linking.
50

51
```typescript { .api }
52
/**
53
 * Program manages GLSL shader compilation and program linking
54
 * Handles vertex and fragment shader compilation
55
 */
56
class Program {
57
  /** Vertex shader source code */
58
  vertexSrc: string;
59
  /** Fragment shader source code */
60
  fragmentSrc: string;
61
  /** Program name for debugging */
62
  name: string;
63
  /** Unique program ID */
64
  id: number;
65
  /** Attribute data extracted from shaders */
66
  attributeData: {[key: string]: IAttributeData};
67
  /** Uniform data extracted from shaders */
68
  uniformData: {[key: string]: IUniformData};
69

70
  /**
71
   * Create a new Program
72
   * @param vertexSrc - Vertex shader source
73
   * @param fragmentSrc - Fragment shader source
74
   * @param name - Program name
75
   */
76
  constructor(vertexSrc?: string, fragmentSrc?: string, name?: string);
77

78
  /**
79
   * Extract attribute and uniform data from shader source
80
   * @param vertexSrc - Vertex shader source
81
   * @param fragmentSrc - Fragment shader source
82
   */
83
  extractData(vertexSrc: string, fragmentSrc: string): void;
84

85
  /** Destroy program */
86
  destroy(): void;
87

88
  /**
89
   * Create program from shader sources
90
   * @param vertexSrc - Vertex shader source
91
   * @param fragmentSrc - Fragment shader source
92
   * @param name - Program name
93
   */
94
  static from(vertexSrc?: string, fragmentSrc?: string, name?: string): Program;
95
}
96

97
interface IAttributeData {
98
  type: string;
99
  size: number;
100
  location: number;
101
  name: string;
102
}
103

104
interface IUniformData {
105
  index: number;
106
  type: string;
107
  size: number;
108
  offset: number;
109
  name: string;
110
  value: any;
111
}
112
```
113

114
### UniformGroup
115

116
UniformGroup manages collections of shader uniforms with automatic GPU buffer synchronization.
117

118
```typescript { .api }
119
/**
120
 * UniformGroup manages collections of shader uniforms
121
 * Handles uniform buffer objects and automatic synchronization
122
 */
123
class UniformGroup<LAYOUT = Dict<any>> extends EventEmitter {
124
  /** Uniform data layout */
125
  uniforms: LAYOUT;
126
  /** Group ID for caching */
127
  group: number;
128
  /** Unique group ID */
129
  id: number;
130
  /** Whether group uses uniform buffer objects */
131
  ubo: boolean;
132
  /** Buffer for UBO data */
133
  buffer?: Buffer;
134
  /** Auto-manage flag */
135
  autoManage: boolean;
136
  /** Sync function for buffer updates */
137
  syncUniforms: {[key: string]: UniformsSyncCallback};
138

139
  /**
140
   * Create a new UniformGroup
141
   * @param uniforms - Uniform data or buffer
142
   * @param _static - Whether uniforms are static
143
   * @param _id - Group ID
144
   */
145
  constructor(uniforms: LAYOUT | Buffer, _static?: boolean, _id?: number);
146

147
  /** Update uniform buffer */
148
  update(): void;
149

150
  /** Add uniform to group */
151
  add(name: string, uniforms: Dict<any>, _static?: boolean): void;
152

153
  /**
154
   * Create uniform group with UBO buffer
155
   * @param uniforms - Uniform data
156
   * @param _static - Static flag
157
   */
158
  static uboFrom(uniforms: Dict<any>, _static?: boolean): UniformGroup;
159

160
  /**
161
   * Create uniform group from data
162
   * @param uniforms - Uniform data
163
   * @param _static - Static flag
164
   */
165
  static from(uniforms: Dict<any>, _static?: boolean): UniformGroup;
166

167
  /** Destroy uniform group */
168
  destroy(): void;
169
}
170

171
type UniformsSyncCallback = (ud: any, uv: any, renderer: Renderer, syncData: any) => void;
172
```
173

174
### GLProgram
175

176
WebGL-specific program wrapper that manages compiled GPU programs.
177

178
```typescript { .api }
179
/**  
180
 * GLProgram wraps compiled WebGL programs
181
 * Manages GPU program objects and uniform locations
182
 */
183
class GLProgram {
184
  /** WebGL program object */
185
  program: WebGLProgram;
186
  /** Uniform location cache */
187
  uniformData: {[key: string]: any};
188
  /** Uniform group data */
189
  uniformGroups: {[key: string]: any};
190
  /** Uniform block data */
191
  uniformDirtyGroups: {[key: string]: boolean};
192

193
  /**
194
   * Create GLProgram from Program
195
   * @param program - Source program
196
   */  
197
  constructor(program: Program);
198

199
  /** Destroy WebGL program */
200
  destroy(): void;
201
}
202
```
203

204
### Shader Utilities
205

206
Utility functions for shader compilation and management.
207

208
```typescript { .api }
209
/**
210
 * Generate WebGL program from vertex and fragment shaders
211
 * @param gl - WebGL context
212
 * @param vertexSrc - Vertex shader source
213
 * @param fragmentSrc - Fragment shader source
214
 * @param attributeLocations - Attribute location bindings
215
 * @param transformFeedbackVaryings - Transform feedback varyings
216
 */
217
function generateProgram(
218
  gl: IRenderingContext,
219
  vertexSrc: string,
220
  fragmentSrc: string,
221
  attributeLocations?: {[key: string]: number},
222
  transformFeedbackVaryings?: {
223
    names: string[];
224
    bufferMode: 'separate' | 'interleaved';
225
  }
226
): WebGLProgram;
227

228
/**
229
 * Get a WebGL test context for feature detection
230
 * @param failIfMajorPerformanceCaveat - Fail if performance caveat
231
 */
232
function getTestContext(failIfMajorPerformanceCaveat?: boolean): IRenderingContext | null;
233

234
/**
235
 * Check maximum if statements supported in shaders
236
 * @param maxIfs - Maximum if statements to test
237
 * @param gl - WebGL context
238
 */
239
function checkMaxIfStatementsInShader(maxIfs: number, gl: IRenderingContext): number;
240

241
/**
242
 * Generate uniform buffer synchronization function
243
 * @param group - Uniform group
244
 * @param uniformData - Uniform metadata
245
 */
246
function generateUniformBufferSync(group: UniformGroup, uniformData: {[key: string]: any}): UniformsSyncCallback;
247

248
/**
249
 * Get uniform parsers for different data types
250
 */
251
const uniformParsers: {
252
  [key: string]: {
253
    test: (data: unknown, uniform: any) => boolean;
254
    code: string;
255
    codeUbo: string;
256
  };
257
};
258
```
259

260
**Usage Examples:**
261

262
```typescript
263
import { Shader, Program, UniformGroup } from "@pixi/core";
264

265
// Create basic shader
266
const vertexShader = `
267
  attribute vec2 aVertexPosition;
268
  attribute vec2 aTextureCoord;
269
  
270
  uniform mat3 projectionMatrix;
271
  
272
  varying vec2 vTextureCoord;
273
  
274
  void main(void) {
275
    gl_Position = vec4((projectionMatrix * vec3(aVertexPosition, 1.0)).xy, 0.0, 1.0);
276
    vTextureCoord = aTextureCoord;
277
  }
278
`;
279

280
const fragmentShader = `
281
  precision mediump float;
282
  
283
  varying vec2 vTextureCoord;
284
  uniform sampler2D uSampler;
285
  uniform vec4 uColor;
286
  
287
  void main(void) {
288
    gl_FragColor = texture2D(uSampler, vTextureCoord) * uColor;
289
  }
290
`;
291

292
// Create shader with uniforms
293
const shader = Shader.from(vertexShader, fragmentShader, {
294
  uSampler: texture,
295
  uColor: [1.0, 1.0, 1.0, 1.0],
296
  projectionMatrix: new Matrix()
297
});
298

299
// Create shader program separately
300
const program = Program.from(vertexShader, fragmentShader, 'basic-shader');
301
const uniformGroup = UniformGroup.from({
302
  uSampler: texture,
303
  uColor: [1.0, 0.5, 0.0, 1.0]
304
});
305

306
const customShader = new Shader(program, uniformGroup);
307

308
// Using Uniform Buffer Objects for better performance
309
const uboGroup = UniformGroup.uboFrom({
310
  projectionMatrix: new Matrix(),
311
  viewMatrix: new Matrix(),
312
  lightPosition: [0, 0, 0],
313
  lightColor: [1, 1, 1, 1]
314
}, false); // dynamic uniforms
315

316
// Update uniforms
317
shader.uniforms.uColor = [1.0, 0.0, 0.0, 1.0]; // Red tint
318
uboGroup.uniforms.lightPosition = [100, 100, 0];
319
uboGroup.update(); // Sync to GPU
320

321
// Advanced shader with multiple uniform groups
322
const advancedShader = new Shader(program, {
323
  // Textures
324
  uSampler: texture,
325
  uNormalMap: normalTexture,
326
  
327
  // Material properties
328
  uMaterial: UniformGroup.from({
329
    ambient: [0.2, 0.2, 0.2],
330
    diffuse: [0.8, 0.8, 0.8],
331
    specular: [1.0, 1.0, 1.0],
332
    shininess: 32.0
333
  }),
334
  
335
  // Lighting
336
  uLighting: UniformGroup.uboFrom({
337
    lightDirection: [0.0, -1.0, -1.0],
338
    lightColor: [1.0, 1.0, 1.0],
339
    ambientLight: [0.1, 0.1, 0.1]
340
  })
341
});
342

343
// Extract program information
344
console.log('Attributes:', program.attributeData);
345
console.log('Uniforms:', program.uniformData);
346

347
// Cleanup
348
shader.destroy();
349
program.destroy();
350
uniformGroup.destroy();
351
```
352

353
**Advanced Uniform Management:**
354

355
```typescript
356
// Custom uniform synchronization
357
const customUniforms = new UniformGroup({
358
  time: 0,
359
  resolution: [800, 600],
360
  mouse: [0, 0]
361
});
362

363
// Manual uniform updates in render loop
364
function render(deltaTime) {
365
  customUniforms.uniforms.time += deltaTime;
366
  customUniforms.uniforms.mouse = [mouseX, mouseY];
367
  customUniforms.update();
368
  
369
  renderer.render(scene);
370
}
371

372
// Uniform buffer objects for large uniform sets
373
const sceneUniforms = UniformGroup.uboFrom({
374
  viewMatrix: new Matrix(),
375
  projectionMatrix: new Matrix(),
376
  cameraPosition: [0, 0, 0],
377
  fogColor: [0.5, 0.5, 0.5],
378
  fogNear: 10.0,
379
  fogFar: 100.0
380
});
381

382
// Batch uniform updates
383
sceneUniforms.uniforms.viewMatrix = camera.viewMatrix;
384
sceneUniforms.uniforms.projectionMatrix = camera.projectionMatrix;
385
sceneUniforms.uniforms.cameraPosition = camera.position;
386
sceneUniforms.update(); // Single GPU sync
387
```
388

389
## Types
390

391
```typescript { .api }
392
interface IUniformData {
393
  index: number;
394
  type: string;
395
  size: number;
396
  offset: number;
397
  name: string;
398
  value: any;
399
}
400

401
interface IAttributeData {
402
  type: string;
403
  size: number;
404
  location: number;
405
  name: string;  
406
}
407

408
type UniformsSyncCallback = (ud: any, uv: any, renderer: Renderer, syncData: any) => void;
409
```