TextureAtlasRegion

Represents a single image region within a texture atlas.

TextureAtlasRegion defines a rectangular area within a texture atlas page that contains a specific image. It extends TextureTile, allowing it to be directly assigned to visual objects like Quad.tile for rendering.

Key features:

• Supports trimmed sprites with offset data
• Handles rotated regions for optimal packing
• Automatic UV coordinate calculation
• Direct integration with the rendering system

The region stores both the packed dimensions (actual space used in atlas) and original dimensions (including trimmed transparent areas), enabling proper sprite alignment and collision detection.

// Get a region from atlas
var region = atlas.region("player_idle");

// Apply to a quad (basic support)
var quad = new Quad();
quad.tile = region;

// Position accounting for trim offset
quad.pos(100 + region.offsetX, 200 + region.offsetY);

// Apply to a sprite (extended support of trimmed regions with offsets, needs sprite plugin)
var sprite = new Sprite();
sprite.region = region;

Instance Members #

Unique identifier for this region within the atlas.

Used to retrieve specific images from the atlas. Often matches the original image filename without extension.

Reference to the containing texture atlas.

Provides access to the atlas pages and other regions. Set automatically during region creation.

Index of the texture page containing this region.

Large atlases may span multiple texture pages. Used to retrieve the correct texture for rendering.

Actual width of packed pixels in the atlas.

This is the width after any rotation applied during packing. May be different from display width if the region was rotated. Used for texture coordinate calculations.

Actual height of packed pixels in the atlas.

This is the height after any rotation applied during packing. May be different from display height if the region was rotated. Used for texture coordinate calculations.

X position of the region within its texture page.

Pixel coordinate from the left edge of the texture. Used to calculate texture coordinates for rendering.

Y position of the region within its texture page.

Pixel coordinate from the top edge of the texture. Used to calculate texture coordinates for rendering.

Display width of the region (before any rotation).

This is the width of the visible pixels, excluding any transparent areas that were trimmed during packing.

Display height of the region (before any rotation).

This is the height of the visible pixels, excluding any transparent areas that were trimmed during packing.

Horizontal offset from original sprite origin.

When sprites are trimmed, this offset maintains proper alignment. Positive values shift the sprite right. Add to sprite X position for correct placement.

Vertical offset from original sprite origin.

When sprites are trimmed, this offset maintains proper alignment. Positive values shift the sprite down. Add to sprite Y position for correct placement.

Original sprite width before trimming.

Includes any transparent margins that were removed during atlas packing. Use this for maintaining consistent sprite sizes and proper collision bounds.

Original sprite height before trimming.

Includes any transparent margins that were removed during atlas packing. Use this for maintaining consistent sprite sizes and proper collision bounds.

Calculates texture coordinates from pixel positions.

Converts the pixel-based region coordinates (x, y, width, height) into normalized UV coordinates for GPU rendering. This method must be called after the atlas page textures are loaded to ensure proper coordinate calculation.

The method handles:

• Texture density scaling
• Coordinate normalization (0-1 range)
• Frame property updates for rendering

Typically called automatically by TextureAtlas.computeFrames() after all pages are loaded.

Creates a new texture atlas region.

Typically called internally by atlas parsers and packers. Automatically registers this region with the atlas.

Private Members #

Returns a detailed string representation of this region.

Includes all region properties for debugging purposes: name, page index, dimensions, offsets, and texture coordinates.