0
# Shape Drawing
1

2
Comprehensive set of drawing components for creating basic and advanced shapes, paths, and geometric primitives in React Native Skia.
3

4
## Capabilities
5

6
### Basic Shapes
7

8
Fundamental geometric shapes for common drawing operations.
9

10
#### Circle
11

12
Draws a circle with center point and radius.
13

14
```typescript { .api }
15
/**
16
 * Draws a circle with center point and radius
17
 * @param props - Circle properties (supports both coordinate and vector syntax)
18
 * @returns JSX circle element
19
 */
20
function Circle(props: CircleProps): JSX.Element;
21

22
// Union type supporting both coordinate and vector center definitions
23
type CircleProps = CirclePropsWithCoordinates | CirclePropsWithCenter;
24

25
interface CirclePropsWithCoordinates extends DrawingNodeProps {
26
  /** Center X coordinate */
27
  cx: number;
28
  /** Center Y coordinate */
29
  cy: number; 
30
  /** Circle radius */
31
  r: number;
32
}
33

34
interface CirclePropsWithCenter extends DrawingNodeProps {
35
  /** Center point as vector */
36
  c: Vector;
37
  /** Circle radius */
38
  r: number;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { Circle, Paint } from "@shopify/react-native-skia";
46

47
// Basic circle with center coordinates
48
<Circle cx={50} cy={50} r={25}>
49
  <Paint color="red" />
50
</Circle>
51

52
// Circle with center point vector
53
<Circle c={{ x: 100, y: 100 }} r={30}>
54
  <Paint color="blue" style="stroke" strokeWidth={2} />
55
</Circle>
56
```
57

58
#### Rectangle
59

60
Draws a rectangle with position and dimensions.
61

62
```typescript { .api }
63
/**
64
 * Draws a rectangle with position and dimensions
65
 * @param props - Rectangle properties
66
 * @returns JSX rectangle element
67
 */
68
function Rect(props: RectProps): JSX.Element;
69

70
interface RectProps extends DrawingNodeProps {
71
  /** Left position */
72
  x: number;
73
  /** Top position */
74
  y: number;
75
  /** Rectangle width */
76
  width: number;
77
  /** Rectangle height */
78
  height: number;
79
}
80
```
81

82
#### Rounded Rectangle
83

84
Draws a rectangle with rounded corners.
85

86
```typescript { .api }
87
/**
88
 * Draws a rectangle with rounded corners
89
 * @param props - Rounded rectangle properties
90
 * @returns JSX rounded rectangle element
91
 */
92
function RoundedRect(props: RoundedRectProps): JSX.Element;
93

94
interface RoundedRectProps extends DrawingNodeProps {
95
  /** Left position */
96
  x: number;
97
  /** Top position */
98
  y: number;
99
  /** Rectangle width */
100
  width: number;
101
  /** Rectangle height */
102
  height: number;
103
  /** Corner radius (uniform for all corners) */
104
  r: number | RadiusValue;
105
}
106

107
type RadiusValue = number | {
108
  topLeft?: number;
109
  topRight?: number;
110
  bottomRight?: number;
111
  bottomLeft?: number;
112
};
113
```
114

115
#### Oval
116

117
Draws an oval/ellipse shape.
118

119
```typescript { .api }
120
/**
121
 * Draws an oval/ellipse shape
122
 * @param props - Oval properties
123
 * @returns JSX oval element
124
 */
125
function Oval(props: OvalProps): JSX.Element;
126

127
interface OvalProps extends DrawingNodeProps {
128
  /** Left position */
129
  x: number;
130
  /** Top position */
131
  y: number;
132
  /** Oval width */
133
  width: number;
134
  /** Oval height */
135
  height: number;
136
}
137
```
138

139
#### Line
140

141
Draws a straight line between two points.
142

143
```typescript { .api }
144
/**
145
 * Draws a straight line between two points
146
 * @param props - Line properties
147
 * @returns JSX line element
148
 */
149
function Line(props: LineProps): JSX.Element;
150

151
interface LineProps extends DrawingNodeProps {
152
  /** Start point of the line */
153
  p1: Vector;
154
  /** End point of the line */
155
  p2: Vector;
156
}
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
// Basic shapes
163
<Rect x={10} y={10} width={100} height={50}>
164
  <Paint color="green" />
165
</Rect>
166

167
<RoundedRect x={20} y={20} width={80} height={60} r={10}>
168
  <Paint color="orange" />
169
</RoundedRect>
170

171
<Oval x={0} y={0} width={120} height={80}>
172
  <Paint color="purple" />
173
</Oval>
174

175
<Line p1={{ x: 0, y: 0 }} p2={{ x: 100, y: 50 }}>
176
  <Paint color="black" strokeWidth={2} />
177
</Line>
178
```
179

