SurfaceTexture

An image uploaded once and bound per draw.

class SurfaceTexture

import { SurfaceTexture } from '@driftengine/core';

In depth

The engine ships no image assets and fetches nothing — that payload rule is intact and this does not weaken it. What it takes is a TexImageSource the consumer already has: a canvas it generated procedurally at runtime, an ImageBitmap it decoded, a video frame. The engine owns the GPU object and the sampler state; where the pixels came from is the caller's business and stays that way.

Constructor

`new`

constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[])

One image, or an array of images that must share one size (layerSize refuses otherwise). Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are where compressed — the formats this context samples — has theirs; see compressedSource.ts.

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`
`source`	`SurfaceSource \| readonly SurfaceSource[] \| LightmapTexels \| SceneCaptureTexels`
`options?`	`SurfaceTextureOptions`
`compressed?`	`readonly CompressedTextureFormat[]`

Properties

Name	Type	Description
`layers`readonly	`number`	How many images the array holds: 1 for `createSurfaceTexture`, the list's length otherwise.

Accessors

Name	Type	Description
`hasEffects`get	`boolean`	Whether this texture carries an effects table, which the lit program reads only once one exists.

Methods

`bindEffects`

bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`
`unit`	`number`
`fallback`	`WebGLTexture`

`update`

update(gl: WebGL2RenderingContext, source: TexImageSource | CompressedTextureSource, compressed?: readonly CompressedTextureFormat[]): void

Replace the pixels, keeping the GPU object and its sampler state.

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`
`source`	`TexImageSource \| CompressedTextureSource`
`compressed?`	`readonly CompressedTextureFormat[]`

For a source that changes — a canvas being redrawn, a decoded frame. Re-uploading beats constructing a second texture because the binding the caller already handed to a draw stays valid, and because a texture created per frame is a leak in every case where the caller forgets the matching dispose.

Not a hot path: it re-uploads the whole image and regenerates the chain. A caller doing this every frame at any size wants to know that it costs what it costs.

`attachColor`

attachColor(gl: WebGL2RenderingContext): void

Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into by captureScene. Engine-internal, as bind is.

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`

`bind`

bind(gl: WebGL2RenderingContext, unit: number): void

Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment.

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`
`unit`	`number`

`flatLayer`

flatLayer(gl: WebGL2RenderingContext): WebGLTexture | null

Layer 0 as a plain 2D texture: what a sampler2D can be handed, which an array cannot. Copied the first time it is asked for, by a framebuffer blit into storage of the same format, and kept until update or dispose. Engine-internal: a surface overlay's atlas is bound where the lit stage's one 2D image slot is (surfaceOverlay.ts).

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`

Null for blocks, which no framebuffer can read; the caller says so. What it costs is a copy of level 0 in memory beside the array, and the bindings of both framebuffer targets, which are read back before the blit and put back after it — a sync query, paid once per image.

`dispose`

dispose(gl: WebGL2RenderingContext): void

Parameter	Type	Description
`gl`	`WebGL2RenderingContext`