TextureTilePacker

View source
Entity → ceramic.TextureTilePacker (Class)

Dynamic texture tile allocator with automatic packing and reuse capabilities.

TextureTilePacker provides a grid-based allocation system for dynamically creating and managing texture tiles within render textures. Unlike static texture atlases, this packer allows runtime allocation and deallocation of texture regions, making it ideal for:

  • Dynamic text rendering
  • Procedural graphics generation
  • Temporary visual effects
  • Runtime sprite composition

Features:

  • Grid-based allocation with configurable padding
  • Automatic texture chaining when space runs out
  • Tile reuse after deallocation
  • Visual stamping into allocated tiles
  • Margin support to prevent bleeding

The packer divides textures into a grid of fixed-size cells (pads) and allocates contiguous blocks for tiles that need more space.

// Create a packer for dynamic text
var packer = new TextureTilePacker(
    true,    // Auto-render
    2048,    // Max width
    2048,    // Max height
    64, 64,  // Pad size
    2        // Margin
);

// Allocate a tile
var tile = packer.allocTile(128, 32);

// Render content into the tile
var text = new Text();
text.content = "Dynamic Text";
packer.stamp(tile, text, () -> {
    // Use the tile
    quad.tile = tile;
});

// Release when done
packer.releaseTile(tile);
See: TextureTile The tiles allocated by this packer, RenderTexture The target texture for packing

Instance Members

The render texture containing all allocated tiles.

This texture is rendered to when stamping visuals into tiles. Size is determined by constructor parameters and screen density.

padWidth: Int

Width of each grid cell in pixels.

Tiles smaller than this will still occupy a full cell. Larger tiles will span multiple cells horizontally.

padHeight: Int

Height of each grid cell in pixels.

Tiles smaller than this will still occupy a full cell. Larger tiles will span multiple cells vertically.

margin: Int

Margin around each tile in pixels.

Prevents texture bleeding between adjacent tiles. Applied on all sides of allocated regions.

nextPacker: TextureTilePacker

Next packer in the chain for overflow handling.

When this packer runs out of space, tiles are allocated from the next packer, creating a linked list of textures.

destroy(): Void
allocTile(width: Int, height: Int): TextureTile

Allocates a new tile of the specified size.

Searches for available space in the grid that can accommodate the requested dimensions. If the tile is larger than a single pad, multiple adjacent pads are allocated. When no space is available, automatically creates a chained packer.

Name Type Description
width Int Required tile width in pixels
height Int Required tile height in pixels
Returns Description
TextureTile The allocated TextureTile, or null if dimensions exceed maximum * haxe // Allocate a 100x50 tile var tile = packer.allocTile(100, 50); if (tile != null) { // Tile successfully allocated myQuad.tile = tile; }
releaseTile(tile: TextureTile): Void

Releases a previously allocated tile for reuse.

Marks the tile's grid cells as available for future allocations. The release is deferred by two frames to ensure any pending rendering operations complete first.

Name Type Description
tile TextureTile The tile to release (must be from this packer)
stamp(tile: TextureTile, visual: Visual, done: Function): Void

Renders a visual into an allocated tile.

Stamps the visual's content into the tile's region of the render texture. The visual is temporarily reparented and transformed to fit within the tile bounds, including margins.

Name Type Description
tile TextureTile The target tile to render into
visual Visual The visual content to render
done Function Callback invoked when rendering completes * haxe // Render text into a tile var tile = packer.allocTile(200, 50); var text = new Text(); text.content = "Hello World"; * packer.stamp(tile, text, () -> { // Text is now rendered in the tile sprite.tile = tile; });
managesTexture(texture: Texture): Bool

Checks if a texture is managed by this packer or its chain.

Recursively searches through this packer and any chained packers to determine if the given texture belongs to the allocation system.

Name Type Description
texture Texture The texture to check
Returns Description
Bool True if this packer chain manages the texture
new(autoRender: Bool, ?maxPixelTextureWidth: Int = -1, ?maxPixelTextureHeight: Int = -1, ?padWidth: Int = 16, ?padHeight: Int = 16, ?margin: Int = 1): Void

Creates a new texture tile packer.

Name Type Default Description
autoRender Bool Whether to automatically render changes to the texture
maxPixelTextureWidth Int -1 Maximum texture width (-1 for auto based on density)
maxPixelTextureHeight Int -1 Maximum texture height (-1 for auto based on density)
padWidth Int 16 Width of each grid cell (default: 16)
padHeight Int 16 Height of each grid cell (default: 16)
margin Int 1 Pixel margin around tiles (default: 1)

Private Members

Grid storage for allocated tiles. Indexed as [row * numCols + col].

numCols: Int

Number of columns in the allocation grid.

numRows: Int

Number of rows in the allocation grid.

maxPixelTextureWidth: Int

Maximum texture width constraint in pixels.

maxPixelTextureHeight: Int

Maximum texture height constraint in pixels.

getTileAtPosition(col: Int, row: Int): TextureTile
Name Type
col Int
row Int
Returns
TextureTile
setTileAtPosition(col: Int, row: Int, tile: TextureTile): Void
Name Type
col Int
row Int
tile TextureTile

Metadata

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