180
### Advanced Shapes
181

182
Complex shape components for specialized drawing operations.
183

184
#### Path
185

186
Draws custom vector paths using SVG path syntax or SkPath objects.
187

188
```typescript { .api }
189
/**
190
 * Draws custom vector paths using SVG path syntax or SkPath objects
191
 * @param props - Path properties
192
 * @returns JSX path element
193
 */
194
function Path(props: PathProps): JSX.Element;
195

196
interface PathProps extends DrawingNodeProps {
197
  /** Path definition (SVG string or SkPath object) */
198
  path: PathDef;
199
  /** Start position along path (0.0 to 1.0) */
200
  start?: number;
201
  /** End position along path (0.0 to 1.0) */
202
  end?: number;
203
}
204

205
type PathDef = string | SkPath;
206
```
207

208
#### Points
209

210
Draws multiple points with specified drawing mode.
211

212
```typescript { .api }
213
/**
214
 * Draws multiple points with specified drawing mode
215
 * @param props - Points properties
216
 * @returns JSX points element
217
 */
218
function Points(props: PointsProps): JSX.Element;
219

220
interface PointsProps extends DrawingNodeProps {
221
  /** Array of points to draw */
222
  points: SkPoint[];
223
  /** Drawing mode for the points */
224
  mode: PointMode;
225
}
226

227
enum PointMode {
228
  Points = 0,  // Draw individual points
229
  Lines = 1,   // Draw lines between consecutive points
230
  Polygon = 2  // Draw closed polygon
231
}
232
```
233

234
#### Vertices
235

236
Draws geometry using vertex arrays with optional texture coordinates and colors.
237

238
```typescript { .api }
239
/**
240
 * Draws geometry using vertex arrays with optional texture coordinates and colors
241
 * @param props - Vertices properties
242
 * @returns JSX vertices element
243
 */
244
function Vertices(props: VerticesProps): JSX.Element;
245

246
interface VerticesProps extends DrawingNodeProps {
247
  /** Array of vertex positions */
248
  vertices: SkPoint[];
249
  /** Vertex drawing mode */
250
  mode: VertexMode;
251
  /** Optional texture coordinates for each vertex */
252
  textures?: SkPoint[];
253
  /** Optional colors for each vertex */
254
  colors?: Color[];
255
  /** Optional triangle indices for indexed drawing */
256
  indices?: number[];
257
}
258

259
enum VertexMode {
260
  Triangles = 0,
261
  TriangleStrip = 1,
262
  TriangleFan = 2
263
}
264
```
265

266
#### DiffRect
267

268
Draws a rectangle with a hole (difference between outer and inner rectangles).
269

270
```typescript { .api }
271
/**
272
 * Draws a rectangle with a hole (difference between outer and inner rectangles)
273
 * @param props - DiffRect properties
274
 * @returns JSX diff rectangle element
275
 */
276
function DiffRect(props: DiffRectProps): JSX.Element;
277

278
interface DiffRectProps extends DrawingNodeProps {
279
  /** Outer rectangle */
280
  outer: SkRRect;
281
  /** Inner rectangle (hole) */
282
  inner: SkRRect;
283
}
284
```
285

286
#### Patch
287

288
Draws a cubic Bezier patch for smooth surfaces.
289

290
```typescript { .api }
291
/**
292
 * Draws a cubic Bezier patch for smooth surfaces
293
 * @param props - Patch properties
294
 * @returns JSX patch element
295
 */
296
function Patch(props: PatchProps): JSX.Element;
297

298
interface PatchProps extends DrawingNodeProps {
299
  /** Array of 12 cubic Bezier control points defining the patch */
300
  patch: CubicBezierHandle[];
301
  /** Optional texture coordinates for the patch corners */
302
  textures?: SkPoint[];
303
  /** Optional colors for the patch corners */
304
  colors?: Color[];
305
}
306

307
interface CubicBezierHandle {
308
  pos: SkPoint;
309
  c1: SkPoint;
310
  c2: SkPoint;
311
}
312
```
313

314
#### Atlas
315

316
Draws sprites from a texture atlas with transforms.
317

318
```typescript { .api }
319
/**
320
 * Draws sprites from a texture atlas with transforms
321
 * @param props - Atlas properties
322
 * @returns JSX atlas element
323
 */
324
function Atlas(props: AtlasProps): JSX.Element;
325

326
interface AtlasProps extends DrawingNodeProps {
327
  /** Source image containing sprite atlas */
328
  image: SkImage;
329
  /** Array of source rectangles in the atlas image */
330
  sprites: SkRect[];
331
  /** Array of transforms for each sprite */
332
  transforms: SkRSXform[];
333
  /** Optional colors for each sprite */
334
  colors?: Color[];
335
}
336
```
337

