0
# Graphics Utilities
1

2
Collection of utility functions and classes for shape building, curve calculations, and rendering optimizations. Includes mathematical utilities for arc, bezier, and quadratic curve operations.
3

4
## Capabilities
5

6
### Graphics Utils Namespace
7

8
Main namespace containing all utility functions, classes, and constants for graphics operations.
9

10
```typescript { .api }
11
declare const graphicsUtils: {
12
  /** Polygon shape builder implementing IShapeBuildCommand */
13
  buildPoly: IShapeBuildCommand;
14
  
15
  /** Circle and ellipse shape builder implementing IShapeBuildCommand */
16
  buildCircle: IShapeBuildCommand;
17
  
18
  /** Rectangle shape builder implementing IShapeBuildCommand */
19
  buildRectangle: IShapeBuildCommand;
20
  
21
  /** Rounded rectangle shape builder implementing IShapeBuildCommand */
22
  buildRoundedRectangle: IShapeBuildCommand;
23
  
24
  /** Line builder function for creating line geometry */
25
  buildLine: (graphicsData: GraphicsData, graphicsGeometry: GraphicsGeometry) => void;
26
  
27
  /** Arc curve utilities class */
28
  ArcUtils: typeof ArcUtils;
29
  
30
  /** Bezier curve utilities class */
31
  BezierUtils: typeof BezierUtils;
32
  
33
  /** Quadratic curve utilities class */
34
  QuadraticUtils: typeof QuadraticUtils;
35
  
36
  /** Batch part class for batching operations */
37
  BatchPart: typeof BatchPart;
38
  
39
  /** Map of fill commands by shape type */
40
  FILL_COMMANDS: Record<SHAPES, IShapeBuildCommand>;
41
  
42
  /** Pool of unused BatchPart objects for reuse */
43
  BATCH_POOL: Array<BatchPart>;
44
  
45
  /** Pool of unused BatchDrawCall objects for reuse */
46
  DRAW_CALL_POOL: Array<BatchDrawCall>;
47
};
48
```
49

50
### Shape Build Command Interface
51

52
Interface defining the contract for shape building operations used by all shape builders.
53

54
```typescript { .api }
55
/**
56
 * Interface for shape building commands that construct geometry from GraphicsData
57
 */
58
interface IShapeBuildCommand {
59
  /**
60
   * Build the shape geometry from graphics data
61
   * @param graphicsData - GraphicsData containing shape and style information
62
   */
63
  build(graphicsData: GraphicsData): void;
64
  
65
  /**
66
   * Triangulate the shape for rendering
67
   * @param graphicsData - GraphicsData containing shape information
68
   * @param target - Target GraphicsGeometry to receive triangulated data
69
   */
70
  triangulate(graphicsData: GraphicsData, target: GraphicsGeometry): void;
71
}
72
```
73

74
### Shape Builder Functions
75

76
Individual builder functions for different geometric primitives, accessed through the graphicsUtils namespace.
77

78
```typescript { .api }
79
/**
80
 * Builds polygon geometry from GraphicsData
81
 * Handles complex polygons with holes and self-intersections
82
 */
83
declare const buildPoly: IShapeBuildCommand;
84

85
/**
86
 * Builds circle and ellipse geometry from GraphicsData
87
 * Optimized for different circle segment counts based on radius
88
 */
89
declare const buildCircle: IShapeBuildCommand;
90

91
/**
92
 * Builds rectangle geometry from GraphicsData
93
 * Handles basic rectangles with optional line styling
94
 */
95
declare const buildRectangle: IShapeBuildCommand;
96

97
/**
98
 * Builds rounded rectangle geometry from GraphicsData
99
 * Supports different corner radius values and rendering modes
100
 */
101
declare const buildRoundedRectangle: IShapeBuildCommand;
102

103
/**
104
 * Builds line geometry from GraphicsData
105
 * Handles line caps, joins, and thickness
106
 * @param graphicsData - GraphicsData containing line information
107
 * @param graphicsGeometry - Target GraphicsGeometry to receive line geometry
108
 */
109
declare function buildLine(graphicsData: GraphicsData, graphicsGeometry: GraphicsGeometry): void;
110
```
111

112
### Pooling Constants
113

114
Pre-allocated object pools for performance optimization during rendering operations.
115

