Skip to content

Unlock custom brushes, natural fill effects and intuitive hatching in p5.js

11.2 KB
Raw Blame

p5.brush — Standalone Build

The standalone build (dist/brush.js / dist/brush.esm.js) runs without p5.js. It needs nothing beyond a WebGL2-capable browser.

For the p5 build see the main README.


Table of Contents


Installation

Script tag (UMD)

Download dist/brush.js from this repository and include it in your HTML. It exposes a global brush object.

<script src="path_to/brush.js"></script>

ESM module via npm

// After: npm install p5.brush
import * as brush from 'p5.brush/standalone';

ESM module via local file

import * as brush from './dist/brush.esm.js';

Setup

Using brush.createCanvas()

The simplest path. Creates a <canvas> element, attaches it to the DOM, and automatically loads it as the draw target — no separate brush.load() call needed.

brush.createCanvas(width, height, options?)

Options:

Property Description
pixelDensity Backing resolution multiplier. Defaults to 1. Pass window.devicePixelRatio for sharp output on HiDPI screens.
parent CSS selector string or DOM element to append the canvas to.
id id attribute for the created <canvas>.
import * as brush from './dist/brush.esm.js';

brush.createCanvas(800, 600, {
  parent: '#sketch-container',
  pixelDensity: window.devicePixelRatio,
});

brush.scaleBrushes(4);
brush.angleMode(brush.DEGREES);

Bringing your own canvas

If you create the canvas element yourself (or use an OffscreenCanvas), call brush.load(canvas) once to register it as the draw target.

const canvas = document.createElement('canvas');
canvas.width  = 800;
canvas.height = 600;
document.body.appendChild(canvas);

brush.load(canvas);

brush.load() also lets you switch between multiple canvases at runtime — call it again with a different canvas whenever you want to redirect drawing.

WebGL2 required. Both brush.createCanvas() and brush.load() require the canvas to support a WebGL2 context. Make sure the browser supports it before calling either.


Frame lifecycle

Unlike the p5 build (where p5 handles compositing automatically), the standalone build requires you to explicitly flush and clear each frame.

brush.render()

Flushes any pending stroke and fill compositing into the active canvas. Call this at the end of each drawing pass — once per frame if you are animating, or once after a static draw.

brush.clear('#f5f0e0');
brush.push();
brush.translate(-W / 2, -H / 2);

brush.set('HB', '#333', 1);
brush.line(100, 100, 700, 500);

brush.pop();
brush.render(); // ← flush to canvas

brush.clear(color?)

Clears the active canvas. Without arguments, clears to transparent. With a color argument, clears to that color at full opacity.

brush.clear();            // transparent
brush.clear('#f5f0e0');   // off-white background
brush.clear(240, 235, 220); // RGB

Transforms

The standalone build manages its own transform stack, independent of any external library.

brush.push()           // save current transform + brush state
brush.pop()            // restore
brush.translate(x, y)
brush.rotate(angle)    // angle follows current angleMode
brush.scale(x, y?)     // omit y to scale uniformly

These work exactly like p5's equivalents. push() and pop() save and restore both the transform matrix and brush state (stroke, fill, hatch settings).

Origin

The WebGL canvas origin is at the center of the canvas. To work in top-left coordinates, shift the origin at the start of each frame:

brush.push();
brush.translate(-W / 2, -H / 2);

// draw everything here...

brush.pop();
brush.render();

Angle mode

brush.angleMode(brush.DEGREES);  // all angle inputs in degrees
brush.angleMode(brush.RADIANS);  // all angle inputs in radians (default)

The exported constants are brush.DEGREES and brush.RADIANS. The mode affects every API that accepts an angle: brush.rotate(), brush.hatch(), brush.fillBleed(), brush.flowLine(), brush.arc(), brush.move(), brush.addField(), and brush.Position.moveTo().

brush.angleMode(brush.DEGREES);
brush.hatch(8, 45);        // 45°
brush.flowLine(x, y, 100, 90); // pointing down

For custom vector fields, pass { angleMode: 'radians' } if your generator writes radians:

brush.addField('myField', (t, field) => {
  for (let c = 0; c < field.length; c++)
    for (let r = 0; r < field[0].length; r++)
      field[c][r] = Math.sin(c * 0.3 + t) * Math.PI;
  return field;
}, { angleMode: 'radians' });

Seeding

brush.seed(n)        // seed the internal RNG
brush.noiseSeed(n)   // seed the internal noise generator

Call before drawing to get reproducible results. Both accept any number.

brush.seed(42);
brush.noiseSeed(42);

API reference

All stroke, fill, hatch, primitive, field, and class APIs are identical to the p5 build. See the p5 API reference in README.md for the full documentation of every function.

The sections below list only what is different or exclusive to the standalone build.


Configuration

brush.createCanvas(width, height, options?)

Creates a <canvas> element and loads it as the draw target. Returns the canvas element.

See Setup above for the full option list and examples.


brush.load(canvas)

Loads an existing HTMLCanvasElement or OffscreenCanvas as the draw target. Only needed when you create the canvas yourself or want to switch targets.

// External canvas
const canvas = document.createElement('canvas');
canvas.width = 800; canvas.height = 600;
brush.load(canvas);

