0
# Geometry
1

2
Vertex data management system providing GPU buffer optimization, attribute handling, and efficient geometry rendering. The geometry system manages vertex buffers, index buffers, and vertex attributes for WebGL rendering.
3

4
## Capabilities
5

6
### Geometry
7

8
Main geometry class that manages vertex data, attributes, and index buffers for efficient GPU rendering.
9

10
```typescript { .api }
11
/**
12
 * Geometry manages vertex data and attributes for rendering
13
 * Handles vertex buffers, index buffers, and attribute definitions
14
 */
15
class Geometry extends EventEmitter {
16
  /** Array of vertex buffers */
17
  buffers: Buffer[];
18
  /** Index buffer for indexed rendering */
19
  indexBuffer: Buffer;
20
  /** Map of attribute definitions */
21
  attributes: {[key: string]: Attribute};
22
  /** Whether geometry has been destroyed */
23
  destroyed: boolean;
24
  /** Instance count for instanced rendering */
25
  instanceCount: number;
26
  /** WebGL Vertex Array Objects cache */
27
  glVertexArrayObjects: {[key: number]: {[key: string]: WebGLVertexArrayObject}};
28
  /** Dispose runner for cleanup */
29
  disposeRunner: Runner;
30

31
  /** Create a new Geometry */
32
  constructor();
33

34
  /**
35
   * Add an attribute to the geometry
36
   * @param id - Attribute identifier
37
   * @param buffer - Buffer data, Buffer instance, or Attribute
38
   * @param size - Number of components per vertex (default: 2)
39
   * @param normalized - Whether values should be normalized
40
   * @param type - Data type (FLOAT, etc.)
41
   * @param stride - Byte stride between vertices
42
   * @param start - Byte offset of first vertex
43
   * @param instance - Whether attribute is instanced
44
   */
45
  addAttribute(
46
    id: string,
47
    buffer: ArrayLike<number> | Buffer | Attribute,
48
    size?: number,
49
    normalized?: boolean,
50
    type?: TYPES,
51
    stride?: number,
52
    start?: number,
53
    instance?: boolean
54
  ): this;
55

56
  /**
57
   * Get an attribute by ID
58
   * @param id - Attribute identifier
59
   */
60
  getAttribute(id: string): Attribute;
61

62
  /**
63
   * Get a buffer by attribute ID
64
   * @param id - Attribute identifier  
65
   */
66
  getBuffer(id: string): Buffer;
67

68
  /**
69
   * Add index buffer for indexed rendering
70
   * @param buffer - Index data or Buffer instance
71
   */
72
  addIndex(buffer: ArrayLike<number> | Buffer): this;
73

74
  /**
75
   * Get the current index buffer
76
   */
77
  getIndex(): Buffer;
78

79
  /**
80
   * Interleave vertex data into a single buffer
81
   * @param arrays - Array of vertex data arrays
82
   * @param sizes - Array of component sizes for each attribute
83
   */
84
  interleave(): this;
85

86
  /** Get size of geometry (number of vertices) */
87
  getSize(): number;
88

89
  /** Clone the geometry */
90
  clone(): Geometry;
91

92
  /** Dispose of WebGL resources */
93
  dispose(): void;
94

95
  /** Destroy geometry and cleanup all resources */  
96
  destroy(): void;
97
}
98
```
99

100
### Buffer
101

102
Buffer class that manages vertex or index data and handles GPU buffer creation and updates.
103

104
```typescript { .api }
105
/**
106
 * Buffer manages vertex or index data for GPU rendering
107
 * Handles buffer creation, updates, and GPU resource management
108
 */
109
class Buffer {
110
  /** The data array (vertices, indices, etc.) */
111
  data: IArrayBuffer;
112
  /** Buffer type (ARRAY_BUFFER or ELEMENT_ARRAY_BUFFER) */
113
  type: BUFFER_TYPE;
114
  /** Whether buffer is static (infrequently updated) */
115
  static: boolean;
116
  /** Unique buffer ID */
117
  id: number;
118
  /** Dispose runner for cleanup */
119
  disposeRunner: Runner;
120

121
  /**
122
   * Create a new Buffer
123
   * @param data - Vertex or index data
124
   * @param _static - Whether buffer is static
125
   * @param index - Whether this is an index buffer
126
   */
127
  constructor(data?: IArrayBuffer, _static?: boolean, index?: boolean);
128

129
  /**
130
   * Update buffer data
131
   * @param data - New buffer data
132
   */
133
  update(data?: IArrayBuffer): void;
134

135
  /** Dispose of GPU resources */
136
  dispose(): void;
137

138
  /** Destroy buffer and cleanup resources */
139
  destroy(): void;
140

141
  /**
142
   * Create buffer from array
143
   * @param array - Source data array
144
   */
145
  static from(array: IArrayBuffer | number[]): Buffer;
146
}
147

148
type IArrayBuffer = ArrayBuffer | ArrayBufferView | number[];
149

150
enum BUFFER_TYPE {
151
  ELEMENT_ARRAY_BUFFER = 34963,
152
  ARRAY_BUFFER = 34962
153
}
154
```
155

