Atlas export format

Spine exports texture atlases using the libgdx atlas format. This is a simple, line-based text format made up of one or more page entries, each with any number of region entries. Page entries are separated by a blank line. Here is an example atlas with 2 pages:

page1.png
size: 640,480
format: RGBA8888
filter: Linear,Linear
repeat: none
dagger
rotate: true
xy: 372, 100
size: 26, 108
orig: 26, 108
offset: 0, 0
index: -1
head
rotate: false
xy: 2, 21
size: 103, 81
orig: 103, 81
offset: 0, 0
index: -1

page2.png
size: 640,480
format: RGBA8888
filter: Linear,Linear
repeat: none
bg-dialog
rotate: false
xy: 519, 223
size: 21, 42
split: 10, 10, 29, 10
pad: -1, -1, 28, 10
orig: 21, 42
offset: 0, 0
index: -1

Page sections

The page section provides the page image name and information about loading and rendering the image. Here is an example of the page section header:

page1.png
size: 640,480
format: RGBA8888
filter: Linear,Linear
repeat: none

Page properties:

  • name: The first line is the image name for this page. Where the image is located is up to the atlas loader, but typically it is in the same directory as the atlas file.
  • size: The width and height of the page image. This may be useful for the atlas loader to know before it loads the image, eg to allocate a buffer.
  • format: The format to use for storing the image in memory. Atlas loaders may ignore this property. Possible values: Alpha, Intensity, LuminanceAlpha, RGB565, RGBA4444, RGB888, RGBA8888.
  • filter: The texture filter minification and magnification settings. Atlas loaders may ignore this property. Possible values: Nearest, Linear, MipMap, MipMapNearestNearest, MipMapLinearNearest, MipMapNearestLinear, MipMapLinearLinear.
  • repeat: The texture wrap settings. Atlas loaders may ignore this property. Possible values: x, y, xy, none.

Region sections

The region section provides the region location within the page image and other information about the region. Here is an example of a region section:

bg-dialog
rotate: false
xy: 519, 223
size: 21, 42
split: 10, 10, 29, 10
pad: -1, -1, 28, 10
orig: 21, 42
offset: 0, 0
index: -1

Region properties:

  • name: The first line is the region name. This is used to find a region in the atlas. Multiple regions may have the same name if they have a different index.
  • rotate: If true, the region was stored in the page image rotated by 90 degrees counter clockwise.
  • xy: The pixel location of this image within the page image.
  • size: The packed size, which is the pixel size of this image within the page image.
  • split: The left, right, top, and bottom splits for a ninepatch. These are the number of pixels from the unpacked image edge. Splits define a 3x3 grid for a resizing an image without stretching all parts of the image. split may be omitted.
  • pad: The left, right, top, and bottom padding for a ninepatch. These are the number of pixels from the unpacked image edge. Padding allows content placed on top of a ninepatch to be inset differently from the splits. pad may be omitted and is always omitted if there is no split.
  • orig: The original size, which is the pixel size of this image before it was packed. If whitespace stripping was performed, this may be larger than the region in the page image.
  • offset: The amount of whitespace pixels that were stripped from the left and bottom edges of the image before it was packed.
  • index: An index allows many images to be packed using the same name, as long as each has a different index. Typically the index is the frame number for regions that will be shown sequentional for frame by frame animation.

A blank line after a region section denotes the end of regions for a page. The next line after that will be either another page section or the end of the file.

Rendering

Special care must be taken when rendering a region from an atlas, depending on the texture packing settings that created the atlas. These settings result in more efficient texture packing, but to simplify rendering they can be disabled when the atlas is created.

Rotation

If the region was stored in the atlas as rotated by 90 degrees, rendering needs to adjust the UVs to undo the rotation.

Whitespace stripping

If the region was stripped of whitespace around its edges before being packed, rendering needs to adjust the drawing position so it appears as though the whitespace was not removed.

If a region can be drawn flipped, the whitespace stripping must be taken into account when rendering the flipped region.

The amount of whitespace removed from the right and top can be calculated this way:

offsetRight = originalWidth - packedWidth - offsetLeft
offsetTop = originalHeight - packedHeight - offsetBottom