# packages/core/src/features/textures/lib/definitions.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/textures/lib/definitions.ts#L163). [Back to reference](/reference/types/textures/)
1 import type { TextureRecipe } from '../../../lib/textures/texture.js';
2 import { rasterizeField, releaseField } from "./wasm/memory.js";
3 import { defineTexture, type TextureContext } from "@pibbl/core";
4 import {
5   marbleField,
6   paperField,
7   cellularField,
8   type MaterialGenerator,
9 } from "./material-field.js";
10 import { InkSimulation } from "./simulation.js";
11 import { paletteLut, texturePalettes, validateSeed } from "./palette.js";
12 export { useTexture } from "@pibbl/core";
13 /**
14  * Seed, feature scale, and detail controls shared by static material recipes.
15  *
16  * @see {@link marble}
17  * @see {@link paper}
18  * @see {@link cellular}
19  */
20 export interface MaterialOptions {
21   /**
22    * Seed used for deterministic sampling or simulation initialization. See {@link MaterialOptions}
23    * .
24    */
25   readonly seed?: number;
26   /** Feature frequency across the generated material. See {@link MaterialOptions}. */
27   readonly scale?: number;
28   /** Material-specific distortion, grain strength, or cellular jitter. See {@link MaterialOptions}. */
29   readonly detail?: number;
30 }
31 /**
32  * Seed and pattern preset for a reaction-diffusion recipe.
33  *
34  * @see {@link reactionDiffusion}
35  */
36 export interface ReactionDiffusionOptions {
37   /**
38    * Seed used for deterministic sampling or simulation initialization. See
39    * {@link ReactionDiffusionOptions}.
40    */
41   readonly seed?: number;
42   /**
43    * Named pattern configuration used to initialize the simulation. See
44    * {@link ReactionDiffusionOptions}.
45    */
46   readonly preset?: "spots" | "stripes";
47 }
48 /**
49  * Paint, stir, pause, or reset commands accepted by a reaction-diffusion texture.
50  *
51  * @see {@link reactionDiffusion}
52  */
53 export type InkMessage =
54   | {
55       /** The literal "paint" identifying this variant. See {@link InkMessage}. */
56       readonly type: "paint";
57       /** Normalized horizontal texture coordinate. See {@link InkMessage}. */
58       readonly u: number;
59       /** Normalized vertical texture coordinate. See {@link InkMessage}. */
60       readonly v: number;
61       /** Radius in the coordinate system of this geometry or effect. See {@link InkMessage}. */
62       readonly radius?: number;
63       /** Magnitude of the displacement or brush effect. See {@link InkMessage}. */
64       readonly strength?: number;
65     }
66   | {
67       /** The literal "stir" identifying this variant. See {@link InkMessage}. */
68       readonly type: "stir";
69       /** Normalized horizontal texture coordinate. See {@link InkMessage}. */
70       readonly u: number;
71       /** Normalized vertical texture coordinate. See {@link InkMessage}. */
72       readonly v: number;
73       /** Normalized displacement of the existing field, not a paint dose. */
74       readonly du: number;
75       /** Normalized vertical displacement of the texture field. See {@link InkMessage}. */
76       readonly dv: number;
77       /** Influence radius in texture cells. */
78       readonly radius?: number;
79     }
80   | {
81       /** The literal "pause" identifying this variant. See {@link InkMessage}. */
82       readonly type: "pause";
83       /** Whether simulation or playback advancement is suspended. See {@link InkMessage}. */
84       readonly paused: boolean;
85     }
86   | {
87       /** The literal "reset" identifying this variant. See {@link InkMessage}. */
88       readonly type: "reset";
89     };
90 function colorize(field: Float32Array, context: TextureContext, gain = 1) {
91   const ctx = context.canvas.getContext("2d")!;
92   const lut = paletteLut(context.palette ?? texturePalettes.porcelain);
93   const raster = rasterizeField(field, lut, gain);
94   if (!raster) throw new Error("Texture field has no WASM owner.");
95   ctx.putImageData(raster.image, 0, 0);
96 }
97 function materialConfig(config: MaterialOptions) {
98   const seed = validateSeed(config.seed),
99     scale = config.scale ?? 6,
100     detail = config.detail ?? 0.65;
101   if (
102     !Number.isFinite(scale) ||
103     scale < 1 ||
104     scale > 32 ||
105     !Number.isFinite(detail) ||
106     detail < 0 ||
107     detail > 1
108   )
109     throw new RangeError("Material scale must be 1..32 and detail 0..1.");
110   return { seed, scale, detail };
111 }
112 function material(generate: MaterialGenerator) {
113   const recipe = defineTexture<
114     MaterialOptions,
115     { config: ReturnType<typeof materialConfig>; field: Float32Array }
116   >({
117     create(context, input) {
118       const config = materialConfig(input);
119       return {
120         config,
121         field: generate(
122           context.canvas.width,
123           context.canvas.height,
124           config.seed,
125           config.scale,
126           config.detail,
127         ),
128       };
129     },
130     update(state, input, context) {
131       const config = materialConfig(input);
132       if (JSON.stringify(config) === JSON.stringify(state.config)) return;
133       state.field = generate(
134         context.canvas.width,
135         context.canvas.height,
136         config.seed,
137         config.scale,
138         config.detail,
139         state.field,
140       );
141       state.config = config;
142       context.invalidate();
143     },
144     rasterize(state, context) {
145       colorize(state.field, context);
146     },
147     dispose(state) {
148       releaseField(state.field);
149       state.field = new Float32Array(0);
150     },
151   });
152   return (options: MaterialOptions = {}) => recipe(options);
153 }
154 /**
155  * Creates a seeded marble texture recipe with configurable feature scale and distortion.
156  *
157  * @param options - Seed, feature scale, and detail settings. See {@link MaterialOptions}.
158  * @returns A procedural material recipe for useTexture. See {@link TextureRecipe}.
159  *
160  * @see {@link MaterialOptions}
161  * @see {@link TextureRecipe}
162  */
163 export const marble = /* @__PURE__ */ material(marbleField);
164 /**
165  * Creates a seeded paper texture recipe with configurable feature scale and grain.
166  *
167  * @param options - Seed, feature scale, and detail settings. See {@link MaterialOptions}.
168  * @returns A procedural material recipe for useTexture. See {@link TextureRecipe}.
169  *
170  * @see {@link MaterialOptions}
171  * @see {@link TextureRecipe}
172  */
173 export const paper = /* @__PURE__ */ material(paperField);
174 /**
175  * Creates a seeded cellular texture recipe with configurable feature scale and jitter.
176  *
177  * @param options - Seed, feature scale, and detail settings. See {@link MaterialOptions}.
178  * @returns A procedural material recipe for useTexture. See {@link TextureRecipe}.
179  *
180  * @see {@link MaterialOptions}
181  * @see {@link TextureRecipe}
182  */
183 export const cellular = /* @__PURE__ */ material(cellularField);
184 function inkConfig(input: ReactionDiffusionOptions) {
185   const seed = validateSeed(input.seed),
186     preset = input.preset ?? "spots";
187   if (preset !== "spots" && preset !== "stripes")
188     throw new TypeError("Unknown ink preset.");
189   return { seed, preset };
190 }
191 interface InkState {
192   simulation: InkSimulation;
193   config: ReturnType<typeof inkConfig>;
194   paused: boolean;
195   elapsed: number;
196   fresh: boolean;
197 }
198 function reset(state: InkState, context: TextureContext) {
199   const next = new InkSimulation(
200     context.canvas.width,
201     context.canvas.height,
202     state.config.seed,
203     state.config.preset,
204   );
205   state.simulation.dispose();
206   state.simulation = next;
207   state.elapsed = 0;
208   state.fresh = true;
209   context.invalidate();
210 }
211 const inkRecipe = /* @__PURE__ */ defineTexture<
212   ReactionDiffusionOptions,
213   InkState,
214   InkMessage
215 >({
216   defaultPlacement: { mode: "stretch" },
217   create(context, input) {
218     const config = inkConfig(input);
219     context.requestFrame();
220     return {
221       simulation: new InkSimulation(
222         context.canvas.width,
223         context.canvas.height,
224         config.seed,
225         config.preset,
226       ),
227       config,
228       paused: false,
229       elapsed: 0,
230       fresh: true,
231     };
232   },
233   update(state, input, context) {
234     const config = inkConfig(input);
235     if (
236       config.seed === state.config.seed &&
237       config.preset === state.config.preset
238     )
239       return;
240     state.config = config;
241     reset(state, context);
242   },
243   receive(state, message, context) {
244     if (message.type === "pause") {
245       state.paused = message.paused;
246       state.elapsed = 0;
247       state.fresh = true;
248       if (!state.paused) context.requestFrame();
249     } else if (message.type === "reset") reset(state, context);
250     else if (message.type === "stir") {
251       const radius = message.radius ?? 16;
252       if (
253         ![message.u, message.v, message.du, message.dv, radius].every(
254           Number.isFinite,
255         ) ||
256         radius <= 0 ||
257         radius > 128 ||
258         Math.abs(message.du) > 1 ||
259         Math.abs(message.dv) > 1
260       )
261         throw new RangeError("Invalid ink stir message.");
262       if (message.u < 0 || message.u > 1 || message.v < 0 || message.v > 1)
263         return;
264       state.simulation.stir(
265         message.u * context.canvas.width,
266         message.v * context.canvas.height,
267         message.du * context.canvas.width,
268         message.dv * context.canvas.height,
269         radius,
270       );
271       context.invalidate();
272     } else if (message.type === "paint") {
273       const radius = message.radius ?? 6,
274         strength = message.strength ?? 0.8;
275       if (
276         ![message.u, message.v, radius, strength].every(Number.isFinite) ||
277         radius <= 0 ||
278         radius > 128 ||
279         strength < 0 ||
280         strength > 1
281       )
282         throw new RangeError("Invalid ink paint message.");
283       if (message.u < 0 || message.v < 0 || message.u > 1 || message.v > 1)
284         return;
285       state.simulation.paint(
286         message.u * context.canvas.width,
287         message.v * context.canvas.height,
288         radius,
289         strength,
290       );
291       context.invalidate();
292     } else throw new TypeError("Unknown ink message.");
293   },
294   advance(state, frame, context) {
295     if (state.paused) return;
296     if (!state.fresh) {
297       state.elapsed += Math.min(50, frame.delta);
298       const steps = Math.min(24, Math.floor(state.elapsed * 0.48 + 1e-9));
299       state.elapsed -= steps / 0.48;
300       if (steps) {
301         state.simulation.advance(steps);
302         context.invalidate();
303       }
304     }
305     state.fresh = false;
306     context.requestFrame();
307   },
308   rasterize(state, context) {
309     colorize(state.simulation.b, context, 650 / 255);
310   },
311   dispose(state) {
312     state.simulation.dispose();
313   },
314 });
315 /**
316  * Creates a stateful reaction-diffusion texture recipe supporting paint, stirring, pause, and
317  * reset
318  * messages.
319  *
320  * @param options - Reaction and diffusion parameters, initialization, and rendering options. See
321  * {@link ReactionDiffusionOptions} .
322  * @returns A reaction-diffusion texture recipe for useTexture.
323  *
324  * @see {@link ReactionDiffusionOptions}
325  */
326 export function reactionDiffusion(options: ReactionDiffusionOptions = {}) {
327   return inkRecipe(options);
328 }
329
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.