156
### Attribute
157

158
Attribute class that defines how vertex data should be interpreted by WebGL vertex shaders.
159

160
```typescript { .api }
161
/**
162
 * Attribute defines how vertex buffer data is interpreted
163
 * Specifies data layout for vertex shader attributes
164
 */
165
class Attribute {
166
  /** The buffer containing attribute data */
167
  buffer: Buffer;
168
  /** Number of components per vertex (1-4) */
169
  size: number;
170
  /** Whether values should be normalized to 0-1 range */
171
  normalized: boolean;
172
  /** Data type (FLOAT, UNSIGNED_BYTE, etc.) */
173
  type: TYPES;
174
  /** Byte stride between consecutive vertices */
175
  stride: number;
176
  /** Byte offset of first vertex in buffer */
177
  start: number;
178
  /** Whether attribute is instanced (one value per instance) */
179
  instance: boolean;
180
  /** Attribute divisor for instanced rendering */
181
  divisor: number;
182

183
  /**
184
   * Create a new Attribute
185
   * @param buffer - Buffer containing attribute data
186
   * @param size - Components per vertex
187
   * @param normalized - Normalize values flag
188
   * @param type - Data type
189
   * @param stride - Byte stride
190
   * @param start - Byte offset
191
   * @param instance - Instanced attribute flag
192
   */
193
  constructor(
194
    buffer: Buffer,
195
    size?: number,
196
    normalized?: boolean,
197
    type?: TYPES,
198
    stride?: number,
199
    start?: number,
200
    instance?: boolean
201
  );
202

203
  /** Destroy attribute */
204
  destroy(): void;
205

206
  /**
207
   * Create attribute from array data
208
   * @param array - Source data
209
   * @param size - Components per vertex
210
   * @param normalized - Normalize flag
211
   */
212
  static from(array: number[], size?: number, normalized?: boolean): Attribute;
213
}
214
```
215

216
### ViewableBuffer
217

218
Advanced buffer that provides typed array views and automatic resizing capabilities.
219

220
```typescript { .api }
221
/**
222
 * ViewableBuffer provides typed array views of buffer data
223
 * Automatically manages buffer resizing and provides convenient access
224
 */
225
class ViewableBuffer {
226
  /** Raw buffer data */
227
  rawBinaryData: ArrayBuffer;
228
  /** 32-bit unsigned integer view */
229
  uint32View: Uint32Array;
230
  /** 32-bit float view */
231
  float32View: Float32Array;
232
  /** Buffer size in bytes */
233
  size: number;
234

235
  /**
236
   * Create a new ViewableBuffer
237
   * @param sizeOrBuffer - Initial size or existing ArrayBuffer
238
   */
239
  constructor(sizeOrBuffer: number | ArrayBuffer);
240

241
  /** Get current buffer size in bytes */
242
  get rawBinaryDataBuffer(): ArrayBuffer;
243

244
  /**
245
   * Ensure buffer has at least the specified size
246
   * @param sizeRequired - Required size in bytes
247
   */
248
  checkDataSize(sizeRequired: number): void;
249

250
  /**
251
   * Resize buffer to new size
252
   * @param size - New size in bytes
253
   */
254
  resize(size: number): void;
255

256
  /** Destroy buffer */
257
  destroy(): void;
258
}
259
```
260

261
### BatchGeometry  
262

263
Specialized geometry for batch rendering that handles dynamic vertex data updates.
264

