skia

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Graphics & Advanced Rendering (Skia)

React Native Skia exposes Google's Skia 2D engine to React. It draws on the **GPU** through a declarative `<Canvas>` tree, and integrates directly with Reanimated so animated values drive the canvas on the UI thread. Use it for graphical work the standard view system cannot express cleanly.

The single most important rule: **Skia is for custom, GPU-heavy drawing — not for shapes a View can already render.** If `expo-linear-gradient`, `react-native-svg`, or a styled `View` with `borderRadius` does the job, use that. Reach for Skia only when you need shaders, charts/graphs, complex vector paths, image filters/blurs, or high-frame-rate custom drawing. Never simulate graphics by stacking nested Views.

## When to reach for Skia (and when not to)

| Reach for Skia | Use something else |
| --- | --- |
| Custom SkSL shaders / procedural effects | Solid fills, rounded corners → styled `View` |
| Charts, graphs, sparklines, gauges | A single linear/radial gradient → `expo-linear-gradient` |
| Complex or animated vector paths (morphing, drawing-on) | Static icons / simple vector shapes → `react-native-svg` |
| Image filters, blurs, color matrices, displacement | A blurred backdrop → `expo-blur` (`BlurView`) |
| GPU-heavy effects (glow, noise, gradient meshes, particles) | Shadows on a card → `shadow*` / `elevation` style props |
| High-frame-rate custom drawing (audio waveforms, canvases) | Layout-driven motion → Reanimated `transform`/`opacity` |

```tsx
// Bad — faking a ring/progress arc with nested Views and overflow tricks
<View style={styles.ringOuter}>
  <View style={styles.ringMask} />
  <View style={[styles.ringFill, { transform: [{ rotate }] }]} />
</View>

// Good — an actual arc path drawn on the GPU
<Canvas style={{ width: 120, height: 120 }}>
  <Path path={arcPath} style="stroke" strokeWidth={10} strokeCap="round" color="#3478f6" />
</Canvas>
```

```tsx
// Bad — a whole Skia canvas just to draw one gradient rectangle
<Canvas style={{ flex: 1 }}>
  <Rect x={0} y={0} width={width} height={height}>
    <LinearGradient start={vec(0, 0)} end={vec(0, height)} colors={['#3478f6', '#0a1a3f']} />
  </Rect>
</Canvas>

// Good — plain, cheap, no GPU canvas needed
import { LinearGradient } from 'expo-linear-gradient';
<LinearGradient colors={['#3478f6', '#0a1a3f']} style={{ flex: 1 }} />
```

## GPU vs CPU cost

Skia rendering happens on the GPU, but the *setup* around it runs on the CPU (usually the JS thread). Cheap-looking code can be expensive for the wrong reason. Budget both.

| Cost lives on the GPU | Cost lives on the CPU / JS thread |
| --- | --- |
| Blurs, shadows, `saveLayer`/layer effects | Building `Skia.Path`/`Skia.Paint` objects every render |
| Large fills, overdraw (stacked translucent layers) | Constructing/parsing path strings per frame |
| Runtime shaders with heavy per-pixel math | Decoding images synchronously, large bitmaps |
| Many blend/color-filter passes | Re-creating the `<Canvas>` subtree on each state change |

Rules of thumb:
- **Blur and shadow are the most expensive GPU effects.** Keep blur radii modest, and never animate a large blur every frame on a full-screen surface.
- **Overdraw kills fill rate.** Avoid stacking many semi-transparent layers; flatten where you can.
- **Do object creation once.** Memoize paths, paints, and fonts so the CPU isn't rebuilding them 60–120×/second.
- **Static content → render once.** Bake unchanging drawing into a `Picture` (see below) instead of re-issuing draw calls every frame.

## The declarative `<Canvas>` API

Compose drawing as JSX. Elements are drawn in document order (painter's model — later siblings paint on top).

```tsx
import {
  Canvas, Fill, Group, Circle, Rect, RoundedRect, Path,
  LinearGradient, RadialGradient, Blur, Shadow, Skia, vec,
} from '@shopify/react-native-skia';

export const Badge = () => {
  return (
    <Canvas style={{ width: 200, height: 200 }}>
      {/* Background fill spanning the whole canvas */}
      <Fill color="#0a1a3f" />

      {/* A rounded rect with a gradient paint (child = paint source) */}
      <RoundedRect x={20} y={20} width={160} height={160} r={24}>
        <LinearGradient
          start={vec(20, 20)}
          end={vec(180, 180)}
          colors={['#3478f6', '#8e5cff']}
        />
      </RoundedRect>

      {/* A circle with a soft blur applied via a child effect */}
      <Circle cx={100} cy={100} r={40} color="#ffffff">
        <Blur blur={6} />
      </Circle>

      {/* A stroked path */}
      <Path
        path="M60 100 L90 130 L140 70"
        style="stroke"
        strokeWidth={8}
        strokeCap="round"
        strokeJoin="round"
        color="#00e0a8"
      />
    </Canvas>
  );
}
```

Key points:
- **Paint is set by props or by children.** `color`, `style="stroke" | "fill"`, `strokeWidth`, `opacity` are props. Effects and shaders (`LinearGradient`, `Blur`, `Shadow`, `ColorMatrix`, `Shader`) are supplied as *children* and apply to the parent shape.
- **`Fill`** paints the entire canvas — use it for backgrounds and as the surface for a full-screen shader.
- **`Group`** batches children and applies a shared `transform`, `clip`, `opacity`, `blendMode`, or `layer`. Prefer one `Group` transform over transforming each child.
- **Gradients** take `start`/`end` (or `c`/`r` for radial) as `vec(x, y)` points in canvas space, plus a `colors` array and optional `positions`.

### `Group` transforms and clipping

```tsx
// Good — one transform on the Group moves/rotates the whole subtree
<Group transform={[{ translateX: 50 }, { rotate: Math.PI / 6 }]} origin={vec(100, 100)}>
  <Circle cx={100} cy={100} r={30} color="#3478f6" />
  <Rect x={80} y={80} width={40} height={40} color="#8e5cff" />
</Group>

From hzblj/skills, MIT.

More from hzblj/skills