Class SpriteSheet

Namespace

Egami

Assembly

Egami.dll

A sprite sheet: many images packed into one, with the rectangle of each. Packing uses the MaxRects algorithm with the best short side fit (Jylänki, "A Thousand Ways to Pack the Bin", 2010), the images taken by height, tallest first, and then by input order, so the same inputs always give the same sheet. Sprites are never rotated.

public sealed class SpriteSheet : IDisposable

Inheritance

object

SpriteSheet

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Pack sprites with a 2-pixel gap and 1 pixel of extruded edge, so GPU filtering never bleeds between them.
using SpriteSheet sheet = SpriteSheet.Pack([small, tiny, small, tiny], new SpritePackOptions { Padding = 2, Extrude = 1, PowerOfTwo = true });
sheet.Image.Save("sprites.png");

// The rectangles are plain data: writing them for a game engine is one line of System.Text.Json.
File.WriteAllText("sprites.json", JsonSerializer.Serialize(sheet.Frames.Select(f => new { f.X, f.Y, w = f.Width, h = f.Height })));

Properties

Frames

Gets where each input sits on the sheet, in input order.

public IReadOnlyList<Rect> Frames { get; }

Property Value

IReadOnlyList<Rect>

Image

Gets the sheet. It has the first input's pixel type, metadata and color profile, and a transparent background.

public Raster Image { get; }

Property Value

Raster

Offsets

Gets, for each input, where its packed rectangle sat in the original image: (0, 0) unless Trim cut a transparent border away.

public IReadOnlyList<Point> Offsets { get; }

Property Value

IReadOnlyList<Point>

Methods

Dispose()

Frees the sheet.

public void Dispose()

Pack(IReadOnlyList<Raster>, SpritePackOptions?)

Packs the images' first frames into as small a sheet as it finds.

public static SpriteSheet Pack(IReadOnlyList<Raster> images, SpritePackOptions? options = null)

Parameters

images IReadOnlyList<Raster>

At least one raster, of any sizes and pixel types.

options SpritePackOptions

The layout options, or null for the defaults.

Returns

SpriteSheet

The sheet and the rectangles. The caller must dispose it.

Examples

// Pack sprites with a 2-pixel gap and 1 pixel of extruded edge, so GPU filtering never bleeds between them.
using SpriteSheet sheet = SpriteSheet.Pack([small, tiny, small, tiny], new SpritePackOptions { Padding = 2, Extrude = 1, PowerOfTwo = true });
sheet.Image.Save("sprites.png");

// The rectangles are plain data: writing them for a game engine is one line of System.Text.Json.
File.WriteAllText("sprites.json", JsonSerializer.Serialize(sheet.Frames.Select(f => new { f.X, f.Y, w = f.Width, h = f.Height })));

Exceptions

ArgumentNullException

images or one of them is null.

ArgumentException

images is empty, or an image (with its padding and extrusion) is wider than MaxWidth, naming its index.

LimitExceededException

The sheet would break MaxTotalBytes.