0
# Geometry Management
1

2
Low-level geometry management for advanced use cases including custom vertex manipulation, batching optimization, and geometry reuse across multiple graphics objects.
3

4
## Capabilities
5

6
### GraphicsGeometry Class
7

8
Core class for managing geometry data including vertices, indices, colors, and batching optimization for high-performance rendering.
9

10
```typescript { .api }
11
class GraphicsGeometry extends BatchGeometry {
12
  /** Creates new GraphicsGeometry with empty data */
13
  constructor();
14
  
15
  /** Current geometry bounds (readonly) */
16
  readonly bounds: Bounds;
17
  
18
  /** Array of points to draw (2 numbers per point: x, y) */
19
  points: number[];
20
  
21
  /** Collection of colors corresponding to vertices */
22
  colors: number[];
23
  
24
  /** UV coordinates collection for texture mapping */
25
  uvs: number[];
26
  
27
  /** Vertex indices for triangle construction */
28
  indices: number[];
29
  
30
  /** Reference to texture IDs for multi-texture rendering */
31
  textureIds: number[];
32
  
33
  /** Collection of drawn shapes as GraphicsData objects */
34
  graphicsData: GraphicsData[];
35
  
36
  /** List of draw calls generated from batches */
37
  drawCalls: BatchDrawCall[];
38
  
39
  /** Intermediate batch format for rendering optimization */
40
  batches: BatchPart[];
41
  
42
  /** Flag indicating if batches need regeneration (-1 = dirty) */
43
  batchDirty: number;
44
  
45
  /** Whether geometry can be batched with other geometries */
46
  batchable: boolean;
47
  
48
  /** Float32 UV coordinates array for GPU */
49
  uvsFloat32: Float32Array;
50
  
51
  /** Indices array (Uint16 or Uint32 based on vertex count) */
52
  indicesUint16: Uint16Array | Uint32Array;
53
}
54
```
55

56
### Static Properties
57

58
Configuration constants for geometry optimization and batching behavior.
59

60
```typescript { .api }
61
class GraphicsGeometry {
62
  /** Maximum points for batchable objects (default: 100) */
63
  static BATCHABLE_SIZE: number;
64
}
65
```
66

67
### Geometry Configuration Properties
68

69
Properties controlling geometry behavior and precision settings.
70

71
```typescript { .api }
72
interface GraphicsGeometry {
73
  /** Minimal distance between different points (default: 1e-4) */
74
  closePointEps: number;
75
  
76
  /** Padding to add to geometry bounds (default: 0) */
77
  boundsPadding: number;
78
}
79
```
80

81
### Core Geometry Methods
82

83
Methods for managing geometry state and drawing operations.
84

85
```typescript { .api }
86
/**
87
 * Clears all graphics data and resets styles to defaults
88
 */
89
clear(): GraphicsGeometry;
90

91
/**
92
 * Draws any shape with optional styling and transformation
93
 * @param shape - Shape object to draw (Circle, Ellipse, Polygon, Rectangle, RoundedRectangle)
94
 * @param fillStyle - Optional fill style configuration
95
 * @param lineStyle - Optional line style configuration  
96
 * @param matrix - Optional transformation matrix
97
 */
98
drawShape(shape: IShape, fillStyle?: FillStyle, lineStyle?: LineStyle, matrix?: Matrix): GraphicsGeometry;
99

100
/**
101
 * Draws a hole in the last drawn shape
102
 * @param shape - Shape object defining the hole
103
 * @param matrix - Optional transformation matrix for the hole
104
 */
105
drawHole(shape: IShape, matrix?: Matrix): GraphicsGeometry;
106

107
/**
108
 * Generates intermediate batch data for rendering optimization
109
 * Call this after modifying geometry data directly
110
 */
111
updateBatches(): void;
112

113
/**
114
 * Tests if a point is within the geometry bounds
115
 * @param point - Point to test for containment
116
 */
117
containsPoint(point: IPointData): boolean;
118

119
/**
120
 * Destroys the geometry and cleans up resources
121
 */
122
destroy(): void;
123
```
124

125
### GraphicsData Class
126

127
Class representing individual drawn shapes with their styling and transformation information.
128