338
### Utility Shapes
339

340
Special-purpose shape components for common use cases.
341

342
#### Fill
343

344
Fills the entire canvas with the current paint.
345

346
```typescript { .api }
347
/**
348
 * Fills the entire canvas with the current paint
349
 * @param props - Fill properties
350
 * @returns JSX fill element
351
 */
352
function Fill(props: FillProps): JSX.Element;
353

354
interface FillProps extends DrawingNodeProps {
355
  // No additional properties - uses canvas bounds
356
}
357
```
358

359
#### Box
360

361
Draws a box with shadow support and rounded corners.
362

363
```typescript { .api }
364
/**
365
 * Draws a box with shadow support and rounded corners
366
 * @param props - Box properties
367
 * @returns JSX box element
368
 */
369
function Box(props: BoxProps): JSX.Element;
370

371
interface BoxProps extends DrawingNodeProps {
372
  /** Box definition (SkRect or SkRRect) */
373
  box: SkRect | SkRRect;
374
}
375
```
376

377
#### FitBox
378

379
Container that fits content within specified bounds using fit modes.
380

381
```typescript { .api }
382
/**
383
 * Container that fits content within specified bounds using fit modes
384
 * @param props - FitBox properties
385
 * @returns JSX fit box element
386
 */
387
function FitBox(props: FitBoxProps): JSX.Element;
388

389
interface FitBoxProps extends DrawingNodeProps {
390
  /** How to fit the content */
391
  fit: Fit;
392
  /** Source bounds of the content */
393
  src: SkRect;
394
  /** Destination bounds to fit within */
395
  dst: SkRect;
396
}
397

398
type Fit = 
399
  | "cover"      // Cover entire dst, may crop
400
  | "contain"    // Fit entirely within dst, may have empty space
401
  | "fill"       // Stretch to fill dst exactly
402
  | "fitHeight"  // Fit to dst height, preserve aspect ratio
403
  | "fitWidth"   // Fit to dst width, preserve aspect ratio
404
  | "none"       // No scaling
405
  | "scaleDown"; // Scale down only, never up
406
```
407

408
**Usage Examples:**
409

410
```typescript
411
// Advanced shapes
412
<Path path="M 10 10 L 100 10 L 100 100 Z">
413
  <Paint color="red" />
414
</Path>
415

416
<Points 
417
  points={[{x: 10, y: 10}, {x: 50, y: 50}, {x: 90, y: 10}]}
418
  mode={PointMode.Lines}
419
>
420
  <Paint color="blue" strokeWidth={3} />
421
</Points>
422

423
<Vertices
424
  vertices={[{x: 50, y: 10}, {x: 90, y: 90}, {x: 10, y: 90}]}
425
  mode={VertexMode.Triangles}
426
  colors={["red", "green", "blue"]}
427
/>
428

429
<Fill>
430
  <Paint color="lightgray" />
431
</Fill>
432

433
<FitBox
434
  fit="contain"
435
  src={{ x: 0, y: 0, width: 200, height: 100 }}
436
  dst={{ x: 0, y: 0, width: 100, height: 100 }}
437
>
438
  {/* content to fit */}
439
</FitBox>
440
```
441

442
## Core Types
443

444
```typescript { .api }
445
// Base drawing properties
446
interface DrawingNodeProps extends TransformProps {
447
  children?: React.ReactNode;
448
}
449

450
interface TransformProps {
451
  transform?: Transform3d[];
452
  origin?: Vector;
453
  matrix?: InputMatrix;
454
}
455

456
// Geometric types
457
interface SkPoint {
458
  x: number;
459
  y: number;
460
}
461

462
interface SkRect {
463
  x: number;
464
  y: number;
465
  width: number;
466
  height: number;
467
}
468

469
interface SkRRect {
470
  rect: SkRect;
471
  rx: number;
472
  ry: number;
473
}
474

475
interface SkRSXform {
476
  scos: number;  // Cosine of rotation * scale
477
  ssin: number;  // Sine of rotation * scale
478
  tx: number;    // Translation X
479
  ty: number;    // Translation Y
480
}
481

482
// Vector and path types
483
type Vector = SkPoint | { x: number; y: number };
484
type PathDef = string | SkPath;
485
type Color = string | number | Float32Array;
486

487
// Transform types
488
type Transform3d = 
489
  | { translateX: number }
490
  | { translateY: number }
491
  | { scale: number }
492
  | { scaleX: number }
493
  | { scaleY: number }
494
  | { rotate: number }
495
  | { rotateX: number }
496
  | { rotateY: number }
497
  | { rotateZ: number }
498
  | { skewX: number }
499
  | { skewY: number };
500

501
type InputMatrix = readonly number[] | SkMatrix;
502
```