116
```typescript { .api }
117
/**
118
 * Map of fill commands indexed by shape type for fast lookup
119
 */
120
declare const FILL_COMMANDS: Record<SHAPES, IShapeBuildCommand>;
121

122
/**
123
 * Pool of unused BatchPart objects for memory efficiency
124
 * Reused during batching operations to avoid garbage collection
125
 */
126
declare const BATCH_POOL: Array<BatchPart>;
127

128
/**
129
 * Pool of unused BatchDrawCall objects for memory efficiency
130
 * Reused during draw call generation to avoid garbage collection
131
 */
132
declare const DRAW_CALL_POOL: Array<BatchDrawCall>;
133
```
134

135
### Advanced Curve Utilities
136

137
Utility classes providing mathematical functions for complex curve operations (already detailed in curves documentation, included here for completeness).
138

139
```typescript { .api }
140
/**
141
 * Arc curve utilities with mathematical functions
142
 */
143
class ArcUtils {
144
  static curveTo(x1: number, y1: number, x2: number, y2: number, radius: number, points: number[]): IArcLikeShape;
145
  static arc(startX: number, startY: number, cx: number, cy: number, radius: number, startAngle: number, endAngle: number, anticlockwise: boolean, points: number[]): void;
146
}
147

148
/**
149
 * Bezier curve utilities with mathematical functions
150
 */
151
class BezierUtils {
152
  static curveLength(fromX: number, fromY: number, cpX: number, cpY: number, cpX2: number, cpY2: number, toX: number, toY: number): number;
153
  static curveTo(cpX: number, cpY: number, cpX2: number, cpY2: number, toX: number, toY: number, points: number[]): void;
154
}
155

156
/**
157
 * Quadratic curve utilities with mathematical functions
158
 */
159
class QuadraticUtils {
160
  static curveLength(fromX: number, fromY: number, cpX: number, cpY: number, toX: number, toY: number): number;
161
  static curveTo(cpX: number, cpY: number, toX: number, toY: number, points: number[]): void;
162
}
163
```
164

165
### Batch Part Class
166

167
Class for managing interim batch objects during geometry processing and rendering optimization.
168

169
```typescript { .api }
170
/**
171
 * Represents a batch part for grouping geometry data during rendering
172
 */
173
class BatchPart {
174
  /** Creates new BatchPart for batching operations */
175
  constructor();
176
  
177
  /**
178
   * Begin a new batch part with specified parameters
179
   * @param style - Style configuration for the batch
180
   * @param startIndex - Starting vertex index in the geometry
181
   * @param attribStart - Starting attribute index
182
   */
183
  begin(style: any, startIndex: number, attribStart: number): void;
184
  
185
  /**
186
   * End the current batch part with specified parameters
187
   * @param endIndex - Ending vertex index in the geometry
188
   * @param endAttrib - Ending attribute index
189
   */
190
  end(endIndex: number, endAttrib: number): void;
191
  
192
  /** Reset the batch part to initial state for reuse */
193
  reset(): void;
194
}
195
```
196

197
## Usage Examples
198

199
**Using Shape Builders Directly:**
200

201
```typescript
202
import { graphicsUtils, GraphicsData, Rectangle, FillStyle } from "@pixi/graphics";
203

204
// Create graphics data for a rectangle
205
const fillStyle = new FillStyle();
206
fillStyle.color = 0xff0000;
207
fillStyle.visible = true;
208

209
const rectData = new GraphicsData(new Rectangle(0, 0, 100, 50), fillStyle);
210

211
// Use shape builder directly
212
graphicsUtils.buildRectangle.build(rectData);
213

214
// The shape builder has now populated rectData.points with geometry
215
console.log(`Generated points: ${rectData.points.length}`);
216
```
217

218
**Accessing Fill Commands by Shape Type:**
219

220
```typescript
221
import { graphicsUtils, SHAPES, GraphicsData, Circle } from "@pixi/graphics";
222

223
// Get builder for specific shape type
224
const circleBuilder = graphicsUtils.FILL_COMMANDS[SHAPES.CIRCLE];
225

226
// Use builder for circle geometry
227
const circleData = new GraphicsData(new Circle(0, 0, 25));
228
circleBuilder.build(circleData);
229
```
230

231
**Working with Object Pools:**
232

233
```typescript
234
import { graphicsUtils } from "@pixi/graphics";
235

236
// Get a BatchPart from the pool (if available) or create new one
237
let batchPart: BatchPart;
238
if (graphicsUtils.BATCH_POOL.length > 0) {
239
  batchPart = graphicsUtils.BATCH_POOL.pop()!;
240
  batchPart.reset();
241
} else {
242
  batchPart = new graphicsUtils.BatchPart();
243
}
244

245
// Use the batch part
246
batchPart.begin(styleObject, 0, 0);
247
// ... perform batching operations ...
248
batchPart.end(100, 400);
249

250
// Return to pool for reuse
251
graphicsUtils.BATCH_POOL.push(batchPart);
252
```
253