129
```typescript { .api }
130
class GraphicsData {
131
  /** The shape object (Circle|Ellipse|Polygon|Rectangle|RoundedRectangle) */
132
  shape: IShape;
133
  
134
  /** Line style configuration for this shape */
135
  lineStyle: LineStyle;
136
  
137
  /** Fill style configuration for this shape */
138
  fillStyle: FillStyle;
139
  
140
  /** Transform matrix applied to this shape */
141
  matrix: Matrix;
142
  
143
  /** Shape type from SHAPES enum */
144
  type: SHAPES;
145
  
146
  /** Collection of calculated points for the shape */
147
  points: number[];
148
  
149
  /** Collection of holes within this shape */
150
  holes: GraphicsData[];
151

152
  /**
153
   * Creates GraphicsData for a shape
154
   * @param shape - The shape object to store
155
   * @param fillStyle - Fill style configuration (optional)
156
   * @param lineStyle - Line style configuration (optional)
157
   * @param matrix - Transformation matrix (optional)
158
   */
159
  constructor(shape: IShape, fillStyle?: FillStyle, lineStyle?: LineStyle, matrix?: Matrix);
160
  
161
  /** Creates a copy of the GraphicsData with same values */
162
  clone(): GraphicsData;
163
  
164
  /** Destroys the graphics data and cleans up resources */
165
  destroy(): void;
166
}
167
```
168

169
### Batch Management
170

171
Classes and interfaces for managing rendering batches and draw calls.
172

173
```typescript { .api }
174
/**
175
 * Structure for interim batch objects during geometry processing
176
 */
177
class BatchPart {
178
  /** Creates new BatchPart for batching operations */
179
  constructor();
180
  
181
  /**
182
   * Begin a new batch part
183
   * @param style - Style configuration for the batch
184
   * @param startIndex - Starting vertex index
185
   * @param attribStart - Starting attribute index
186
   */
187
  begin(style: any, startIndex: number, attribStart: number): void;
188
  
189
  /**
190
   * End the current batch part
191
   * @param endIndex - Ending vertex index
192
   * @param endAttrib - Ending attribute index
193
   */
194
  end(endIndex: number, endAttrib: number): void;
195
  
196
  /** Reset the batch part to initial state */
197
  reset(): void;
198
}
199

200
/**
201
 * Batch element computed from Graphics geometry for rendering
202
 */
203
interface IGraphicsBatchElement {
204
  /** Vertex position data as Float32Array */
205
  vertexData: Float32Array;
206
  /** Blend mode for rendering this batch */
207
  blendMode: BLEND_MODES;
208
  /** Face indices (Uint16Array or Uint32Array) */
209
  indices: Uint16Array | Uint32Array;
210
  /** UV texture coordinates */
211
  uvs: Float32Array;
212
  /** Local alpha value */
213
  alpha: number;
214
  /** Combined world alpha value */
215
  worldAlpha: number;
216
  /** Batch RGB values array */
217
  _batchRGB: number[];
218
  /** Tint RGB value */
219
  _tintRGB: number;
220
  /** Associated texture */
221
  _texture: Texture;
222
}
223
```
224

225
## Usage Examples
226

227
**Creating and Reusing Geometry:**
228

229
```typescript
230
import { Graphics, GraphicsGeometry, FillStyle, LineStyle } from "@pixi/graphics";
231

232
// Create reusable geometry
233
const sharedGeometry = new GraphicsGeometry();
234

235
// Draw shapes directly to geometry
236
const fillStyle = new FillStyle();
237
fillStyle.color = 0xff0000;
238
fillStyle.visible = true;
239

240
const lineStyle = new LineStyle();
241
lineStyle.width = 2;
242
lineStyle.color = 0x000000;
243

244
sharedGeometry.drawShape(
245
  new Rectangle(0, 0, 100, 100),
246
  fillStyle,
247
  lineStyle
248
);
249

250
// Use geometry in multiple Graphics objects
251
const graphics1 = new Graphics(sharedGeometry);
252
const graphics2 = new Graphics(sharedGeometry);
253

254
// Position them differently
255
graphics1.position.set(100, 100);
256
graphics2.position.set(300, 100);
257
```
258

259
**Direct Geometry Manipulation:**
260

