p5.tree/matrix

Reading the camera's matrices, and mapping points and directions between world, eye and screen.

Read the current camera's matrices with mat4Proj, mat4View, mat4Eye and mat4Model, or their products mat4PV, mat4MV and mat4PMV; each is written into the buffer you pass. Reach for them when a custom shader needs a uniform, when you draw from a second Camera, or when you want to know where translate, rotate and scale have put you. projNear, projFar and projFov read the current projection's numbers directly.

mapLocation and mapDirection carry a point or a direction between world, eye, screen space and the model transform stack. pixelRatio, drawingBufferSize, fragCoord and texelSize answer the pixel-level questions that usually follow.

p5

`treeHost()`

The sketch's host context — the @nakednous/host object behind every handle, track, helm and stream p5.tree creates, one per canvas. Reach for it when you want a host construct p5.tree has no verb for: labels, the DOM text layer over the canvas, or orbit, the camera gesture that replaces orbitControl on a camera state. Null before createCanvas().

Returns Object The host, or null.

Labels through the host: DOM text at a world anchor and in the HUD corner, no font needed

`mat4Proj(out)`

The current projection matrix, copied into your buffer. It follows the latest perspective() or ortho() call; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.

Returns Float32Array|ArrayLike|p5.Matrix out

The live projection, dumped; press the mouse for ortho

`mat4Persp(out, left, right, bottom, top, near, far, [ndcZMin], [ndcYSign])`

Builds a perspective projection matrix from six frustum bounds, without touching the camera. Pair it with mat4Eye to draw or use a virtual camera, as the example does; the optional depth-range arguments default to those of the current canvas.

Parameter	Type	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`	16-element destination.
`left`	`number`
`right`	`number`
`bottom`	`number`
`top`	`number`
`near`	`number`
`far`	`number`
`ndcZMin` optional	`number`	`WEBGL` (−1) or `WEBGPU` (0).
`ndcYSign` optional	`number`	Sign of the NDC y axis.

Returns Float32Array|ArrayLike|p5.Matrix out

A frustum from numbers alone: a lookat eye plus a perspective projection

`mat4Ortho(out, left, right, bottom, top, near, far, [ndcZMin], [ndcYSign])`

Builds an orthographic projection matrix from six box bounds, without touching the camera. Pair it with mat4Eye for a virtual camera, as the example does; the optional depth-range arguments default to those of the current canvas.

Parameter	Type	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`	16-element destination.
`left`	`number`
`right`	`number`
`bottom`	`number`
`top`	`number`
`near`	`number`
`far`	`number`
`ndcZMin` optional	`number`	`WEBGL` (−1) or `WEBGPU` (0).
`ndcYSign` optional	`number`	Sign of the NDC y axis.

Returns Float32Array|ArrayLike|p5.Matrix out

An orthographic box from numbers alone

`mat4Model(out)`

The current transform stack as a matrix, copied into your buffer. Call it between push and pop to capture where translate, rotate and scale have put you; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.

Returns Float32Array|ArrayLike|p5.Matrix out

The transform stack, read from inside push/pop

`mat4View(out, [lookat])`

The current camera's view matrix, copied into your buffer. Pass nine numbers after the buffer (eye, center, up) to build a standalone lookat instead, without touching the camera; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`lookat` optional	`...number`		`ex, ey, ez, cx, cy, cz, ux, uy, uz`.

Returns Float32Array|ArrayLike|p5.Matrix out

The live view matrix, dumped; orbit to watch it change

Standalone lookat: depth from a virtual camera, no camera state touched

`mat4Eye(out, [lookat])`

The current camera's placement in the world as a matrix, copied into your buffer; its last column is the camera position. Pass nine numbers after the buffer (eye, center, up) to build a standalone lookat instead, without touching the camera; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`lookat` optional	`...number`		`ex, ey, ez, cx, cy, cz, ux, uy, uz`.

Returns Float32Array|ArrayLike|p5.Matrix|null out, or null if singular.

Current camera: the last column is the camera position

Standalone lookat: a virtual camera's frustum, no camera state touched

`mat4PV(out, [opts])`

The projection and view matrices combined, copied into your buffer. Compute it once per frame and pass it as mat4PV to mapLocation to project many points cheaply, as the example does; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`opts` optional	`{ mat4Proj?, mat4View? }`		Precomputed matrices to skip redundant work.

Returns Float32Array|ArrayLike|p5.Matrix out

One PV per frame projects every corner: HUD dots pinned to a box

`mat4PVInv(out, [opts])`