254
**Custom Shape Building:**
255

256
```typescript
257
import { graphicsUtils, GraphicsData, Polygon, GraphicsGeometry } from "@pixi/graphics";
258

259
// Create custom polygon data
260
const points = [0, 0, 100, 0, 100, 100, 50, 150, 0, 100];
261
const polygon = new Polygon(points);
262
const polygonData = new GraphicsData(polygon);
263

264
// Build the polygon geometry
265
graphicsUtils.buildPoly.build(polygonData);
266

267
// Triangulate for rendering
268
const geometry = new GraphicsGeometry();
269
graphicsUtils.buildPoly.triangulate(polygonData, geometry);
270

271
console.log(`Triangulated indices: ${geometry.indices.length}`);
272
```
273

274
**Using Line Builder:**
275

276
```typescript
277
import { graphicsUtils, GraphicsData, LineStyle } from "@pixi/graphics";
278

279
// Create line data with styling
280
const lineStyle = new LineStyle();
281
lineStyle.width = 5;
282
lineStyle.color = 0x00ff00;
283
lineStyle.cap = LINE_CAP.ROUND;
284

285
// Line data requires points array for the line path
286
const lineData = new GraphicsData(null, null, lineStyle);
287
lineData.points = [0, 0, 100, 50, 200, 0, 300, 75]; // Line path points
288

289
// Build line geometry
290
const geometry = new GraphicsGeometry();
291
graphicsUtils.buildLine(lineData, geometry);
292
```
293

294
**Curve Utilities Integration:**
295

296
```typescript
297
import { graphicsUtils } from "@pixi/graphics";
298

299
// Use curve utilities directly
300
const points: number[] = [];
301

302
// Calculate bezier curve points
303
graphicsUtils.BezierUtils.curveTo(50, -25, 100, 25, 150, 0, points);
304

305
// Calculate curve length for animation timing
306
const length = graphicsUtils.BezierUtils.curveLength(0, 0, 50, -25, 100, 25, 150, 0);
307
console.log(`Curve length: ${length} pixels`);
308

309
// Use calculated points in custom shape
310
const customData = new GraphicsData(null);
311
customData.points = [0, 0, ...points]; // Start point + curve points
312
const customGeometry = new GraphicsGeometry();
313
graphicsUtils.buildLine(customData, customGeometry);
314
```
315

316
**Advanced Batching with BatchPart:**
317

318
```typescript
319
import { graphicsUtils } from "@pixi/graphics";
320

321
// Create multiple batch parts for complex geometry
322
const batch1 = new graphicsUtils.BatchPart();
323
const batch2 = new graphicsUtils.BatchPart();
324

325
// Configure first batch (filled shapes)
326
batch1.begin({ 
327
  fillStyle: { color: 0xff0000, alpha: 1 },
328
  texture: null 
329
}, 0, 0);
330
batch1.end(100, 300);
331

332
// Configure second batch (stroked shapes)
333
batch2.begin({
334
  lineStyle: { width: 2, color: 0x000000 },
335
  texture: null
336
}, 100, 300);
337
batch2.end(200, 600);
338

339
// Batches can now be used for optimized rendering
340
console.log(`Batch 1 vertex range: 0-100`);
341
console.log(`Batch 2 vertex range: 100-200`);
342
```
343

344
**Shape Builder Performance Comparison:**
345

346
```typescript
347
import { graphicsUtils, GraphicsData, Rectangle, Circle } from "@pixi/graphics";
348

349
// Performance test different builders
350
const iterations = 1000;
351

352
// Rectangle building performance
353
const rectData = new GraphicsData(new Rectangle(0, 0, 100, 100));
354
console.time('Rectangle building');
355
for (let i = 0; i < iterations; i++) {
356
  rectData.points = []; // Reset
357
  graphicsUtils.buildRectangle.build(rectData);
358
}
359
console.timeEnd('Rectangle building');
360

361
// Circle building performance  
362
const circleData = new GraphicsData(new Circle(0, 0, 50));
363
console.time('Circle building');
364
for (let i = 0; i < iterations; i++) {
365
  circleData.points = []; // Reset
366
  graphicsUtils.buildCircle.build(circleData);
367
}
368
console.timeEnd('Circle building');
369
```