261
```typescript
262
import { GraphicsGeometry, Circle, FillStyle } from "@pixi/graphics";
263

264
const geometry = new GraphicsGeometry();
265

266
// Manually add geometry data
267
geometry.points = [0, 0, 100, 0, 100, 100, 0, 100]; // Rectangle points
268
geometry.colors = [0xff0000, 0x00ff00, 0x0000ff, 0xffff00]; // Vertex colors
269
geometry.indices = [0, 1, 2, 0, 2, 3]; // Triangle indices
270
geometry.uvs = [0, 0, 1, 0, 1, 1, 0, 1]; // UV coordinates
271

272
// Update batches after manual changes
273
geometry.updateBatches();
274

275
const graphics = new Graphics(geometry);
276
```
277

278
**Advanced Batch Management:**
279

280
```typescript
281
import { GraphicsGeometry } from "@pixi/graphics";
282

283
const geometry = new GraphicsGeometry();
284

285
// Check batching status
286
console.log(`Geometry is batchable: ${geometry.batchable}`);
287
console.log(`Current batch count: ${geometry.batches.length}`);
288
console.log(`Current draw calls: ${geometry.drawCalls.length}`);
289

290
// Force batch regeneration
291
geometry.batchDirty = -1;
292
geometry.updateBatches();
293

294
// Check geometry bounds
295
console.log(`Bounds: ${geometry.bounds.x}, ${geometry.bounds.y}, ${geometry.bounds.width}, ${geometry.bounds.height}`);
296
```
297

298
**Working with GraphicsData:**
299

300
```typescript
301
import { GraphicsData, Circle, Rectangle, FillStyle, LineStyle, Matrix } from "@pixi/graphics";
302

303
// Create styled shapes
304
const fillStyle = new FillStyle();
305
fillStyle.color = 0x00ff00;
306
fillStyle.alpha = 0.7;
307

308
const lineStyle = new LineStyle();
309
lineStyle.width = 3;
310
lineStyle.color = 0xff0000;
311

312
const transform = new Matrix().translate(50, 50).scale(1.2, 1.2);
313

314
// Create GraphicsData objects
315
const circleData = new GraphicsData(
316
  new Circle(0, 0, 30),
317
  fillStyle,
318
  lineStyle,
319
  transform
320
);
321

322
const rectData = new GraphicsData(
323
  new Rectangle(100, 0, 80, 60),
324
  fillStyle.clone(),
325
  lineStyle.clone()
326
);
327

328
// Add to geometry
329
const geometry = new GraphicsGeometry();
330
geometry.graphicsData.push(circleData, rectData);
331
geometry.updateBatches();
332
```
333

334
**Performance Optimization:**
335

336
```typescript
337
import { GraphicsGeometry } from "@pixi/graphics";
338

339
// Configure for performance
340
const geometry = new GraphicsGeometry();
341

342
// Adjust precision for better performance (larger epsilon = fewer points)
343
geometry.closePointEps = 1e-3;
344

345
// Add padding to bounds to avoid frequent recalculation
346
geometry.boundsPadding = 5;
347

348
// Check if geometry can be batched efficiently
349
if (geometry.points.length / 2 <= GraphicsGeometry.BATCHABLE_SIZE) {
350
  console.log("Geometry is suitable for batching");
351
} else {
352
  console.log("Geometry may need splitting for optimal performance");
353
}
354
```
355

356
**Geometry Analysis:**
357

358
```typescript
359
import { GraphicsGeometry } from "@pixi/graphics";
360

361
const geometry = new GraphicsGeometry();
362
// ... add shapes to geometry ...
363

364
// Analyze geometry properties
365
console.log(`Total points: ${geometry.points.length / 2}`);
366
console.log(`Total triangles: ${geometry.indices.length / 3}`);
367
console.log(`Total shapes: ${geometry.graphicsData.length}`);
368
console.log(`Bounds: ${JSON.stringify(geometry.bounds)}`);
369

370
// Check containment
371
const testPoint = { x: 50, y: 50 };
372
if (geometry.containsPoint(testPoint)) {
373
  console.log("Point is inside geometry");
374
}
375

376
// Access UV and color data
377
console.log(`UV coordinates: ${geometry.uvs.length / 2} pairs`);
378
console.log(`Colors: ${geometry.colors.length} values`);
379
```