TextureAtlasPacker

Dynamic texture atlas builder that packs multiple images into optimized texture pages at runtime.

TextureAtlasPacker uses bin packing algorithms to efficiently arrange images into larger textures, minimizing wasted space and texture switches. This is useful for:

• Dynamically generated content (procedural graphics, text rendering)
• User-generated content that needs atlasing
• Optimizing texture usage for varying screen resolutions
• Creating atlases from individual loaded images

The packer features:

• Automatic page size growth (32x32 to 2048x2048)
• Multi-page support when content exceeds maximum size
• Configurable spacing between packed images
• Support for trimmed sprites with offset data
• Variant regions that share texture data

// Create a packer
var packer = new TextureAtlasPacker();
packer.spacing = 2; // 2 pixel margin
packer.filter = LINEAR;

// Add regions from pixel data
packer.add("player_idle", idlePixels, 64, 64, 60, 60, 2, 2);
packer.add("player_walk", walkPixels, 64, 64, 62, 62, 1, 1);

// Pack and get resulting atlas
packer.pack((atlas) -> {
    var playerRegion = atlas.region("player_idle");
    playerSprite.region = playerRegion;
});

Instance Members #

The resulting texture atlas after packing.

Created on first pack() call and reused for subsequent packing. Contains all pages and regions that have been packed.

Spacing between packed regions in pixels.

Adds a margin around each packed image to prevent texture bleeding during filtering. Recommended values: 1-2 pixels for linear filtering, 0 for nearest neighbor filtering.

Default: 1

Texture filtering mode for atlas pages.

Applied to all texture pages created by this packer.

• LINEAR: Smooth filtering (best for scaled graphics)
• NEAREST: Pixel-perfect filtering (best for pixel art)

Default: LINEAR

Checks if there are regions waiting to be packed.

Finds a region by name in pending or packed regions.

Searches both regions waiting to be packed and regions already packed into pages. Useful for creating variant regions or checking if a region exists.

Removes regions from the packer using a custom matching function.

This method allows selective removal of regions based on any criteria. It handles cleanup of both pending regions and already-packed regions, reorganizing the atlas as needed.

Removes all regions whose names start with the specified prefix.

Convenience method for removing groups of related regions. Commonly used for cleaning up temporary or category-specific regions.

Destroys the packer and all associated resources.

Cleans up:

• The generated atlas and all its textures
• Pending region data
• Internal packing structures

Add a region to this atlas packer from the given pixels. Example usage:

atlas.add(region1, pixels1);
atlas.add(region2, pixels2);
atlas.pack(() -> {
    // Done packing new regions
});

Packs all pending regions into texture atlas pages.

This method executes the bin packing algorithm to arrange all regions added via add() into optimal texture layouts. It handles:

• Automatic page size growth when regions don't fit
• Creation of new pages when maximum size is exceeded
• Texture generation from pixel data
• Variant region resolution

The packing process:

1. Attempts to fit regions into existing pages
2. Grows page size (up to MAX_TEXTURE_SIZE) if needed
3. Creates new pages when current pages are full
4. Generates GPU textures from packed pixel data
5. Creates TextureAtlasRegion instances for use

Creates a new texture atlas packer.

The packer starts empty - use add() to queue regions and pack() to build the atlas.

Private Members #

Minimum texture page size in pixels. Pages start at this size and grow as needed.

Maximum texture page size in pixels. When exceeded, additional pages are created. This limit ensures compatibility with most GPUs.

Regions waiting to be packed. Populated by add() calls, cleared after pack().

Internal page data for bin packing. Each page tracks its packer, regions, and texture state.

Event emitted when packing is complete.

Fired after all regions have been successfully packed and textures have been created. The atlas is ready for use.

Metadata #