Texture atlases

Texture atlases (also called texture sheets, sprite sheets, flipbooks, or sub-UVs), are a way to pack multiple textures into a larger texture.
You can use them to represent animated textures, or to pack different unrelated textures together. Packing different unrelated textures allows to draw different particle renderers in the same draw-call, which helps rendering performance.

PopcornFX loads texture atlas definitions from .pkat files, which is a simple text file containing a list of UV coordinates.
The following components can currently use texture atlases:

The renderers allow you to specify a procedural atlas: If your texture is laid out in a regular grid of tiles, as is usually the case of animated flipbooks, you can specify the dimensions of that grid in the renderer’s properties:
Texture atlases: Billboard renderer procedural atlas definition
When your texture sub-UVs are not laid out along a regular grid, you will need to use an external atlas definition file:
Texture atlases: Billboard renderer external atlas definition

Creating atlas files

Non-procedural atlases will require you to provide an atlas definition file (with the ".pkat" extension).
This is required only for more complex packing layouts, which cannot be represented by a regular grid.

Originally, in PopcornFX v1.x, pkat files were created using the atlas builder tool that shipped with the v1 editor.
In v2, we chose not to keep maintaining this aging tool.

To create .pkat files, you can use the following tools that support exporting them out of the box:

Alternatively, you can also create them by hand in a text editor (see the definition file format section below)

Exporting with TexturePacker

To export your texture sheet from TexturePacker into the PopcornFX format, simply click on the "DataFormat" button in the TexturePacker settings panel, and pick the "PopcornFX" exporter from the list:
Texture atlases: exporting with TexturePacker
Important note: Trimming the sprites is currently not supported, so make sure you keep the "Trim mode" setting under the "Sprites" category set to "None"

Atlas definition file format

The .pkat files are simple text files. They are formatted as follows:

  • One line per sub-texture

  • 4 values per line, separated by commas

  • The decimal point is a dot, not a comma

  • The values are normalized texture coordinates, between 0.0 and 1.0

  • The coordinates are in the following order: left, top, right, bottom

Texture atlas: Definition

For example, the .pkat file for a 2x2 texture atlas would look like this:

Texture atlases: Simple 2x2 atlas

0,     0, 0.5, 0.5
0.5,   0,   1, 0.5
0,   0.5, 0.5,   1
0.5, 0.5,   1,   1

Of course, the sub-rectangles can be anything, the whole texture doesn’t have to be covered entirely either.
The .pkat file for a 3x1 texture atlas only spanning half of the vertical height would look like this:

Texture atlases: 3x1 atlas

0,     0, 0.333, 0.5
0.333, 0, 0.667, 0.5
0.667, 0, 1,     0.5