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.mdindex 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 → thintip: (_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.mdindex 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.txtindex 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})