265
```typescript { .api }
266
/**
267
 * BatchGeometry specialized for batch rendering systems
268
 * Handles dynamic vertex data and efficient batch updates
269
 */
270
class BatchGeometry extends Geometry {
271
  /** Maximum number of textures per batch */
272
  static MAX_TEXTURES: number;
273

274
  /** Packed vertex data */
275
  _buffer: Buffer;
276
  /** Index data */
277
  _indexBuffer: Buffer;
278

279
  /**
280
   * Create a new BatchGeometry
281
   * @param _static - Whether geometry is static
282
   */
283
  constructor(_static?: boolean);
284
}
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
import { Geometry, Buffer, Attribute } from "@pixi/core";
291

292
// Create basic triangle geometry
293
const geometry = new Geometry();
294

295
// Add vertex positions (3 vertices, 2 components each)
296
geometry.addAttribute('aVertexPosition', [
297
  -0.5, -0.5,  // vertex 1
298
   0.5, -0.5,  // vertex 2  
299
   0.0,  0.5   // vertex 3
300
], 2);
301

302
// Add texture coordinates
303
geometry.addAttribute('aTextureCoord', [
304
  0, 0,  // UV for vertex 1
305
  1, 0,  // UV for vertex 2
306
  0.5, 1 // UV for vertex 3
307
], 2);
308

309
// Create quad with indices
310
const quadGeometry = new Geometry()
311
  .addAttribute('aVertexPosition', [
312
    -1, -1,  // bottom-left
313
     1, -1,  // bottom-right
314
     1,  1,  // top-right
315
    -1,  1   // top-left
316
  ], 2)
317
  .addIndex([0, 1, 2, 0, 2, 3]); // Two triangles
318

319
// Create geometry with explicit buffers
320
const positionBuffer = new Buffer(new Float32Array([
321
  -0.5, -0.5,
322
   0.5, -0.5,
323
   0.0,  0.5
324
]), false); // dynamic buffer
325

326
const positionAttribute = new Attribute(positionBuffer, 2, false, TYPES.FLOAT);
327
geometry.addAttribute('aVertexPosition', positionAttribute);
328

329
// Update buffer data
330
positionBuffer.update(new Float32Array([
331
  -0.8, -0.8,
332
   0.8, -0.8,
333
   0.0,  0.8
334
]));
335

336
// Interleaved vertex data (position + UV)
337
const interleavedGeometry = new Geometry();
338
interleavedGeometry.addAttribute('aVertexPosition', [
339
  -1, -1, 0, 0,  // vertex 1: pos(-1,-1), uv(0,0)
340
   1, -1, 1, 0,  // vertex 2: pos(1,-1), uv(1,0)
341
   1,  1, 1, 1,  // vertex 3: pos(1,1), uv(1,1)
342
  -1,  1, 0, 1   // vertex 4: pos(-1,1), uv(0,1)
343
], 2, false, TYPES.FLOAT, 4 * 4, 0); // stride=16 bytes, start=0
344

345
interleavedGeometry.addAttribute('aTextureCoord', 
346
  interleavedGeometry.getBuffer('aVertexPosition'), // same buffer
347
  2, false, TYPES.FLOAT, 4 * 4, 2 * 4); // stride=16 bytes, start=8 bytes
348

349
// Instanced geometry
350
const instanceGeometry = new Geometry();
351
instanceGeometry.instanceCount = 100;
352
instanceGeometry.addAttribute('aVertexPosition', quadVertices, 2);
353
instanceGeometry.addAttribute('aInstancePosition', instancePositions, 2, false, TYPES.FLOAT, 0, 0, true);
354

355
// Get geometry info
356
console.log('Vertex count:', geometry.getSize());
357
console.log('Has indices:', !!geometry.indexBuffer);
358
```
359

360
## Types
361

362
```typescript { .api }
363
enum TYPES {
364
  BYTE = 5120,
365
  UNSIGNED_BYTE = 5121,
366
  SHORT = 5122,
367
  UNSIGNED_SHORT = 5123,
368
  INT = 5124,
369
  UNSIGNED_INT = 5125,
370
  FLOAT = 5126,
371
  DOUBLE = 5130,
372
  HALF_FLOAT = 36193
373
}
374

375
interface IAttributeData {
376
  buffer: Buffer;
377
  size: number;
378
  normalized: boolean;
379
  type: TYPES;
380
  stride: number;
381
  start: number;
382
  instance: boolean;
383
}
384
```