Textures

View source
backend.Textures (Class)
Implements: spec.Textures

Clay backend implementation of texture management. Handles loading, creating, and managing GPU textures with reference counting.

Features:

  • Automatic texture caching and reference counting
  • Support for loading from files, URLs, or raw bytes
  • Render texture creation for off-screen rendering
  • Texture filtering and wrapping configuration
  • PNG export functionality
  • Multi-texture batching support

The class maintains a cache of loaded textures to avoid duplicate loads and uses reference counting to manage texture lifetime.

See: ceramic.Texture, clay.graphics.Texture

Instance Members

clay
load(path: String, ?options: Null<LoadTextureOptions>, _done: Function): Void

Loads a texture from a file path or URL. Implements automatic caching and reference counting to avoid duplicate loads.

Features:

  • Supports both local files and HTTP(S) URLs
  • Automatic texture caching with reference counting
  • Synchronous or asynchronous loading
  • Optional alpha premultiplication
  • Queues callbacks if texture is already loading
Name Type Default Description
path String File path (relative to assets) or URL to load
options Null<LoadTextureOptions> (optional) Loading options (sync/async, premultiply alpha, etc.)
_done Function Callback when texture is loaded or failed (null on failure)
clay
loadFromBytes(bytes: haxe.io.Bytes, type: ceramic.ImageType, ?options: Null<LoadTextureOptions>, _done: Function): Void

Creates a texture from raw image bytes. Useful for dynamically generated images or data loaded from custom sources.

Name Type Default Description
bytes haxe.io.Bytes Raw image data
type ceramic.ImageType Image format (PNG, JPEG, GIF)
options Null<LoadTextureOptions> (optional) Loading options (sync/async, premultiply alpha)
_done Function Callback when texture is created or failed (null on failure)
clay
supportsHotReloadPath(): Bool

Indicates whether hot-reloading of texture files is supported. Clay backend supports watching texture files for changes.

Returns Description
Bool Always returns true for Clay backend
clay
createTexture(width: Int, height: Int, pixels: ceramic.UInt8Array): Texture

Creates a texture from raw pixel data. The pixels should be in RGBA format with 8 bits per channel.

Name Type Description
width Int Texture width in pixels
height Int Texture height in pixels
pixels ceramic.UInt8Array Raw RGBA pixel data (width * height * 4 bytes)
Returns Description
Texture Created texture with reference count of 1
clay
createRenderTarget(width: Int, height: Int, depth: Bool, stencil: Bool, antialiasing: Int): Texture

Creates a render texture for off-screen rendering. Render textures can be used as drawing targets for post-processing effects.

Name Type Description
width Int Texture width in pixels
height Int Texture height in pixels
depth Bool Whether to create a depth buffer
stencil Bool Whether to create a stencil buffer
antialiasing Int Antialiasing samples (0 = disabled, WebGL2+ required on web)
Returns Description
Texture Created render texture with reference count of 1
clay
fetchTexturePixels(texture: Texture, ?result: Null<ceramic.UInt8Array>): ceramic.UInt8Array

Reads pixel data from a texture. Retrieves the current pixel contents from GPU memory.

Name Type Default Description
texture Texture The texture to read from
result Null<ceramic.UInt8Array> (optional) Optional array to store results (created if null)
Returns Description
ceramic.UInt8Array Array containing RGBA pixel data
clay
submitTexturePixels(texture: Texture, pixels: ceramic.UInt8Array): Void

Updates texture pixels on the GPU. Uploads new pixel data to an existing texture.

Name Type Description
texture Texture The texture to update
pixels ceramic.UInt8Array New RGBA pixel data (must match texture dimensions)
clay
destroyTexture(texture: Texture): Void

Destroys a texture and releases GPU resources. Decrements reference count and only destroys when count reaches zero.

Name Type Description
texture Texture The texture to destroy
clay
getTextureId(texture: Texture): TextureId

Gets the GPU texture ID.

Name Type Description
texture Texture The texture
Returns Description
TextureId OpenGL texture ID
clay
getTextureWidth(texture: Texture): Int

