Texture resources
defineTexture from @pibbl/core creates a recipe factory. Recipes contain data;
useTexture(recipe, options) creates one persistent, mount-owned source that can
be passed directly to style.fill or style.stroke. Its send(message) method
queues typed, structured-cloneable data for the next Pibbl update. It may not run
during rendering. A static texture without a receiver accepts no messages.
TextureDefinition<Config, State, Message> supplies synchronous create,
rasterize, and optional update, receive, advance, and dispose callbacks.
TextureContext supplies the resource-owned canvas, optional palette,
invalidate() for changed output, and requestFrame() for continuing work.
TextureFrame supplies delta and time in milliseconds. No additional loop is
needed. Configurations and messages must be structured-cloneable data.
TextureOptions controls resolution and optional palette. Resolution defaults
to 256 by 160; dimensions are integers from 8 through 1024 with at most 262144
cells. Resizing resets implementation state. Palette changes preserve state.
Texture<Message> is a TexturePaint with send and paint(placement).
TexturePlacement chooses repeat or stretch, logical tileWidth/tileHeight,
offsetX/offsetY, and rotation in degrees. Paint views share their owner’s
pixels and lifetime. Sharing is supported within the owner’s Pibbl tree. Disposal
releases the canvas and queued work; later sends are inert, and rendering a
disposed resource is an error. Owners must outlive consumers.
TextureRecipe<Message> is the opaque result of the recipe factory. Recreating
recipes with the same definition preserves the mounted resource. Changing the
definition requires a new keyed owner. Custom implementations receive changed
configuration through update and decide whether output needs regeneration.
defineTexture
Section titled “defineTexture”Creates the immutable recipe factory for a custom implementation.
Texture
Section titled “Texture”The typed resource handle accepted by fills and strokes.
TextureContext
Section titled “TextureContext”The owned raster and invalidation capabilities.
TextureDefinition
Section titled “TextureDefinition”The custom implementation lifecycle described above.
TextureFrame
Section titled “TextureFrame”Pibbl-supplied time and delta in milliseconds.
TextureOptions
Section titled “TextureOptions”Resource resolution and presentation palette.
TexturePaint
Section titled “TexturePaint”An opaque resource-backed paint, optionally with per-use placement.
TexturePlacement
Section titled “TexturePlacement”Per-consumer repeat/stretch, tile size, offset, and rotation.
TextureRecipe
Section titled “TextureRecipe”A pure definition/configuration value consumed by the hook.
useTexture
Section titled “useTexture”Owns one recipe instance at the current mounted hook slot.
API details from source
Section titled “API details from source”
useTexture
Section titled “useTexture”Owns one persistent texture resource for the current mounted hook slot.
useTexture: <Message>(input: TextureRecipe<Message>, options?: TextureOptions) => Texture<Message>Related API: useTexture, TextureRecipe, TextureOptions, Texture.
Parameters
Section titled “Parameters”-
input— Texture recipe to mount or update. See TextureRecipe. -
options— Resolution and lifecycle options for the mounted texture. See TextureOptions .
Returns
Section titled “Returns”A mount-owned texture handle for sending messages and creating paint placements. See Texture .
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:565
defineTexture
Section titled “defineTexture”Defines a pure recipe factory; resource allocation starts at useTexture.
defineTexture: <Config, State, Message = never>(definition: TextureDefinition<Config, State, Message>) => (config: Config) => TextureRecipe<Message>Related API: defineTexture, TextureDefinition, TextureRecipe.
Parameters
Section titled “Parameters”definition— State creation, update, simulation, rasterization, and disposal callbacks. See TextureDefinition .
Returns
Section titled “Returns”A configuration-to-recipe factory; resources are allocated when a recipe is mounted. See TextureRecipe .
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:179
Texture
Section titled “Texture”A mount-owned texture handle that provides paint and accepts recipe messages.
interface Texture<Message = never> extends TexturePaintRelated API: Texture, TexturePaint.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:27
Properties and methods
Section titled “Properties and methods”
send
send: (message: Message) => voidDelivers a typed message to the mounted recipe instance. See Texture.
Parameters
Section titled “Parameters”message— Message delivered to the texture definition’s receive callback.
paint
paint: (placement: TexturePlacement) => TexturePaintRelated API: TexturePlacement, TexturePaint.
Returns a paint view with the requested placement while retaining the same texture ownership. See TexturePaint.
Parameters
Section titled “Parameters”placement— Destination bounds and texture placement policy. See TexturePlacement .
Returns
Section titled “Returns”A paint descriptor referencing this mounted texture. See TexturePaint.
TexturePaint
Section titled “TexturePaint”Opaque paint value produced by a mounted texture owner.
interface TexturePaintRelated API: TexturePaint.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture-protocol.ts:35
TextureRecipe
Section titled “TextureRecipe”A reusable texture definition together with the options used to instantiate it.
interface TextureRecipe<Message = never>Related API: TextureRecipe.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:158
TextureDefinition
Section titled “TextureDefinition”Lifecycle callbacks for creating, updating, painting, and disposing texture resources.
interface TextureDefinition<Config, State, Message = never>Related API: TextureDefinition.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:98
Properties and methods
Section titled “Properties and methods”
defaultPlacement (optional)
readonly defaultPlacement?: TexturePlacement | undefinedRelated API: TexturePlacement.
Texture placement used when no paint-specific override is supplied. See TexturePlacement.
create
create: (context: TextureContext, config: Readonly<Config>) => StateRelated API: TextureContext.
Allocates state for a mounted texture recipe. See TextureDefinition.
Parameters
Section titled “Parameters”-
context— Texture-owned drawing surface and scheduling services. See TextureContext . -
config— Initial recipe configuration.
Returns
Section titled “Returns”State retained for this mounted texture lifetime.
update (optional)
update?: ((state: State, config: Readonly<Config>, context: TextureContext) => void) | undefinedRelated API: TextureContext.
Updates existing state when the recipe configuration changes. See TextureDefinition.
Parameters
Section titled “Parameters”-
state— State returned by create. -
config— Latest recipe configuration. -
context— Texture-owned drawing surface and scheduling services. See TextureContext .
receive (optional)
receive?: ((state: State, message: Message, context: TextureContext) => void) | undefinedRelated API: TextureContext.
Handles a typed application message for this recipe instance. See TextureDefinition.
Parameters
Section titled “Parameters”-
state— State returned by create. -
message— Message sent through the mounted texture handle. -
context— Texture-owned drawing surface and scheduling services. See TextureContext .
advance (optional)
advance?: ((state: State, frame: TextureFrame, context: TextureContext) => void) | undefinedRelated API: TextureFrame, TextureContext.
Advances simulation using the shared Pibbl frame timing. See TextureDefinition.
Parameters
Section titled “Parameters”-
state— State returned by create. -
frame— Shared animation time and delta. See TextureFrame. -
context— Texture-owned drawing surface and scheduling services. See TextureContext .
rasterize
rasterize: (state: State, context: TextureContext) => voidRelated API: TextureContext.
Draws current texture pixels into the owned offscreen surface. See TextureDefinition.
Parameters
Section titled “Parameters”-
state— State returned by create. -
context— Texture-owned drawing surface and scheduling services. See TextureContext .
dispose (optional)
dispose?: ((state: State, context: TextureContext) => void) | undefinedRelated API: TextureContext.
Releases state and resources when the mounted texture is disposed. See TextureDefinition.
Parameters
Section titled “Parameters”-
state— State returned by create. -
context— Texture-owned drawing surface and scheduling services. See TextureContext .
TextureOptions
Section titled “TextureOptions”Resolution and runtime configuration for a mounted texture recipe.
interface TextureOptionsRelated API: TextureOptions.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:47
Properties and methods
Section titled “Properties and methods”
resolution (optional)
readonly resolution?: { readonly width: number; readonly height: number; } | undefinedDimensions of the simulation or raster grid. See TextureOptions.
palette (optional)
readonly palette?: readonly string[] | undefinedOrdered colors used to present texture intensity. See TextureOptions.
TexturePlacement
Section titled “TexturePlacement”How a texture raster is positioned and scaled when used as paint.
interface TexturePlacementRelated API: TexturePlacement.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture-protocol.ts:13
Properties and methods
Section titled “Properties and methods”
mode (optional)
readonly mode?: "repeat" | "stretch" | undefinedRelated API: repeat.
Selects the supported mapping, placement, or result policy. See TexturePlacement.
View source — packages/core/src/lib/textures/texture-protocol.ts:15
tileWidth (optional)
readonly tileWidth?: number | undefinedWidth of one texture tile in logical paint coordinates. See TexturePlacement.
View source — packages/core/src/lib/textures/texture-protocol.ts:17
tileHeight (optional)
readonly tileHeight?: number | undefinedHeight of one texture tile in logical paint coordinates. See TexturePlacement.
View source — packages/core/src/lib/textures/texture-protocol.ts:19
offsetX (optional)
readonly offsetX?: number | undefinedHorizontal offset applied to the texture or shadow. See TexturePlacement.
View source — packages/core/src/lib/textures/texture-protocol.ts:21
offsetY (optional)
readonly offsetY?: number | undefinedVertical offset applied to the texture or shadow. See TexturePlacement.
View source — packages/core/src/lib/textures/texture-protocol.ts:23
rotation (optional)
readonly rotation?: number | undefinedRotation applied to the containing geometry. See TexturePlacement.
View source — packages/core/src/lib/textures/texture-protocol.ts:25
TextureContext
Section titled “TextureContext”Surface and invalidation facilities supplied to texture lifecycle callbacks.
interface TextureContextRelated API: TextureContext.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:69
Properties and methods
Section titled “Properties and methods”
canvas
readonly canvas: OffscreenCanvasCanvas surface associated with this resource or mount. See TextureContext.
palette
readonly palette: readonly string[] | undefinedOrdered colors used to present texture intensity. See TextureContext.
invalidate
invalidate: () => voidMarks the source pixels dirty and requests a Pibbl update.
requestFrame
requestFrame: () => voidRequests another Pibbl frame; implementations stop by not requesting again.
TextureFrame
Section titled “TextureFrame”Shared logical time and elapsed milliseconds supplied while advancing a texture.
interface TextureFrameRelated API: TextureFrame.
See also
Section titled “See also”View source — packages/core/src/lib/textures/texture.ts:84
Properties and methods
Section titled “Properties and methods”
delta
readonly delta: numberElapsed time since the preceding texture frame, in milliseconds. See TextureFrame.
time
readonly time: numberCurrent shared logical time, in milliseconds. See TextureFrame.
Implementation guidance for agents
Section titled “Implementation guidance for agents”Read the Textures and reaction-diffusion companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.
Complete minimal examples
Section titled “Complete minimal examples”- Define and own a texture: Rasterize a small animated tile and send it a message from native HTML. Plain source
Interactive examples
Section titled “Interactive examples”- Plasma Globe · Full page
- Underwater scene · Full page
- Stirred Ink · Full page
- Rainy Window · Full page
Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 380919b. ALPHA — NOT FOR PRODUCTION USE.