The inverse of the combined projection and view matrices, copied into your buffer; returns null when it cannot be inverted. Pass a precomputed mat4PV in the options to skip that multiplication, then hand both to mapLocation for screen-to-world work, as the example does; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`opts` optional	`{ mat4Proj?, mat4View?, mat4PV? }`		Precomputed matrices to skip redundant work.

Returns Float32Array|ArrayLike|p5.Matrix|null out, or null if singular.

Unproject the mouse at the depth of the origin, PV and its inverse precomputed

`mat4MV(out, [opts])`

The transform stack as seen from the current camera, copied into your buffer. Its last column gives the eye-space position of the local origin, which the example uses as a depth; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`opts` optional	`{ mat4Model?, mat4View? }`		Precomputed matrices to skip redundant work.

Returns Float32Array|ArrayLike|p5.Matrix out

Eye-space depth from the modelview's last column: the nearer sphere lights up

`mat4PMV(out, [opts])`

The full clip-space transform for what you are about to draw, copied into your buffer. Feed it to a custom vertex shader as a uniform, as the example does; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`opts` optional	`{ mat4Proj?, mat4Model?, mat4View? }`		Precomputed matrices to skip redundant work.

Returns Float32Array|ArrayLike|p5.Matrix out

Your own clip transform, fed to a custom vertex shader

`mat3Normal(out, [opts])`

The 3×3 matrix that carries surface normals into eye space for lighting, copied into your buffer. Pass a precomputed mat4MV in the options to skip redundant work, and feed the result to a custom shader as the example does; needs a WEBGL canvas.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		9-element destination.
`opts` optional	`{ mat4Model?, mat4View?, mat4MV? }`		Precomputed matrices to skip redundant work.

Returns Float32Array|ArrayLike|p5.Matrix out

Lambert shading with your own normal matrix

`mat4Location(out, from, to)`

The matrix that takes points expressed in one frame into another frame's coordinates, copied into your buffer. Both frames are model matrices such as those captured with mat4Model; returns null when the target frame cannot be inverted.

Parameter	Type	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`	16-element destination.
`from`	`Float32Array\|ArrayLike\|p5.Matrix`
`to`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|ArrayLike|p5.Matrix|null out, or null if to is singular.

Frame A's origin in frame B's coordinates: a line drawn inside B lands on A

`mat3Direction(out, from, to)`

The 3×3 matrix that converts a direction's coordinates from one frame to another, ignoring translation, copied into your buffer. Both frames are model matrices such as those captured with mat4Model; the same conversion mapDirection does between frames. Returns null when the destination frame cannot be inverted.

Parameter	Type	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`	9-element destination.
`from`	`Float32Array\|ArrayLike\|p5.Matrix`
`to`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|ArrayLike|p5.Matrix|null out, or null if to is singular.

A direction given in frame A, expressed in frame B: drawn inside each frame, the two lines stay parallel

const a = new Float32Array(16)
const b = new Float32Array(16)
const D = new Float32Array(9)
const d = [0.6, -0.8, 0]   // a direction in frame A's coordinates

function setup() {
  createCanvas(400, 300, WEBGL)
}

function draw() {
  background('#138D75')
  orbitControl()
  axes()
  noFill()
  // frame A spins about y; the direction is drawn in A's own coordinates
  push()
  translate(-90, 0, 0)
  rotateY(frameCount * 0.01)
  mat4Model(a)
  stroke('#ff4fd8')
  box(30)
  axes({ size: 40 })
  stroke('white')
  line(0, 0, 0, 60 * d[0], 60 * d[1], 60 * d[2])
  pop()
  // frame B spins about x; the same direction, converted to B's coordinates
  push()
  translate(90, 0, 0)
  rotateX(frameCount * 0.02)
  mat4Model(b)
  stroke('#ffd166')
  box(30)
  axes({ size: 40 })
  mat3Direction(D, a, b)
  const e = mul3(D, d)
  stroke('white')
  line(0, 0, 0, 60 * e[0], 60 * e[1], 60 * e[2])
  pop()
}

// column-major mat3 times vec3
function mul3(m, v) {
  return [
    m[0] * v[0] + m[3] * v[1] + m[6] * v[2],
    m[1] * v[0] + m[4] * v[1] + m[7] * v[2],
    m[2] * v[0] + m[5] * v[1] + m[8] * v[2]
  ]
}

`mat4Mul(out, A, B)`

Multiplies two matrices into your buffer. Applying the product places the second matrix's frame inside the first one's, as the example shows.

