Texture Packing
Spine can pack your individual images into a texture atlas or grid (spritesheet) for more efficient rendering at runtime. Spine's texture packer is a general purpose tool. While it can be used for your Spine skeletons, it can also be run separately to pack all the images for your applications.
In most graphics APIs (eg, OpenGL), a texture is bound, some drawing is done, another texture is bound, more drawing is done, etc. Binding the texture is relatively expensive, so it is ideal to store many smaller images on a larger image, bind the larger texture once, then draw portions of it many times. Spine can efficiently pack many smaller images on to larger images. The locations of the smaller images are stored in a simple data file so they are can be referenced by name in your application.
Spine uses multiple, advanced packing algorithms. Packing is done with numerous heuristics at various sizes and then the most efficient result is chosen.
Packing
The texture packer can be run two ways:
Packing during skeleton data export
While exporting JSON or binary, check Create Atlas:
This is a convenient way to export both the data and atlas at the same time, but will pack only the images each skeleton references and ignores the folder structure and JSON files. To pack the images for multiple skeletons into a single atlas, use the next method of running the packer.
Using the Spine Texture Packer separately
Choose Texture Packer from the main menu:
Then specify the path to the images to pack:
Settings
There are many settings to control how images are packed:
This can be intimidating at first, but for the most part the defaults will work fine. The most important settings are: 1) the max width/height, 2) whether premultiplied alpha is used, and 3) whether whitespace stripping is performed.
Regions
| Setting | Description |
|---|---|
| Strip whitespace X/Y | Removes blank pixels around the edges of the input images. The amount removed is stored in the atlas data so the images can be drawn in your application as if they were not whitespace stripped. |
| Rotation | More efficient packing is achieved by rotating some images 90 degrees. Applications must take special care to draw these regions properly. |
| Alias | Two images that are pixel for pixel the same will only be packed once. |
| Ignore blank images | Images that are only transparent pixels will not be packed. |
| Alpha threshold | Alpha values below this are treated as zero when whitespace is stripped. |
Region padding
| Setting | Description |
|---|---|
| Padding X/Y | The number of pixels between packed images. Some texture filtering averages neighboring pixels, so a padding of 2 is recommended to avoid neighboring regions from affecting each other. |
| Edge padding | The padding will also be applied to the edge of the page images. |
| Duplicate padding | The padding will copy pixels from the closest region. This can hide "seam" artifacts if texture filtering selects padding pixels. |
Pages
| Setting | Description |
|---|---|
| Min width/height | The smallest size for any page image. |
| Max width/height | The maximum size of any page image. If the images don't fit in a page this size, multiple page images are output. |
| Power of two | Makes the output page dimensions a power of two. This is a requirement for some game toolkits. |
| Square | Makes the width and height equal. This is a requirement for some texture compression algorithms (eg, PVRT). |
Output
| Setting | Description |
|---|---|
| Format | Output PNG or JPG pages. |
| JPG quality | The compression for JPG output. |
| Packing |
|
| Premultiply alpha | Multiplies pixel RGB values by the alpha value. This is recommended for proper blending. |
| Bleed | Sets RGB values for transparent pixels to the RGB values of the nearest non-transparent pixels. This prevents texture filtering artifacts when RGB values are sampled for transparent pixels. |
| Scale | A whole atlas is output for each scale specified. |
| Suffix | The suffix for each scaled atlas. If blank, files for multiple scales will be output with the same name to a subfolder for each scale. |
Options
| Setting | Description |
|---|---|
| Atlas extension | The file extension for the atlas data file. |
| Combine subdirectories | The current folder and all subfolders are packed on to the same pages. Any subfolder containing a `pack.json` file will not be combined. |
| Flatten paths | Subfolders are stripped from region file names. Image file names should be unique. |
| Use indexes | Image names are used without stripping any image index suffix (everything after the last underscore). |
| Debug | Lines are drawn on the output pages to show the packed image bounds. |
| Fast | Packing will not be as efficient but will execute much faster. |
| Limit memory | When unchecked, all images are loaded to memory at the same time to increase packing speed. Spine may crash if not enough memory is available. |
| Current project | When checked, mesh UVs for mesh image files in the current project are used to strip whitespace. When packing as part of data export, this setting is ignored and meshes in the current project are always used to strip whitespace. |
Runtime
These settings are hints intended for the application to optionally apply at runtime.
| Setting | Description |
|---|---|
| Filter min/mag | The texture minification and magnification settings. |
| Wrap X/Y | The texture wrap settings. |
| Format | The in-memory format. |
Other
These settings are not available on the settings dialog and may only be specified in the JSON configuration.
| Setting | Description |
|---|---|
| ignore | Images in this folder and any subfolders will not be packed. |
| limitMemory | If true, only one image is in memory at any given time, but each image will be read twice. If false, all images are kept in memory during packing but are only read once. |
Folder structure
Spine can pack all images for an application in one shot. Given a folder, it recursively scans for image files. For each folder of images Spine encounters, it packs the images on to a larger texture, called a page.
If the images in a folder don't fit on the max size of a single page, multiple pages will be used. Note when packing is done as part of JSON or binary export, the folder structure is not used.
Images in the same folder go on the same set of pages. If all images fit on a single page, no subfolders should be used because with one page the app will only ever perform one texture bind. Otherwise, subfolders can be used to segregate related images to minimize texture binds.
Eg, an application may want to place all the "game" images in a separate folder from the "pause menu" images, since these two sets of images are drawn serially: all the game images are drawn (one bind), then the pause menu is drawn on top (another bind). If the images were in a single folder that resulted in more than one page, each page could contain a mix of game and pause menu images. This would cause multiple texture binds to render the game and pause menu instead of just one each.
Subfolders are also useful to group images with related texture settings. Settings like runtime memory format (RGBA, RGB, etc) and filtering (nearest, linear, etc) are per texture. Images that need different per texture settings need to go on separate pages, so should be placed in separate subfolders.
To use subfolders for organization without Spine outputting a set of pages for each subfolder, see the Combine subdirectories setting.
To avoid subfolder paths being used in image names in the atlas file, see the Flatten paths setting.
JSON Configuration
Each folder may contain a "pack.json" file to specify settings for that folder. Each subfolder inherits all the settings from its parent folder. Any settings set in the subfolder override those set in the parent folder. Note when packing is done as part of JSON or binary export, the JSON configuration file is not used.
Below is a JSON example with every available setting.
pot: true,
paddingX: 2,
paddingY: 2,
bleed: true,
edgePadding: true,
duplicatePadding: false,
rotation: false,
minWidth: 16,
minHeight: 16,
maxWidth: 1024,
maxHeight: 1024,
square: false,
stripWhitespaceX: false,
stripWhitespaceY: false,
alphaThreshold: 0,
filterMin: Nearest,
filterMag: Nearest,
wrapX: ClampToEdge,
wrapY: ClampToEdge,
format: RGBA8888,
alias: true,
outputFormat: png,
jpegQuality: 0.9,
ignoreBlankImages: true,
fast: false,
debug: false,
combineSubdirectories: false,
flattenPaths: false,
premultiplyAlpha: false,
useIndexes: true,
grid: false,
scale: [ 1 ],
scaleSuffix: [ "" ],
limitMemory: true,
ignore: false
}
Note that this is libgdx's "minimal" JSON format, so double quotes are optional in most cases.
Not all settings need to be specified, any or all may be omitted. For example, to turn off padding and to combine subfolders, this JSON can be used:
paddingX: 0,
paddingY: 0,
combineSubdirectories: false
}
To ignore all images in a folder and all subfolders:
ignore: true
}
The Settings dialog has a Save JSON button which saves a JSON file with the current settings. This file can be named pack.json and placed in an input image folder to specify settings for that folder, rather than writing the JSON by hand.
Texture atlas name
When using command line export, packing is done by specifying the texture atlas name using the --pack or -p parameter:
Spine -i /path/to/images/ -o /path/to/output/ -p atlasName
The texture atlas name is used to name the atlas and PNG files. Running this example would result in atlasName.atlas and atlasName.png.
Alternatively, if the --pack or -p parameter ends in .json, then it used as a path to a pack JSON file:
Spine -i /path/to/images/ -o /path/to/output/ -p /path/to/atlasName.pack.json
When specifying a pack JSON file, the texture atlas name will be the pack JSON file name without the extension. In this example it would be atlasName. To specify a different texture atlas name, a name value can be specified in the pack JSON:
name: "atlasName",
paddingX: 0,
paddingY: 0,
combineSubdirectories: false
}
The name value can only be provided in the pack JSON specified with the --pack or -p parameter. It cannot be provided in pack JSON files located in the image input folders.
Ninepatches
Ninepatches are not generally useful for Spine skeletons, but can be useful for other purposes.
If an image file name ends with ".9" just before the file extension, it is considered a ninepatch. Ninepatch images can be created manually or by using this tool. The image must have a 1px transparent border. The upper and left edge may optionally have one contiguous line of black pixels which denote the split information, ie what part of the ninepatch will stretch. The bottom and right edge may optionally have one contiguous line of black pixels which denote the padding information, ie how content on top of the ninepatch should be inset. When this image is packed, the 1px border is removed and the split and padding information stored in the atlas data file.
Image indexes
Image indexes are not generally useful for Spine skeletons, but can be useful for other purposes.
If an image file name ends with underscore and then a number (eg animation_23.png), the number is considered the "index" and is stored for the region in the atlas data file. The image name is stored without the underscore and index. This allows a list of all images with the same name to be retrieved, ordered by index. This makes it easy to pack sprite animations without losing the order of the frames.
Texture Unpacker
Spine also provides a texture unpacking utility which takes a texture atlas and writes out individual images from it. Any rotation in the atlas is undone and any stripped whitespace is restored in the individual images.