// OffscreenCanvas (e.g. in a Web Worker)
const offscreen = new OffscreenCanvas(800, 600);
brush.load(offscreen);

brush.render()

Flushes compositing. Must be called at the end of every drawing pass. See Frame lifecycle.


brush.clear(color?)

Clears the canvas to transparent (no args) or to a solid color. See Frame lifecycle.


Transforms

brush.push() / brush.pop()

Save and restore the current transform matrix and all brush state (stroke, fill, hatch).

brush.translate(x, y)

brush.rotate(angle)

Angle follows the current brush.angleMode().

brush.scale(x, y?)

Omit y to scale uniformly.


Angle mode

brush.angleMode(mode)

Set to brush.DEGREES or brush.RADIANS. Default is brush.RADIANS.

brush.DEGREES / brush.RADIANS

Exported string constants used with brush.angleMode().


Seeding

brush.seed(n)

Seed the internal RNG.

brush.noiseSeed(n)

Seed the internal noise generator.


Custom tip brushes

In the p5 build, the tip function receives a real p5.Graphics object so any p5 drawing command works. In the standalone build it receives a minimal 2D-canvas-backed surface that deliberately mirrors the same method names, so most tip functions are portable between builds.

Available methods

Method Notes
push() / pop() Save / restore transform and state
translate(x, y)
scale(x, y?)
rotate(angle) Always radians — ignores brush.angleMode()
fill(value) Grayscale number 0–255, [r, g, b] / [r, g, b, a] array, or CSS color string
noFill()
stroke(value) Grayscale number 0–255, [r, g, b] / [r, g, b, a] array, or CSS color string
noStroke()
strokeWeight(value)
rect(x, y, w, h)
circle(x, y, diameter)
ellipse(x, y, w, h)
line(x1, y1, x2, y2)
beginShape() / vertex(x, y) / endShape(close?)
loadPixels() / updatePixels() / pixels Raw pixel access

Coordinate space

The tip surface is 500×500 px internally but the user-facing coordinate space is 100×100 units with the origin at the centre (the library applies a ×5 scale and a translate to the centre automatically). Draw within roughly ±50 units.

Dark fills → high opacity. Light/white → transparent. The library converts the tip to a white-tinted mask so it can be tinted with any brush color at draw time.

Colors

Colors accept a grayscale number (0 = black/opaque, 255 = white/transparent), an array ([60, 47, 30], or [60, 47, 30, 0.5] with alpha in 0–1), separate r, g, b arguments, or a CSS color string the browser recognises ('red', '#3a2f1e', 'rgb(60, 47, 30)'). p5.Color objects are not supported.

A value that cannot be parsed throws Invalid color value "..." rather than drawing something arbitrary.

// ✓ works in both builds
brush.add('diamond', {
  type: 'custom',
  weight: 5,
  scatter: 0.08,
  opacity: 23,
  spacing: 0.6,
  pressure: [0.5, 1.5, 0.5],
  tip: (_m) => {
    _m.rotate(Math.PI / 4); // radians — works in both builds
    _m.rect(-1.5, -1.5, 3, 3);
  },
  rotate: 'natural',
  markerTip: false,
});
// ✗ p5 build only — p5.Color and angleMode-aware rotate
brush.add('p5only', {
  type: 'custom',
  tip: (_m) => {
    _m.fill(color(30, 20, 10)); // p5.Color — standalone will break
    _m.rotate(45);              // degrees via angleMode — standalone always uses radians
    _m.rect(-2, -2, 4, 4);
  },
});

Differences from the p5 build

p5 build Standalone build
Canvas creation createCanvas(w, h, WEBGL) brush.createCanvas(w, h)
Loading an existing canvas brush.load(p5Graphics|framebuffer) for offscreen targets brush.load(htmlCanvas|offscreenCanvas) for external canvases
Compositing flush Automatic brush.render() required each frame
Clearing background() brush.clear(color?)
Transforms p5's push/pop, translate, rotate, scale brush.push/pop, brush.translate, brush.rotate, brush.scale
Angle mode p5's angleMode() brush.angleMode(brush.DEGREES | brush.RADIANS)
Seeding randomSeed() / noiseSeed() seed the library too brush.seed() / brush.noiseSeed()
Instance mode brush.instance(p) Not applicable (brush.instance() is a no-op)
Framebuffer targets Supported via brush.load(framebuffer) Not supported

Full example

import * as brush from './dist/brush.esm.js';

const W = 800, H = 600;

// Create and load the canvas in one call
brush.createCanvas(W, H, {
  parent: document.body,
  pixelDensity: window.devicePixelRatio,
});

brush.scaleBrushes(4);
brush.angleMode(brush.DEGREES);
brush.seed(42);

// Draw
brush.clear('#f5f0e0');
brush.push();
brush.translate(-W / 2, -H / 2);

brush.set('HB', '#1a2a3a', 1);
brush.line(80, 80, 720, 520);

brush.fill('#003c32', 110);
brush.fillBleed(0.2, 'out', 0);
brush.noStroke();
brush.circle(W / 2, H / 2, 120);

brush.hatchStyle('HB', '#1a2a3a', 0.8);
brush.hatch(6, 45, { rand: 0.05 });
brush.noFill();
brush.rect(100, 100, 200, 160, 'corner');
brush.noHatch();

brush.pop();
brush.render(); // flush to canvas