Texture

View source
Entity → ceramic.Texture (Class) → RenderTexture

A texture represents an image loaded in GPU memory ready for rendering.

Textures are the foundation for displaying images in Ceramic. They can be:

  • Loaded from image files (PNG, JPG, etc.)
  • Created from pixel data
  • Generated as render targets
  • Extracted from texture atlases

Features:

  • Automatic density handling for different screen resolutions
  • Filtering modes (NEAREST for pixel art, LINEAR for smooth scaling)
  • Wrap modes for texture coordinates outside 0-1 range
  • Reference counting through asset management
  • Automatic cleanup when destroyed

Textures are typically obtained through asset loading rather than created directly:

// Load texture through assets
var texture = assets.texture('hero');

// Apply to a quad
var quad = new Quad();
quad.texture = texture;

// Configure for pixel art
texture.filter = NEAREST;

// Create texture from pixels
var pixels = Pixels.create(100, 100, Color.RED);
var texture = Texture.fromPixels(pixels);
See: ImageAsset, Quad, TextureAtlas

Static Members

fromPixels(width: Float, height: Float, pixels: UInt8Array, ?density: Float = 1): Texture

Create a new texture from raw pixel data. Useful for procedural texture generation or image manipulation.

Name Type Default Description
width Float Width of the texture in logical units
height Float Height of the texture in logical units
pixels UInt8Array Pixel buffer in RGBA format (4 bytes per pixel)
density Float 1 Texture density/scale (default: 1.0)
Returns Description
Texture A new Texture instance haxe var pixels = new UInt8Array(100 * 100 * 4); // Fill with red color for (i in 0...100*100) { pixels[i*4] = 255; // R pixels[i*4+1] = 0; // G pixels[i*4+2] = 0; // B pixels[i*4+3] = 255; // A } var texture = Texture.fromPixels(100, 100, pixels);
fromBytes(bytes: haxe.io.Bytes, ?density: Float = 1, ?options: Null<backend.LoadTextureOptions>, done: Function): Void

Create a new texture from PNG or JPEG data. Asynchronously decodes the image data and creates a texture.

Name Type Default Description
bytes haxe.io.Bytes The PNG or JPEG data as bytes
density Float 1 Texture density/scale (default: 1.0)
options Null<backend.LoadTextureOptions> (optional) Additional loading options (backend-specific)
done Function Callback receiving the loaded texture, or null if it failed haxe var imageBytes = Files.getBytes('custom.png'); Texture.fromBytes(imageBytes, 1.0, null, texture -> { if (texture != null) { quad.texture = texture; } });

Instance Members

isRenderTexture: Bool

Whether this texture is a render target. Render textures can be drawn to using RenderTexture class.

asRenderTexture: RenderTexture

If this is a render texture, returns the RenderTexture instance. Otherwise null.

The texture ID used by the underlying graphics API (OpenGL, etc.). This is backend-specific and mainly used for debugging or advanced usage.

nativeWidth: Int

The native pixel width of the texture in GPU memory. This is the actual texture size, not affected by density scaling.

nativeHeight: Int

The native pixel height of the texture in GPU memory. This is the actual texture size, not affected by density scaling.

nativeWidthActual: Int

The actual allocated width of the texture in GPU memory. May be larger than nativeWidth if the backend requires power-of-two dimensions. Use this for advanced texture coordinate calculations.

nativeHeightActual: Int

The actual allocated height of the texture in GPU memory. May be larger than nativeHeight if the backend requires power-of-two dimensions. Use this for advanced texture coordinate calculations.

width: Float

The logical width of the texture after density scaling. This is what you use for positioning and sizing visuals. Calculated as: nativeWidth / density

height: Float

The logical height of the texture after density scaling. This is what you use for positioning and sizing visuals. Calculated as: nativeHeight / density

density: Float

The texture density (scale factor). Used for supporting different screen resolutions:

  • 1.0 = standard resolution
  • 2.0 = retina/high-dpi (@2x assets)
  • 3.0 = extra high density (@3x assets) Changing this updates width/height accordingly.
filter: Anonymous

The texture filtering mode.

  • LINEAR: Smooth interpolation (default, good for photos)
  • NEAREST: No interpolation (good for pixel art) Change this based on your art style and scaling needs.

Horizontal texture wrap mode for UV coordinates outside 0-1 range.

  • CLAMP: Clamp to edge pixels (default)
  • REPEAT: Tile the texture
  • MIRROR: Tile with alternating mirrors

Vertical texture wrap mode for UV coordinates outside 0-1 range.

  • CLAMP: Clamp to edge pixels (default)
  • REPEAT: Tile the texture
  • MIRROR: Tile with alternating mirrors
backendItem: backend.Texture

The backend-specific texture resource. This is managed internally by Ceramic.

The image asset this texture was loaded from, if any. Automatically destroyed when the texture is destroyed.

setWrap(wrapS: TextureWrap, ?wrapT: TextureWrap): Void

Shorthand for setting both wrapS and wrapT at the same time. Possible values: CLAMP, REPEAT, MIRROR

Name Type Default Description
wrapS TextureWrap horizontal wrap mode
wrapT TextureWrap (optional) vertical wrap mode
destroy(): Void
fetchPixels(?result: Null<UInt8Array>): UInt8Array

Fetch the current pixel data from this texture. Reads pixels from GPU memory (can be slow).

Name Type Default Description
result Null<UInt8Array> (optional) Optional array to store results (will be allocated if null)
Returns Description
UInt8Array Array containing RGBA pixel data
submitPixels(pixels: UInt8Array): Void

Update this texture with new pixel data. Uploads pixels to GPU memory. The pixel array must match the texture's dimensions.

Name Type Description
pixels UInt8Array RGBA pixel data to upload
toPng(path: String, ?reversePremultiplyAlpha: Bool = true, done: Function): Void

Export texture as PNG data and save it to the given file path. Useful for screenshots or texture debugging.

Name Type Default Description
path String The png file path where to save the image ('/path/to/image.png')
reversePremultiplyAlpha Bool true
done Function Called when the png has been exported
new(backendItem: backend.Texture, ?density: Float = -1): Void

Create a new Texture from a backend texture resource. Usually you don't call this directly - use asset loading or fromPixels/fromBytes.

Name Type Default Description
backendItem backend.Texture The backend texture resource
density Float -1 Texture density (-1 uses screen density)

Private Members

toString(): String
Returns
String

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()