---
title: "Frames & coordinates"
description: "Frames are how a generator measures its pixels."
group: "space"
groupTitle: "Shapes, frames & warps"
categoryId: "frames"
categorySlug: "frames"
wordCount: 7
curated: true
sourceUrl: "https://github.com/shader-effects-inc/shaders/blob/main/packages/core/src/std/frames.ts"
editUrl: "https://github.com/shader-effects-inc/shaders/edit/main/packages/core/docs/std/frames.md"
---

# Frames & coordinates

Frames are how a generator measures its pixels. Instead of raw uv you get named numbers
ready to use: the distance from a centre, how far along and across a line between two
points, or the axes of a chosen direction. [`surfaceOf`](/docs/primitives/frames/surfaceof) is the starting point: the canvas's
`uv` (0–1, y down), its size in pixels and its aspect ratio. Every frame is aspect-corrected,
so 1 is the canvas height and a circle stays round on a wide canvas.

Build a frame from your position props with `p('name')`, call it with `params` and the
surface, and pull out the numbers you need. Shape them with `math` and hand the result to a
palette, a `light` word or `compose` to make the pixel's color. [`direction`](/docs/primitives/frames/direction) and
[`directionFrame`](/docs/primitives/frames/directionframe) take an angle in degrees, 0 pointing right and turning clockwise on screen.

```ts
import {frames} from 'shaders/std'
```

## Reach for it when

| When you need | Use |
|---|---|
| the canvas uv, size and aspect at the top of a paint | [`surfaceOf`](/docs/primitives/frames/surfaceof) |
| a pattern anchored to the whole canvas, not the layer's box | [`rawSurfaceOf`](/docs/primitives/frames/rawsurfaceof) |
| the distance from a draggable centre | [`centredFrame`](/docs/primitives/frames/centredframe) |
| the position along and across a line between two points | [`segmentFrame`](/docs/primitives/frames/segmentframe) |
| a light or flow angle as a vector | [`direction`](/docs/primitives/frames/direction) |
| a grain, weave or streak running at an angle | [`directionFrame`](/docs/primitives/frames/directionframe) |
| a kaleidoscope | [`sectorFold`](/docs/primitives/frames/sectorfold) |

## Example

```ts
import {defineShader, p, frames, math, transformColor, transformPosition} from 'shaders/std'

const {surfaceOf, segmentFrame} = frames
const {div, exp, mul, neg, smoothstep, sub, vec4} = math

// A bar of light between two draggable points: bright on the line, fading across it, feathered at both ends.
export const LightBar = defineShader({
  name: 'LightBar',
  props: {
    from: {default: {x: 0.2, y: 0.5}, transform: transformPosition},
    to: {default: {x: 0.8, y: 0.5}, transform: transformPosition},
    color: {default: '#7ad7ff', transform: transformColor},
    width: {default: 0.05},
    feather: {default: 0.1},
  },
  paint: (params) => {
    const u = params.uniforms
    const {along, across, length} = segmentFrame({from: p('from'), to: p('to')})(params, surfaceOf(params))
    const profile = exp(neg(div(mul(across, across), mul(u.width, u.width))))
    const ends = mul(smoothstep(0, u.feather, along), smoothstep(0, u.feather, sub(length, along)))
    const bar = mul(profile, ends)
    return vec4(mul(u.color.member('rgb'), bar), bar)
  },
})
```

## Types

| Type | What it is |
|---|---|
| `CentredFrame` | What `centredFrame` gives you for each pixel. |
| `DirectionFrame` | What `directionFrame` gives you. |
| `SegmentFrame` | What `segmentFrame` gives you for each pixel. |

## Words

- [`surfaceOf`](/docs/primitives/frames/surfaceof) — The canvas a generator paints on: its `uv`, its `viewport` size in pixels and its `aspect`.
- [`centredFrame`](/docs/primitives/frames/centredframe) — A frame centred on a position prop: each pixel's offset from the centre and its distance.
- [`segmentFrame`](/docs/primitives/frames/segmentframe) — A frame along the line between two position props: how far each pixel is along it and across it.
- [`direction`](/docs/primitives/frames/direction) — A direction in degrees as a unit vector.
- [`directionFrame`](/docs/primitives/frames/directionframe) — The two axes of a direction given in degrees, for patterns that run along it.
- [`sectorFold`](/docs/primitives/frames/sectorfold) — Fold a point into one mirrored wedge around a centre: the kaleidoscope fold.
- [`rawSurfaceOf`](/docs/primitives/frames/rawsurfaceof) — The canvas like `surfaceOf`, but always measured against the whole canvas, never a fitted box.