Table of Contents

Class RuntimeTexturePacker

Namespace
MLEM.Data
Assembly
MLEM.Data.dll

A runtime texture packer provides the user with the ability to combine multiple Microsoft.Xna.Framework.Graphics.Texture2D instances into a single texture. Packing textures in this manner allows for faster rendering, as fewer texture swaps are required. The resulting texture segments are returned as TextureRegion instances.

public class RuntimeTexturePacker : IDisposable
Inheritance
RuntimeTexturePacker
Implements
Inherited Members

Remarks

The algorithm used by this implementation is based on the blog post "Binary Tree Bin Packing Algorithm", which can be found at https://codeincomplete.com/articles/bin-packing/.

Constructors

RuntimeTexturePacker(bool, bool, bool)

Creates a new runtime texture packer with the given settings.

public RuntimeTexturePacker(bool forcePowerOfTwo = false, bool forceSquare = false, bool disposeTextures = false)

Parameters

forcePowerOfTwo bool

Whether the resulting PackedTexture should have a width and height that is a power of two.

forceSquare bool

Whether the resulting PackedTexture should be square regardless of required size.

disposeTextures bool

Whether the original textures submitted to this texture packer should be disposed after packing.

Properties

LastCalculationTime

The time that it took to calculate the required areas the last time that Pack(GraphicsDevice) was called

public TimeSpan LastCalculationTime { get; }

Property Value

TimeSpan

LastPackTime

The time that it took to copy the texture data from the invidiual textures onto the PackedTexture the last time that Pack(GraphicsDevice) was called

public TimeSpan LastPackTime { get; }

Property Value

TimeSpan

LastTotalTime

The time that Pack(GraphicsDevice) took the last time it was called

public TimeSpan LastTotalTime { get; }

Property Value

TimeSpan

PackedTexture

The generated packed texture. This value is null before Pack(GraphicsDevice) is called.

public Texture2D PackedTexture { get; }

Property Value

Texture2D

PackedTextures

The amount of currently packed texture regions.

public int PackedTextures { get; }

Property Value

int

Methods

Add(DataTextureAtlas, Action<Dictionary<string, TextureRegion>>, int, bool)

Adds a new DataTextureAtlas to this texture packer to be packed. The passed Action<T> is invoked in Pack(GraphicsDevice) and provides the caller with the resulting dictionary of texture regions on the PackedTexture, mapped to their name on the original DataTextureAtlas. Note that the resulting data cannot be converted back into a DataTextureAtlas, since the resulting texture regions might be scattered throughout the PackedTexture.

public void Add(DataTextureAtlas atlas, Action<Dictionary<string, TextureRegion>> result, int padding = 0, bool padWithPixels = false)

Parameters

atlas DataTextureAtlas

The texture atlas to pack.

result Action<Dictionary<string, TextureRegion>>

The result callback which will receive the resulting texture regions.

padding int

The padding that the texture should have around itself. This can be useful if texture bleeding issues occur due to texture coordinate rounding.

padWithPixels bool

Whether the texture's padding should be filled with a copy of the texture's border, rather than transparent pixels. This value only has an effect if padding is greater than 0.

Exceptions

InvalidOperationException

Thrown when trying to add a texture width a width greater than the defined max width.

Add(TextureRegion, Action<TextureRegion>, int, bool)

Adds a new TextureRegion to this texture packer to be packed. The passed Action<T> is invoked in Pack(GraphicsDevice) and provides the caller with the resulting texture region on the PackedTexture.

public void Add(TextureRegion texture, Action<TextureRegion> result, int padding = 0, bool padWithPixels = false)

Parameters

texture TextureRegion

The texture region to pack.

result Action<TextureRegion>

The result callback which will receive the resulting texture region.

padding int

The padding that the texture should have around itself. This can be useful if texture bleeding issues occur due to texture coordinate rounding.

padWithPixels bool

Whether the texture's padding should be filled with a copy of the texture's border, rather than transparent pixels. This value only has an effect if padding is greater than 0.

Exceptions

InvalidOperationException

Thrown when trying to add a texture width a width greater than the defined max width.

Add(UniformTextureAtlas, Action<Dictionary<Point, TextureRegion>>, int, bool, bool)

Adds a new UniformTextureAtlas to this texture packer to be packed. The passed Action<T> is invoked in Pack(GraphicsDevice) and provides the caller with the resulting dictionary of texture regions on the PackedTexture, mapped to their x and y positions on the original UniformTextureAtlas. Note that the resulting data cannot be converted back into a UniformTextureAtlas, since the resulting texture regions might be scattered throughout the PackedTexture.

public void Add(UniformTextureAtlas atlas, Action<Dictionary<Point, TextureRegion>> result, int padding = 0, bool padWithPixels = false, bool ignoreTransparent = false)

Parameters

atlas UniformTextureAtlas

The texture atlas to pack.

result Action<Dictionary<Point, TextureRegion>>

The result callback which will receive the resulting texture regions.

padding int

The padding that the texture should have around itself. This can be useful if texture bleeding issues occur due to texture coordinate rounding.

padWithPixels bool

Whether the texture's padding should be filled with a copy of the texture's border, rather than transparent pixels. This value only has an effect if padding is greater than 0.

ignoreTransparent bool

Whether completely transparent texture regions in the atlas should be ignored. If this is true, they will not be part of the result collection either.

Exceptions

InvalidOperationException

Thrown when trying to add a texture width a width greater than the defined max width.

Add(Texture2D, Action<TextureRegion>, int, bool)

Adds a new Microsoft.Xna.Framework.Graphics.Texture2D to this texture packer to be packed. The passed Action<T> is invoked in Pack(GraphicsDevice) and provides the caller with the resulting texture region on the PackedTexture.

public void Add(Texture2D texture, Action<TextureRegion> result, int padding = 0, bool padWithPixels = false)

Parameters

texture Texture2D

The texture to pack.

result Action<TextureRegion>

The result callback which will receive the resulting texture region.

padding int

The padding that the texture should have around itself. This can be useful if texture bleeding issues occur due to texture coordinate rounding.

padWithPixels bool

Whether the texture's padding should be filled with a copy of the texture's border, rather than transparent pixels. This value only has an effect if padding is greater than 0.

Exceptions

InvalidOperationException

Thrown when trying to add a texture width a width greater than the defined max width.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Pack(GraphicsDevice)

Packs all of the textures and texture regions added using Add(Texture2D, Action<TextureRegion>, int, bool) into one texture, which can be retrieved using PackedTexture. All of the result callbacks that were added will also be invoked. This method can be called multiple times if regions are added after Pack(GraphicsDevice) has already been called. When doing so, result callbacks of previous regions may be invoked again if the resulting PackedTexture has to be resized to accommodate newly added regions.

public void Pack(GraphicsDevice device)

Parameters

device GraphicsDevice

The graphics device to use for texture generation

Reset()

Resets this texture packer entirely, disposing its PackedTexture, clearing all previously added requests, and readying it to be re-used.

public void Reset()
Edit this page