# packages/core/src/lib/textures/texture.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/lib/textures/texture.ts#L565). [Back to reference](/reference/types/texture-resources/)
1 import { GLOBAL_STATE } from "../global-state.js";
2 import {
3   requireHookContext,
4   useHookSlot,
5   withHooksForbidden,
6 } from "../hooks/hook-slot.js";
7 import { registerAdvanceParticipant } from "../scheduler/realm-scheduler.js";
8 import { signal } from "../signals/graph.js";
9 import type { PibblInstance, RenderingContext2D } from "../types.js";
10 import {
11   registerTexturePaint,
12   type BorrowedTextureRaster,
13   type TexturePaint,
14   type TexturePlacement,
15 } from "./texture-protocol.js";
16 
17 export type { TexturePaint, TexturePlacement } from "./texture-protocol.js";
18 
19 declare const recipeBrand: unique symbol;
20 /**
21  * A mount-owned texture handle that provides paint and accepts recipe messages.
22  *
23  * @see {@link TexturePaint}
24  * @see {@link TexturePlacement}
25  * @see {@link useTexture}
26  */
27 export interface Texture<Message = never> extends TexturePaint {
28   /**
29    * Delivers a typed message to the mounted recipe instance. See {@link Texture}.
30    * @param message - Message delivered to the texture definition's receive callback.
31    */
32   send(message: Message): void;
33   /**
34    * Returns a paint view with the requested placement while retaining the same texture ownership.
35    * See {@link TexturePaint}.
36    * @param placement - Destination bounds and texture placement policy. See
37    * {@link TexturePlacement} .
38    * @returns A paint descriptor referencing this mounted texture. See {@link TexturePaint}.
39    */
40   paint(placement: TexturePlacement): TexturePaint;
41 }
42 /**
43  * Resolution and runtime configuration for a mounted texture recipe.
44  *
45  * @see {@link useTexture}
46  */
47 export interface TextureOptions {
48   /** Dimensions of the simulation or raster grid. See {@link TextureOptions}. */
49   readonly resolution?: {
50     /**
51      * Horizontal extent in the units of the containing geometry or surface. See
52      * {@link TextureOptions}.
53      */
54     readonly width: number;
55     /**
56      * Vertical extent in the units of the containing geometry or surface. See
57      * {@link TextureOptions}.
58      */
59     readonly height: number;
60   };
61   /** Ordered colors used to present texture intensity. See {@link TextureOptions}. */
62   readonly palette?: readonly string[];
63 }
64 /**
65  * Surface and invalidation facilities supplied to texture lifecycle callbacks.
66  *
67  * @see {@link TextureDefinition}
68  */
69 export interface TextureContext {
70   /** Canvas surface associated with this resource or mount. See {@link TextureContext}. */
71   readonly canvas: OffscreenCanvas;
72   /** Ordered colors used to present texture intensity. See {@link TextureContext}. */
73   readonly palette: readonly string[] | undefined;
74   /** Marks the source pixels dirty and requests a Pibbl update. */
75   invalidate(): void;
76   /** Requests another Pibbl frame; implementations stop by not requesting again. */
77   requestFrame(): void;
78 }
79 /**
80  * Shared logical time and elapsed milliseconds supplied while advancing a texture.
81  *
82  * @see {@link TextureDefinition}
83  */
84 export interface TextureFrame {
85   /** Elapsed time since the preceding texture frame, in milliseconds. See {@link TextureFrame}. */
86   readonly delta: number;
87   /** Current shared logical time, in milliseconds. See {@link TextureFrame}. */
88   readonly time: number;
89 }
90 /**
91  * Lifecycle callbacks for creating, updating, painting, and disposing texture resources.
92  *
93  * @see {@link TexturePlacement}
94  * @see {@link TextureContext}
95  * @see {@link TextureFrame}
96  * @see {@link defineTexture}
97  */
98 export interface TextureDefinition<Config, State, Message = never> {
99   /**
100    * Texture placement used when no paint-specific override is supplied. See
101    * {@link TexturePlacement}.
102    */
103   readonly defaultPlacement?: TexturePlacement;
104   /**
105    * Allocates state for a mounted texture recipe. See {@link TextureDefinition}.
106    * @param context - Texture-owned drawing surface and scheduling services. See
107    * {@link TextureContext} .
108    * @param config - Initial recipe configuration.
109    * @returns State retained for this mounted texture lifetime.
110    */
111   create(context: TextureContext, config: Readonly<Config>): State;
112   /**
113    * Updates existing state when the recipe configuration changes. See {@link TextureDefinition}.
114    * @param state - State returned by create.
115    * @param config - Latest recipe configuration.
116    * @param context - Texture-owned drawing surface and scheduling services. See
117    * {@link TextureContext} .
118    */
119   update?(state: State, config: Readonly<Config>, context: TextureContext): void;
120   /**
121    * Handles a typed application message for this recipe instance. See {@link TextureDefinition}.
122    * @param state - State returned by create.
123    * @param message - Message sent through the mounted texture handle.
124    * @param context - Texture-owned drawing surface and scheduling services. See
125    * {@link TextureContext} .
126    */
127   receive?(state: State, message: Message, context: TextureContext): void;
128   /**
129    * Advances simulation using the shared Pibbl frame timing. See {@link TextureDefinition}.
130    * @param state - State returned by create.
131    * @param frame - Shared animation time and delta. See {@link TextureFrame}.
132    * @param context - Texture-owned drawing surface and scheduling services. See
133    * {@link TextureContext} .
134    */
135   advance?(state: State, frame: TextureFrame, context: TextureContext): void;
136   /**
137    * Draws current texture pixels into the owned offscreen surface. See {@link TextureDefinition}.
138    * @param state - State returned by create.
139    * @param context - Texture-owned drawing surface and scheduling services. See
140    * {@link TextureContext} .
141    */
142   rasterize(state: State, context: TextureContext): void;
143   /**
144    * Releases state and resources when the mounted texture is disposed. See
145    * {@link TextureDefinition}.
146    * @param state - State returned by create.
147    * @param context - Texture-owned drawing surface and scheduling services. See
148    * {@link TextureContext} .
149    */
150   dispose?(state: State, context: TextureContext): void;
151 }
152 /**
153  * A reusable texture definition together with the options used to instantiate it.
154  *
155  * @see {@link defineTexture}
156  * @see {@link useTexture}
157  */
158 export interface TextureRecipe<Message = never> {
159   readonly [recipeBrand]: (message: Message) => Message;
160 }
161 type Definition = TextureDefinition<any, any, any>;
162 interface Recipe {
163   definition: Definition;
164   config: any;
165 }
166 const recipes = new WeakMap<object, Recipe>();
167 
168 /**
169  * Defines a pure recipe factory; resource allocation starts at useTexture.
170  *
171  * @param definition - State creation, update, simulation, rasterization, and disposal callbacks.
172  * See {@link TextureDefinition} .
173  * @returns A configuration-to-recipe factory; resources are allocated when a recipe is mounted.
174  * See {@link TextureRecipe} .
175  *
176  * @see {@link TextureDefinition}
177  * @see {@link TextureRecipe}
178  */
179 export function defineTexture<Config, State, Message = never>(
180   definition: TextureDefinition<Config, State, Message>,
181 ): (config: Config) => TextureRecipe<Message> {
182   const stable = Object.freeze({ ...definition });
183   return (config) => {
184     const recipe = Object.freeze({}) as TextureRecipe<Message>;
185     recipes.set(recipe, {
186       definition: stable,
187       config: structuredClone(config),
188     });
189     return recipe;
190   };
191 }
192 function placement(value: TexturePlacement = {}): Readonly<TexturePlacement> {
193   if (
194     value.mode !== undefined &&
195     value.mode !== "repeat" &&
196     value.mode !== "stretch"
197   )
198     throw new TypeError("Unknown texture placement mode.");
199   for (const key of [
200     "tileWidth",
201     "tileHeight",
202     "offsetX",
203     "offsetY",
204     "rotation",
205   ] as const) {
206     const n = value[key];
207     if (
208       n !== undefined &&
209       (!Number.isFinite(n) ||
210         ((key === "tileWidth" || key === "tileHeight") && n <= 0))
211     )
212       throw new RangeError(`Invalid texture placement ${key}.`);
213   }
214   return Object.freeze({ ...value });
215 }
216 function dimensions(options: TextureOptions): [number, number] {
217   const width = options.resolution?.width ?? 256,
218     height = options.resolution?.height ?? 160;
219   if (
220     ![width, height].every((n) => Number.isInteger(n) && n >= 8 && n <= 1024) ||
221     width * height > 262144
222   )
223     throw new RangeError(
224       "Texture resolution must be 8..1024 cells per axis, at most 262144 cells.",
225     );
226   return [width, height];
227 }
228 class Resource {
229   readonly revision = signal(0);
230   readonly canvas: OffscreenCanvas;
231   private committed: OffscreenCanvas | undefined;
232   private spare: OffscreenCanvas | undefined;
233   private provisional: { canvas: OffscreenCanvas; transaction: NonNullable<typeof GLOBAL_STATE.renderTransaction> } | undefined;
234   readonly context: TextureContext;
235   readonly handle: Texture<any>;
236   state: any;
237   definition: Definition;
238   disposed = false;
239   private hasState = false;
240   dirty = true;
241   private sequence = 0;
242   private publicationCanvasesCreated = 0;
243   private messages: unknown[] = [];
244   private unregister?: () => void;
245   private continuing = false;
246   private lastTime?: number;
247   private initializing = true;
248   private retryScheduled = false;
249   private palette?: readonly string[];
250   private optionsKey: string;
251   constructor(
252     private owner: PibblInstance | undefined,
253     recipe: Recipe,
254     options: TextureOptions,
255   ) {
256     const [width, height] = dimensions(options);
257     this.optionsKey = JSON.stringify(options);
258     this.palette = options.palette && Object.freeze([...options.palette]);
259     this.canvas = new OffscreenCanvas(width, height);
260     this.definition = recipe.definition;
261     const self = this;
262     this.context = Object.freeze({
263       canvas: this.canvas,
264       get palette() {
265         return self.palette;
266       },
267       invalidate() {
268         if (!self.disposed) {
269           self.dirty = true;
270           if (!self.initializing) self.schedule();
271         }
272       },
273       requestFrame() {
274         if (!self.disposed) {
275           self.continuing = true;
276           self.schedule();
277         }
278       },
279     });
280     const registerPaint = (value: TexturePaint, placement: Readonly<TexturePlacement>) =>
281       registerTexturePaint(value, {
282         resolvePaint: (ctx, bounds) => this.resolvePaint(ctx, bounds, placement),
283         validate: () => this.assertOwner(),
284         borrow: callback => callback(this.borrow(placement)),
285       });
286     this.handle = Object.freeze({
287       send: (message: unknown) => {
288         if (this.disposed) return;
289         if (GLOBAL_STATE.currentPibblInstance)
290           throw new Error("Texture.send cannot run during Pibbl evaluation.");
291         if (!this.definition.receive)
292           throw new Error("This texture does not accept messages.");
293         if (this.messages.length >= 8192)
294           throw new RangeError("Texture message queue is full.");
295         this.messages.push(structuredClone(message));
296         this.schedule();
297       },
298       paint: (value: TexturePlacement) => {
299         const paint = Object.freeze({}) as TexturePaint;
300         registerPaint(paint, placement(value));
301         return paint;
302       },
303     }) as Texture<any>;
304     registerPaint(this.handle, placement(this.definition.defaultPlacement));
305     try {
306       this.state = this.call(() =>
307         this.definition.create(this.context, recipe.config),
308       );
309       this.hasState = true;
310       this.publishInitial();
311       this.initializing = false;
312     } catch (error) {
313       try {
314         this.dispose();
315       } catch {
316         // The initialization failure remains the actionable error.
317       }
318       throw error;
319     }
320   }
321   private call<T>(fn: () => T): T {
322     return withHooksForbidden(
323       "Texture implementations cannot call Pibbl hooks.",
324       fn,
325     );
326   }
327   update(recipe: Recipe, options: TextureOptions) {
328     if (this.disposed) return;
329     if (recipe.definition !== this.definition)
330       throw new Error(
331         "Changing a texture definition requires a new keyed owner.",
332       );
333     const [width, height] = dimensions(options);
334     const nextKey = JSON.stringify(options);
335     if (nextKey !== this.optionsKey) {
336       this.palette = options.palette && Object.freeze([...options.palette]);
337       this.optionsKey = nextKey;
338       if (width !== this.canvas.width || height !== this.canvas.height) {
339         try {
340           this.disposeState();
341           this.canvas.width = width;
342           this.canvas.height = height;
343           this.messages.length = 0;
344           this.lastTime = undefined;
345           this.state = this.call(() =>
346             this.definition.create(this.context, recipe.config),
347           );
348           this.hasState = true;
349         } catch (error) {
350           try { this.dispose(); } catch { /* Preserve the recreate failure. */ }
351           throw error;
352         }
353       }
354       this.context.invalidate();
355     }
356     this.call(() =>
357       this.definition.update?.(this.state, recipe.config, this.context),
358     );
359   }
360   private unschedule() {
361     this.unregister?.();
362     this.unregister = undefined;
363   }
364   private schedule() {
365     if (this.unregister || this.disposed) return;
366     const participant = (frame: { logicalTime: number }, batch: any) => {
367       const retryAtEntry = this.retryScheduled;
368       this.unschedule();
369       const wasContinuing = this.continuing;
370       this.continuing = false;
371       try {
372         const messages = this.messages;
373         this.messages = [];
374         for (const message of messages)
375           this.call(() =>
376             this.definition.receive?.(this.state, message, this.context),
377           );
378         if (wasContinuing)
379           this.call(() =>
380             this.definition.advance?.(
381               this.state,
382               {
383                 delta:
384                   this.lastTime === undefined
385                     ? 0
386                     : Math.max(0, frame.logicalTime - this.lastTime),
387                 time: frame.logicalTime,
388               },
389               this.context,
390             ),
391           );
392         this.lastTime = this.continuing ? frame.logicalTime : undefined;
393         if (this.dirty) {
394           const candidate = this.rasterizeCandidate();
395           let previous: OffscreenCanvas | undefined;
396           batch.stage(this.revision, ++this.sequence, participant);
397           batch.registerLifecycle(participant, {
398             apply: () => {
399               if (this.disposed) {
400                 candidate.width = candidate.height = 0;
401               } else {
402                 previous = this.committed;
403                 this.committed = candidate;
404                 this.spare = previous;
405                 this.retryScheduled = false;
406               }
407             },
408             rollback: () => {
409               if (!this.disposed) {
410                 this.committed = previous;
411                 this.spare = candidate;
412               }
413             },
414             abort: () => {
415               this.spare = candidate;
416               if (!this.disposed) {
417                 this.dirty = true;
418                 this.schedule();
419               }
420             },
421           });
422         }
423         if (!this.continuing && this.messages.length === 0) {
424           this.unschedule();
425         }
426       } catch (error) {
427         this.unschedule();
428         this.continuing = false;
429         if (this.retryScheduled && !retryAtEntry) this.schedule();
430         throw error;
431       }
432     };
433     this.unregister = registerAdvanceParticipant(participant);
434   }
435   private rasterizeCandidate(): OffscreenCanvas {
436     const ctx = this.canvas.getContext("2d");
437     if (!ctx) throw new Error("Textures require OffscreenCanvas 2D.");
438     ctx.save();
439     try {
440       ctx.resetTransform();
441       ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
442       this.call(() => this.definition.rasterize(this.state, this.context));
443       this.dirty = false;
444     } finally {
445       ctx.restore();
446     }
447     const spare = this.spare;
448     this.spare = undefined;
449     const reusable = spare?.width === this.canvas.width && spare.height === this.canvas.height ?
450       spare : undefined;
451     if (spare && spare !== reusable) spare.width = spare.height = 0;
452     let candidate: OffscreenCanvas | undefined;
453     try {
454       candidate = reusable ?? this.createPublicationCanvas();
455       const candidateContext = candidate.getContext("2d");
456       if (!candidateContext) throw new Error("Textures require OffscreenCanvas 2D.");
457       // Publication canvases are reused; transparent source pixels must erase old paint.
458       candidateContext.clearRect(0, 0, candidate.width, candidate.height);
459       candidateContext.drawImage(this.canvas, 0, 0);
460       return candidate;
461     } catch (error) {
462       if (candidate) candidate.width = candidate.height = 0;
463       this.dirty = true;
464       if (!this.retryScheduled) {
465         this.retryScheduled = true;
466         this.schedule();
467       }
468       throw error;
469     }
470   }
471   private createPublicationCanvas(): OffscreenCanvas {
472     this.publicationCanvasesCreated++;
473     return new OffscreenCanvas(this.canvas.width, this.canvas.height);
474   }
475   /** @internal Structural ownership evidence for texture publication tests. */
476   publicationSnapshot(): Readonly<{ publicationCanvasesCreated: number; hasOwner: boolean }> {
477     return Object.freeze({ publicationCanvasesCreated: this.publicationCanvasesCreated, hasOwner: this.owner !== undefined });
478   }
479   private publishInitial(): void {
480     const candidate = this.rasterizeCandidate();
481     const transaction = GLOBAL_STATE.renderTransaction;
482     if (!transaction) {
483       this.committed = candidate;
484       return;
485     }
486     this.provisional = { canvas: candidate, transaction };
487     transaction.onFinish(success => {
488       if (this.provisional?.transaction !== transaction) return;
489       const provisional = this.provisional;
490       this.provisional = undefined;
491       if (success && !this.disposed) this.committed = provisional.canvas;
492       else provisional.canvas.width = provisional.canvas.height = 0;
493     });
494   }
495   private assertOwner(): void {
496     if (this.disposed) throw new Error("Cannot paint with a disposed texture.");
497     let root = GLOBAL_STATE.currentPibblInstance;
498     while (root?.parent) root = GLOBAL_STATE.pibblInstances.get(root.parent);
499     let owner = this.owner;
500     while (owner?.parent) owner = GLOBAL_STATE.pibblInstances.get(owner.parent);
501     if (root !== owner) throw new Error("Textures may only be shared within their owning Pibbl tree.");
502   }
503   private borrow(placement: Readonly<TexturePlacement>): BorrowedTextureRaster {
504     this.assertOwner();
505     const revision = this.revision.get();
506     const provisional = this.provisional;
507     const source =
508       provisional !== undefined && provisional.transaction === GLOBAL_STATE.renderTransaction ?
509         provisional.canvas : this.committed;
510     if (!source) throw new Error("Texture pixels are not committed for this render transaction.");
511     return Object.freeze({ source, width: source.width, height: source.height, revision, resource: this, placement });
512   }
513   private resolvePaint(ctx: RenderingContext2D, bounds: { x: number; y: number; width: number; height: number }, p: Readonly<TexturePlacement>): string | CanvasGradient | CanvasPattern {
514     const borrowed = this.borrow(p);
515     const pattern = ctx.createPattern(borrowed.source, "repeat");
516     if (!pattern) throw new Error("Could not create texture paint.");
517     const stretch = p.mode === "stretch";
518     const width = stretch ? bounds.width : (p.tileWidth ?? borrowed.width);
519     const height = stretch ? bounds.height : (p.tileHeight ?? borrowed.height);
520     pattern.setTransform(new DOMMatrix().translate(bounds.x + (p.offsetX ?? 0), bounds.y + (p.offsetY ?? 0)).rotate(p.rotation ?? 0).scale(Math.max(0.000001, width) / borrowed.width, Math.max(0.000001, height) / borrowed.height));
521     return pattern;
522   }
523   dispose() {
524     if (this.disposed) return;
525     this.disposed = true;
526     this.unschedule();
527     this.messages.length = 0;
528     try {
529       this.disposeState();
530     } finally {
531       this.canvas.width = this.canvas.height = 0;
532       this.committed && (this.committed.width = this.committed.height = 0);
533       this.spare && (this.spare.width = this.spare.height = 0);
534       this.provisional && (this.provisional.canvas.width = this.provisional.canvas.height = 0);
535       this.state = undefined;
536       this.hasState = false;
537       this.committed = undefined;
538       this.spare = undefined;
539       this.provisional = undefined;
540       this.owner = undefined;
541     }
542   }
543   private disposeState() {
544     if (!this.hasState) return;
545     this.hasState = false;
546     const state = this.state;
547     this.state = undefined;
548     this.call(() => this.definition.dispose?.(state, this.context));
549   }
550 }
551 
552 /**
553  * Owns one persistent texture resource for the current mounted hook slot.
554  *
555  * @param input - Texture recipe to mount or update. See {@link TextureRecipe}.
556  * @param options - Resolution and lifecycle options for the mounted texture. See
557  * {@link TextureOptions} .
558  * @returns A mount-owned texture handle for sending messages and creating paint placements. See
559  * {@link Texture} .
560  *
561  * @see {@link TextureRecipe}
562  * @see {@link TextureOptions}
563  * @see {@link Texture}
564  */
565 export function useTexture<Message>(
566   input: TextureRecipe<Message>,
567   options: TextureOptions = {},
568 ): Texture<Message> {
569   const recipe = recipes.get(input);
570   if (!recipe)
571     throw new TypeError("useTexture requires a defineTexture recipe.");
572   const { pibblInstance } = requireHookContext();
573   let created = false;
574   const resource = useHookSlot("texture", (teardowns) => {
575     created = true;
576     const value = new Resource(pibblInstance, recipe, options);
577     teardowns.add(() => value.dispose());
578     return value;
579   }).value;
580   if (!created)
581     GLOBAL_STATE.renderTransaction!.onFinish((success) => {
582       if (success) resource.update(recipe, options);
583     });
584   return resource.handle;
585 }
586
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.