Gets the texture width in pixels.

Name Type Description
texture Texture The texture
Returns Description
Int Width in pixels
clay
getTextureHeight(texture: Texture): Int

Gets the texture height in pixels.

Name Type Description
texture Texture The texture
Returns Description
Int Height in pixels
clay
getTextureWidthActual(texture: Texture): Int

Gets the actual texture width on GPU (may be power of 2).

Name Type Description
texture Texture The texture
Returns Description
Int Actual width in GPU memory
clay
getTextureHeightActual(texture: Texture): Int

Gets the actual texture height on GPU (may be power of 2).

Name Type Description
texture Texture The texture
Returns Description
Int Actual height in GPU memory
clay
getTextureIndex(texture: Texture): Int

Gets the texture index for multi-texture batching.

Name Type Description
texture Texture The texture
Returns Description
Int Texture slot index
clay
setTextureFilter(texture: Texture, filter: Anonymous): Void

Sets the texture filtering mode. LINEAR provides smooth interpolation, NEAREST provides pixelated look.

Name Type Description
texture Texture The texture to configure
filter Anonymous Filter mode (LINEAR or NEAREST)
clay
setTextureWrapS(texture: Texture, wrap: ceramic.TextureWrap): Void

Sets the horizontal texture wrapping mode. Controls how the texture repeats or clamps at U coordinates outside 0-1.

Name Type Description
texture Texture The texture to configure
wrap ceramic.TextureWrap Wrap mode (CLAMP, REPEAT, or MIRROR)
clay
setTextureWrapT(texture: Texture, wrap: ceramic.TextureWrap): Void

Sets the vertical texture wrapping mode. Controls how the texture repeats or clamps at V coordinates outside 0-1.

Name Type Description
texture Texture The texture to configure
wrap ceramic.TextureWrap Wrap mode (CLAMP, REPEAT, or MIRROR)
clay
maxTextureWidth(): Int

Returns the maximum texture width supported by the GPU.

Returns Description
Int Maximum width in pixels (2048 on web, GPU-specific on native)
clay
maxTextureHeight(): Int

Returns the maximum texture height supported by the GPU.

Returns Description
Int Maximum height in pixels (2048 on web, GPU-specific on native)
clay
maxTexturesByBatch(): Int

Returns the maximum number of textures that can be used in a single batch. Values above 1 indicate multi-texture batching support for improved performance.

Returns Description
Int Maximum texture units (capped at 32)
clay
textureToPng(texture: Texture, ?reversePremultiplyAlpha: Bool = true, ?path: String, done: Function): Void

Exports a texture to PNG format. Native implementation using STB image write.

Name Type Default Description
texture Texture The texture to export
reversePremultiplyAlpha Bool true Whether to reverse premultiplied alpha
path String (optional) Optional file path to save to (returns bytes if null)
done Function Callback with PNG data bytes (null if path provided)
clay
pixelsToPng(width: Int, height: Int, pixels: ceramic.UInt8Array, ?path: String, done: Function): Void

Exports raw pixel data to PNG format. Native implementation using STB image write.

Name Type Default Description
width Int Image width in pixels
height Int Image height in pixels
pixels ceramic.UInt8Array Raw RGBA pixel data
path String (optional) Optional file path to save to (returns bytes if null)
done Function Callback with PNG data bytes (null if path provided)
clay
new(): Void

Private Members

clay
nextRenderIndex: Int

Counter for unique render texture IDs

clay
nextPixelsIndex: Int

Counter for unique pixel texture IDs

clay
nextBytesIndex: Int

Counter for unique byte-loaded texture IDs

clay
loadingTextureCallbacks: Map

Map of loading textures to their callbacks

clay
loadedTextures: Map

Cache of loaded textures by path/ID

clay
loadedTexturesRetainCount: Map

Reference count for each loaded texture

clay
computeMaxTextureSizeIfNeeded(): Void

Queries GPU for maximum texture size if not already cached. @private

clay
computeMaxTexturesByBatchIfNeeded(): Void

Queries GPU for maximum texture units if not already cached. @private