Parameter	Type	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`	16-element destination.
`A`	`Float32Array\|ArrayLike\|p5.Matrix`
`B`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|ArrayLike|p5.Matrix out

A · B places B inside A's frame

`mat4Invert(out, src)`

Inverts a matrix into your buffer, or returns null when it cannot be inverted. Applying a transform and then its inverse lands you back where you started, as the example shows.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.
`src`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|ArrayLike|p5.Matrix|null out, or null if singular.

M · inv(M) = I: undo the stack from inside it

`mat4ToTranslation(out3, m)`

Reads the position part of a matrix into a 3-element buffer or Vector. Handy for finding where a nested transform stack ended up, as the example shows.

Parameter	Type	Default	Description
`out3`	`Float32Array\|number[]\|p5.Vector`		3-element destination.
`m`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|number[]|p5.Vector out3

Where a nested transform stack ends up

`mat4ToScale(out3, m)`

Reads the scale part of a matrix into a 3-element buffer or Vector. Works for transforms built from translate, rotate and scale, as in the example.

Parameter	Type	Default	Description
`out3`	`Float32Array\|number[]\|p5.Vector`		3-element destination.
`m`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|number[]|p5.Vector out3

Scale recovered from a transform, re-applied to a clone

`mat4ToRotation(out4, m)`

Reads the rotation part of a matrix into a 4-element quaternion buffer. Re-apply it with rotateQuat to give another object the same orientation, as the example does.

Parameter	Type	Default	Description
`out4`	`Float32Array\|number[]`		4-element destination.
`m`	`Float32Array\|ArrayLike\|p5.Matrix`

Returns Float32Array|number[] out4

Orientation recovered as a quaternion, re-applied to a clone

`projIsOrtho()`

Whether the current projection is orthographic.

Returns boolean

Perspective, or orthographic while the mouse is pressed

`projNear()`

Near clip distance of the current projection (positive).

Returns number

Near and far read back; the mouse drives near through the box

`projFar()`

Far clip distance of the current projection (positive).

Returns number

Near and far read back; the mouse drives far through the box

`projLeft()`

Left extent of the current projection's near plane (camera space; negative).

Returns number

Near-plane extents of a perspective whose fov follows the mouse

`projRight()`

Right extent of the current projection's near plane (camera space).

Returns number

Near-plane extents of a perspective whose fov follows the mouse

`projTop()`

Top extent of the current projection's near plane (camera space).

Returns number

Near-plane extents of a perspective whose fov follows the mouse

`projBottom()`

Bottom extent of the current projection's near plane (camera space; negative).

Returns number

Near-plane extents of a perspective whose fov follows the mouse

`projFov()`

Vertical field of view of the current projection, in radians.

Returns number

Vertical and horizontal fov, the vertical one driven by the mouse

`projHfov()`

Horizontal field of view of the current projection, in radians.

Returns number

Vertical and horizontal fov, the vertical one driven by the mouse

`mapLocation([point], [opts])`

Converts a point from one coordinate space to another: world, screen, eye, NDC, the model transform stack, or any matrix frame. Pick the spaces with the from and to options (eye to world by default); pass an out buffer to reuse it frame after frame, or omit it to get a fresh Vector back. Needs a WEBGL canvas.

Parameter	Type	Default	Description
`point` optional	`Float32Array\|number[]\|p5.Vector`		Input point. Default: `ORIGIN`.
`opts` optional	`{ out?: Float32Array \| number[] \| p5.Vector, from?: string \| Float32Array \| number[] \| p5.Matrix, to?: string \| Float32Array \| number[] \| p5.Matrix, mat4Eye?: Float32Array \| number[] \| p5.Matrix, mat4Proj?: Float32Array \| number[] \| p5.Matrix, mat4View?: Float32Array \| number[] \| p5.Matrix, mat4PV?: Float32Array \| number[] \| p5.Matrix, mat4PVInv?: Float32Array \| number[] \| p5.Matrix, }`

Returns Float32Array|number[]|p5.Vector opts.out if provided, else a fresh Vector.

WORLD to SCREEN: a HUD label pinned to a 3D point

SCREEN to WORLD: the mouse, pushed to the depth of the origin

MODEL to WORLD: where the transform stack put the origin

`mapDirection([dir], [opts])`

Converts a direction from one coordinate space to another, ignoring translation. Pick the spaces with the from and to options (eye to world by default, so with no arguments it returns the camera's look direction); pass an out buffer to reuse it frame after frame, or omit it to get a fresh Vector back. Needs a WEBGL canvas.

Parameter	Type	Default	Description
`dir` optional	`Float32Array\|number[]\|p5.Vector`		Input direction. Default: −Z (look direction).
`opts` optional	`{ out?: Float32Array \| number[] \| p5.Vector, from?: string \| Float32Array \| number[] \| p5.Matrix, to?: string \| Float32Array \| number[] \| p5.Matrix, mat4Eye?: Float32Array \| number[] \| p5.Matrix, mat4Proj?: Float32Array \| number[] \| p5.Matrix, mat4View?: Float32Array \| number[] \| p5.Matrix, }`

Returns Float32Array|number[]|p5.Vector opts.out if provided, else a fresh Vector.

EYE to WORLD, the default: the camera's look direction

MODEL to WORLD: a spinning object's local X, drawn at the world origin

`pixelRatio([worldPos], [opts])`

How many world units one screen pixel covers at a given world position, so you can draw things at a constant on-screen size, as the example does. The position is optional; needs a WEBGL canvas.

Parameter	Type	Default	Description
`worldPos` optional	`Float32Array\|number[]\|p5.Vector`
`opts` optional	`{ mat4Proj?, mat4View? }`

Returns number

A constant screen-size dot: world radius = pixels × pixelRatio

`drawingBufferSize()`

The canvas size in window space — the drawing buffer's physical (device) pixels, accounting for pixel density. Pass it to a shader as its resolution uniform, as the example does; needs a WEBGL canvas.

Returns number[] [w, h]

gl_FragCoord normalised by the physical canvas size

`fragCoord([x], [y])`

The gl_FragCoord of a screen-space pixel, the mouse by default. Pass it to a shader as its pointer uniform beside drawingBufferSize(), as the example does; needs a WEBGL canvas.

Parameter	Type	Default	Description
`x` optional	`number`	`mouseX`	Canvas x.
`y` optional	`number`	`mouseY`	Canvas y, down.

Returns number[] [fx, fy]

Move the mouse over the canvas: an amber disc 40 device pixels in radius follows it — the fragment shader compares its own gl_FragCoord with uMouse, the mouse's.

`texelSize(img)`

The size of one texel of an image, framebuffer or graphics, as a fraction of its width and height. Pass it to a shader to step between neighbouring pixels, as the example does.

Parameter	Type	Default	Description
`img`	`{ width:number, height:number }`

Returns number[] [1/(w×pd), 1/(h×pd)]

Neighbour sampling in a custom shader, stepped by one texel

let img, sh

const vert = `#version 300 es
precision highp float;
in vec4 aPosition;
in vec2 aTexCoord;
uniform mat4 uProjectionMatrix;
uniform mat4 uModelViewMatrix;
out vec2 vUv;
void main() {
  vUv = aTexCoord;
  gl_Position = uProjectionMatrix * uModelViewMatrix * aPosition;
}`

function setup() {
  createCanvas(400, 300, WEBGL)
  // a procedural checker
  img = createImage(64, 64)
  const a = color('#ff4fd8'), b = color('white')
  img.loadPixels()
  for (let y = 0; y < 64; y++) {
    for (let x = 0; x < 64; x++) img.set(x, y, ((x >> 3) + (y >> 3)) & 1 ? a : b)
  }
  img.updatePixels()
  sh = createShader(vert, frag)
}

function draw() {
  background('#138D75')
  shader(sh)
  sh.setUniform('uTex', img)
  sh.setUniform('uTexel', texelSize(img))
  sh.setUniform('uRadius', map(mouseX, 0, width, 0, 3))   // blur in texel steps
  noStroke()
  plane(240, 240)
}

p5.Camera

`mat4Proj(out)`

A second camera's own projection matrix, copied into your buffer. It follows whatever Camera.perspective, Camera.ortho or Camera.frustum call that camera received; needs a WEBGL canvas and a camera made with createCamera().

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.

Returns Float32Array|ArrayLike|p5.Matrix out

A second camera's frustum from its own eye and projection matrices

`mat4View(out)`

A second camera's view matrix, copied into your buffer. Hand it to mapLocation to measure points as that camera sees them, as the example does; needs a WEBGL canvas and a second camera.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.

Returns Float32Array|ArrayLike|p5.Matrix out

Depth of a point as seen by a second camera

`mat4Eye(out)`

A second camera's placement in the world as a matrix, copied into your buffer. Apply it with applyMatrix to draw something at that camera, as the example does; needs a WEBGL canvas and a second camera.

Parameter	Type	Default	Description
`out`	`Float32Array\|ArrayLike\|p5.Matrix`		16-element destination.

Returns Float32Array|ArrayLike|p5.Matrix|null out, or null if singular.

The camera body drawn from its own eye matrix