Textures
Backend interface for texture (image) management and GPU operations.
This interface handles loading images, creating textures, managing GPU texture memory, and configuring texture properties. Textures are the primary way to display images and render targets in Ceramic.
Textures can be created from:
- Image files (PNG, JPEG, etc.)
- Raw pixel data
- Render targets for off-screen rendering
The interface supports various texture operations including filtering modes, wrapping modes, pixel access, and PNG export.
Instance Members
load(path: String, ?options: Null<backend.LoadTextureOptions>, done: Function): VoidLoads a texture from an image file.
Supported formats depend on the backend but typically include PNG, JPEG, and sometimes GIF or WebP. The image is uploaded to GPU memory as a texture.
| Name | Type | Default | Description |
|---|---|---|---|
path |
String | The path to the image file (relative to assets) | |
options |
Null<backend.LoadTextureOptions> | (optional) | Optional loading configuration (filtering, density, etc.) |
done |
Function | Callback invoked with the loaded texture or null on failure |
loadFromBytes(bytes: haxe.io.Bytes, type: ceramic.ImageType, ?options: Null<backend.LoadTextureOptions>, done: Function): VoidCreates a texture from image data in memory.
This allows creating textures from downloaded or generated image data without writing to disk first.
| Name | Type | Default | Description |
|---|---|---|---|
bytes |
haxe.io.Bytes | The raw image file data | |
type |
ceramic.ImageType | The image format (PNG, JPEG, etc.) | |
options |
Null<backend.LoadTextureOptions> | (optional) | Optional loading configuration |
done |
Function | Callback invoked with the created texture or null on failure |
supportsHotReloadPath(): BoolChecks if the backend supports hot-reloading of texture files.
When true, textures can include a ?hot=timestamp query parameter to
bypass caching and force reloading when the image changes during development.
| Returns | Description |
|---|---|
| Bool | True if hot-reload paths are supported, false otherwise |
createTexture(width: Int, height: Int, pixels: ceramic.UInt8Array): backend.TextureCreates a texture from raw pixel data.
Pixels should be provided as RGBA bytes (4 bytes per pixel) in row-major order. The texture is immediately uploaded to GPU memory.
| Name | Type | Description |
|---|---|---|
width |
Int | The texture width in pixels |
height |
Int | The texture height in pixels |
pixels |
ceramic.UInt8Array | The raw RGBA pixel data (width * height * 4 bytes) |
| Returns | Description |
|---|---|
| backend.Texture | The created texture |
destroyTexture(texture: backend.Texture): VoidDestroys a texture and frees its GPU memory.
After calling this, the texture should not be used for rendering. This is automatically called when a Texture object is destroyed.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to destroy |
getTextureId(texture: backend.Texture): backend.TextureIdGets the unique identifier for a texture.
This ID is used internally for texture state tracking and batching.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to query |
| Returns | Description |
|---|---|
| backend.TextureId | The texture's unique identifier |
getTextureWidth(texture: backend.Texture): IntGets the logical width of a texture.
This is the usable width, which may be smaller than the actual GPU texture if the backend uses power-of-two padding.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to query |
| Returns | Description |
|---|---|
| Int | The logical width in pixels |
getTextureHeight(texture: backend.Texture): IntGets the logical height of a texture.
This is the usable height, which may be smaller than the actual GPU texture if the backend uses power-of-two padding.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to query |
| Returns | Description |
|---|---|
| Int | The logical height in pixels |
getTextureWidthActual(texture: backend.Texture): IntGets the actual GPU texture width.
This may be larger than the logical width if the backend pads textures to power-of-two dimensions for older GPU compatibility.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to query |
| Returns | Description |
|---|---|
| Int | The actual GPU texture width in pixels |
getTextureHeightActual(texture: backend.Texture): IntGets the actual GPU texture height.
This may be larger than the logical height if the backend pads textures to power-of-two dimensions for older GPU compatibility.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to query |
| Returns | Description |
|---|---|
| Int | The actual GPU texture height in pixels |
fetchTexturePixels(texture: backend.Texture, ?result: Null<ceramic.UInt8Array>): ceramic.UInt8ArrayFetches pixel data from a texture.
This downloads the texture from GPU memory to CPU memory. The operation may be slow and should be used sparingly. Pixels are returned as RGBA bytes.
| Name | Type | Default | Description |
|---|---|---|---|
texture |
backend.Texture | The texture to read from | |
result |
Null<ceramic.UInt8Array> | (optional) | Optional array to store results (must be widthheight4 bytes) |
| Returns | Description |
|---|---|
| ceramic.UInt8Array | Array containing RGBA pixel data |
submitTexturePixels(texture: backend.Texture, pixels: ceramic.UInt8Array): VoidUpdates a texture with new pixel data.
This uploads new pixel data to an existing texture on the GPU. The pixel array must match the texture's dimensions (widthheight4 bytes).
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to update |
pixels |
ceramic.UInt8Array | The new RGBA pixel data |
setTextureFilter(texture: backend.Texture, filter: Anonymous): VoidSets the filtering mode for a texture.
Filtering determines how pixels are sampled when the texture is scaled:
- LINEAR: Smooth interpolation (good for photos)
- NEAREST: No interpolation (good for pixel art)
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to configure |
filter |
Anonymous | The filtering mode to apply |
setTextureWrapS(texture: backend.Texture, wrap: ceramic.TextureWrap): VoidSets the horizontal (S/U axis) wrapping mode for a texture.
Wrapping determines what happens when texture coordinates exceed 0-1:
- CLAMP: Clamps to edge pixels
- REPEAT: Tiles the texture
- MIRROR: Tiles with alternating mirrored copies
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to configure |
wrap |
ceramic.TextureWrap | The wrapping mode for the S (horizontal) axis |
setTextureWrapT(texture: backend.Texture, wrap: ceramic.TextureWrap): VoidSets the vertical (T/V axis) wrapping mode for a texture.
Wrapping determines what happens when texture coordinates exceed 0-1:
- CLAMP: Clamps to edge pixels
- REPEAT: Tiles the texture
- MIRROR: Tiles with alternating mirrored copies
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to configure |
wrap |
ceramic.TextureWrap | The wrapping mode for the T (vertical) axis |
createRenderTarget(width: Int, height: Int, depth: Bool, stencil: Bool, antialiasing: Int): backend.TextureCreates a render target texture for off-screen rendering.
Render targets allow rendering to a texture instead of the screen. This is used for post-processing effects, render-to-texture, and more.
| Name | Type | Description |
|---|---|---|
width |
Int | The render target width in pixels |
height |
Int | The render target height in pixels |
depth |
Bool | Whether to include a depth buffer |
stencil |
Bool | Whether to include a stencil buffer |
antialiasing |
Int | MSAA sample count (0 or 1 for no antialiasing) |
| Returns | Description |
|---|---|
| backend.Texture | The created render target texture |
maxTexturesByBatch(): IntGets the maximum number of textures that can be used in a single draw call.
If this returns a value above 1, the backend supports multi-texture batching, which can significantly improve performance by reducing draw calls.
| Returns | Description |
|---|---|
| Int | Maximum textures per batch (1 if multi-texturing is not supported) |
getTextureIndex(texture: backend.Texture): IntGets the texture slot index for multi-texture batching.
When using multi-texture batching, each texture is assigned to a slot (0 to maxTexturesByBatch-1). This index is used in shader texture arrays.
| Name | Type | Description |
|---|---|---|
texture |
backend.Texture | The texture to query |
| Returns | Description |
|---|---|
| Int | The texture's slot index for the current batch |
textureToPng(texture: backend.Texture, ?reversePremultiplyAlpha: Bool = true, ?path: String, done: Function): VoidExports a texture to PNG format.
This is useful for debugging, screenshots, or saving generated textures.
| Name | Type | Default | Description |
|---|---|---|---|
texture |
backend.Texture | The texture to export | |
reversePremultiplyAlpha |
Bool | true |
Whether to reverse premultiplied alpha (usually true) |
path |
String | (optional) | Optional file path to save the PNG |
done |
Function | Callback with PNG data bytes (null on error) |
pixelsToPng(width: Int, height: Int, pixels: ceramic.UInt8Array, ?path: String, done: Function): VoidConverts raw pixel data to PNG format.
| Name | Type | Default | Description |
|---|---|---|---|
width |
Int | Image width in pixels | |
height |
Int | Image height in pixels | |
pixels |
ceramic.UInt8Array | RGBA pixel data (width * height * 4 bytes) | |
path |
String | (optional) | Optional file path to save the PNG |
done |
Function | Callback with PNG data bytes (null on error) |