Texture2D

A GPU texture for the 2D engine — the image behind a Sprite or Tilemap. The raw file bytes are decoded and uploaded natively. Not interchangeable with the 3D Texture (material images).

At a glance

Texture2D.load(asset('./hero.png')).then(tex => {
  const hero = new Sprite({ texture: tex })
  console.log(tex.width, tex.height)      // pixel dimensions
})

Loading

Texture2D.load(source: string | FetchResponse | File): Promise<Texture2D>

• URL string — an asset('./file.png') path or a remote https://… URL; fetched, then decoded. Rejects on HTTP status ≥ 400 or a decode failure.
• FetchResponse — an already-fetched response (skip the extra request).
• File — e.g. from Canvas.toFile() or openFilePicker.

Texture2D.fromCanvas(canvas: Canvas): Texture2D
canvas.texture(): Texture2D                      // the canvas's own cached one

Wraps a Canvas's baked surface as a texture — synchronous (already rasterized, no decode). Its width/height are the canvas's physical pixels (logical size × pixelRatio). fromCanvas makes a new texture on every call; canvas.texture() creates one once and returns it after, and that one is what canvas.update() refreshes. Assigning a Canvas directly to sprite.texture uses canvas.texture() for you.

Properties & lifecycle

tex.width, tex.height    // pixels (readonly)
tex.id                   // native texture handle (readonly)
tex.destroy(): void      // free the GPU texture

Textures are shared freely — many sprites can use one Texture2D. Nothing frees a texture by itself: it lives until destroy(), even once nothing references it. After destroy() the sprites and tilemaps still using it draw nothing.

See also

• Sprite — using a texture, frames/atlases
• Tilemap — atlas grids
• SpriteAnimation — sheet slicing into clips
• Scene2D — the global filter setting