Skip to content

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

docs: document standalone custom tip surface — methods, color constraints, radians-only rotate

acamposuribec7e123bbf96d
diff --git a/README.md b/README.md
index 3221e5e..c4e0251 100644
--- a/README.md
+++ b/README.md
@@ -316,7 +316,7 @@ Functions for managing brush behaviors and properties.
- `weight`: How thick the brush is, in canvas units.
- `scatter`: How much the stroke wobbles sideways. Higher = more spread. (in canvas units)
- `sharpness`: A number from 0 to 1. Lower = softer/fuzzier edge. Only matters for `"default"` type.
- - `grain`: Controls how dense the texture is. Higher = smoother, more continuous line. Only matters for `"default"` type.
+ - `grain`: Controls how dense the texture is. Higher = smoother, more continuous line. Only matters for `"default"` and `"spray"` types.
- `opacity`: How opaque each mark is, from 0 to 255. Pressure also affects this.
- `spacing`: Gap between brush tip stamps along the stroke. `1` means no overlap, lower values create denser strokes.
- `pressure`: Controls how the brush size changes from start to end of a stroke. Use a simple array — the easiest way:
@@ -326,7 +326,7 @@ Functions for managing brush behaviors and properties.
- These simple/custom pressure modes include a subtle amount of per-stroke variation automatically, so repeated strokes feel less mechanical.
- Advanced option for power users: use the library's built-in Gaussian pressure profile explicitly with an object like `{ mode: "gaussian", curve: [0.15, 0.2], min_max: [1.1, 0.9] }`.
`curve` adjusts the wobble and asymmetry of the pressure envelope, while `min_max` sets the mapped pressure range. This is the same family of pressure logic used by the built-in brushes.
- - `tip`: Only for `"custom"` type. A function where you draw the tip shape using p5.js commands inside a small graphics buffer `_m`.
+ - `tip`: Only for `"custom"` type. A function `(_m) => { ... }` that draws the tip shape into a small buffer. The coordinate space is 100×100 units with the origin at the centre — dark fills become opaque, light/white becomes transparent. In the **p5 build** `_m` is a `p5.Graphics` object, so any p5 drawing function works. In the **standalone build** `_m` is a minimal 2D-canvas-backed surface that supports the same method names (`rect`, `circle`, `ellipse`, `line`, `beginShape`/`vertex`/`endShape`, `fill`, `noFill`, `stroke`, `noStroke`, `strokeWeight`, `push`, `pop`, `translate`, `scale`, `rotate`) but colors must be a grayscale number `(0–255)` or a CSS color string — not a `p5.Color` — and `rotate()` always takes radians regardless of `brush.angleMode()`.
- `image`: Only for `"image"` type. An object with a `src` property pointing to your image file: `{ src: "./tip.jpg" }`.
- `rotate`: How the tip rotates as it moves. `"none"` keeps it fixed, `"natural"` follows the stroke direction, `"random"` spins randomly.
- `markerTip`: Only for `"marker"`, `"custom"`, and `"image"` types. Set to `false` to disable the extra soft tip buildup those brushes add at the start and end of each stroke. Defaults to `true`.
@@ -366,8 +366,8 @@ Functions for managing brush behaviors and properties.
spacing: 0.6,
pressure: [0.5, 1.5, 0.5], // thin → thick → thin
tip: (_m) => {
- // Draw inside _m using normal p5.js drawing commands
- _m.rotate(45);
+ // Use radians for rotate — works in both p5 and standalone builds
+ _m.rotate(Math.PI / 4);
_m.rect(-1.5, -1.5, 3, 3);
},
rotate: "natural",
diff --git a/docs/standalone.md b/docs/standalone.md
index abf41c5..a04506e 100644
--- a/docs/standalone.md
+++ b/docs/standalone.md
@@ -8,6 +8,7 @@ For the p5 build see the main [README](../README.md).
## Table of Contents
- [Installation](#installation)
+- [Custom tip brushes](#custom-tip-brushes)
- [Setup](#setup)
- [Frame lifecycle](#frame-lifecycle)
- [Transforms](#transforms)
@@ -280,6 +281,72 @@ 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` or CSS color string |
+| `noFill()` | |
+| `stroke(value)` | Grayscale number `0–255` 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) or any **CSS color string** (`'red'`, `'#3a2f1e'`, `'rgb(60, 47, 30)'`). `p5.Color` objects are not supported.
+
+```js
+// ✓ 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,
+});
+```
+
+```js
+// ✗ 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 |
diff --git a/llms.txt b/llms.txt
index 59543bb..ce1d598 100644
--- a/llms.txt
+++ b/llms.txt
@@ -180,7 +180,7 @@ If an LLM is helping a user design a brush, prefer pointing them to the interact
| `opacity` | Mark opacity 0–255 |
| `spacing` | Stamp gap along stroke (1 = no overlap) |
| `pressure` | `[start, end]` or `[start, mid, end]` or `(t) => value` |
-| `tip` | `"custom"` type: `(_m) => { _m.rect(...) }` |
+| `tip` | `"custom"` type: `(_m) => { _m.rect(...) }`. In the **p5 build** `_m` is a `p5.Graphics` — any p5 drawing command works. In the **standalone build** `_m` is a minimal 2D-canvas wrapper with the same method names (`rect`, `circle`, `ellipse`, `line`, `beginShape`/`vertex`/`endShape`, `fill`, `noFill`, `stroke`, `noStroke`, `strokeWeight`, `push`, `pop`, `translate`, `scale`, `rotate`) but colors must be a grayscale number or CSS string (not `p5.Color`), and `rotate()` always takes radians. |
| `image` | `"image"` type: `{ src: "./tip.jpg" }` |
| `rotate` | `"none"`, `"natural"`, `"random"` |
| `markerTip` | `"marker"`, `"custom"`, `"image"` only. Boolean. Defaults to `true`. Set `false` to disable the extra soft tip buildup at the start/end of strokes. |
@@ -199,7 +199,7 @@ 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(45); _m.rect(-1.5, -1.5, 3, 3) },
+ tip: (_m) => { _m.rotate(Math.PI / 4); _m.rect(-1.5, -1.5, 3, 3) },
rotate: "natural",
markerTip: false
})