Texture Atlasing

Prysm provides support for texture atlasing, allowing you to batch multiple UE textures in a larger one and sample from it, instead of binding different textures on every draw call. Grouping textures used in the same screen in your UI will provide for more batching and improve performance, especially on mobile devices.

Overview

The feature is accessible from the Prysm submenu and from the Content Browser. The Atlas Viewer and Atlas Preview windows, along with the context menu extensions are the tools you can use to manage your atlases.

Adding a new atlas

Adding a new atlas can be done in the following ways:

  • From the plus button in the Atlas Viewer
  • By selecting one, or more assets in the Content Browser, right-clicking and choosing Add to atlas
  • By selecting one or more folders in the Content Browser, right-clicking and choosing Atlas assets in folder

The first approach will create an empty atlas, which you can then populate with textures. The second and third approaches can add the textures to either a new, or an existing atlas.

Renaming an atlas

New atlases are always created with default names. To rename an atlas, you can use the Atlas Name field in the Atlas Viewer window.

Deleting an atlas

The Atlas Viewer window also allows you to delete an atlas, which is no longer used via the Delete button.

Modifying an atlas' parameters

The Preview button in the Atlas Viewer window opens the preview window, from where you can edit an already existing atlas. The properties that you can modify include:

  • The textures which the atlas contains
  • The maximum atlas dimensions
  • The maximum dimensions of a texture that can be included in the atlas (textures exceeding these dimensions will be dropped from the atlas)

Changing atlas locations

By default atlases will be created under Content/Atlases, however if you need to change this location, it can easily be done either by changing the Atlas Path field in the Atlas Viewer window, or by changing the Atlas Location field in the Atlas Preview window.

Packaging and source control

All atlases are saved to and loaded from the Content/Atlases folder of your project, along with the atlas metadata (i.e. which asset is contained in which atlas, and where its region is in that atlas). That same directory is automatically set to always be cooked and staged, so that the atlas assets and metadata are available in a packaged game. You can keep the entire folder under source control and update it when you add, remove, or modify an atlas.

Alternatively, you may have changed the location of one or more atlases, in which case the atlas metadata file will still remain under Content/Atlases and contain the other locations for each created atlas. Cooking of new atlas locations has to be either manually added in your project’s packaging settings (by opening Project Settings, then navigating to Packaging settings and adding the location to the Additional Asset Directories to Cook list), or you can use our option to automatically package new atlases (this option is disabled by default).

For example, given the first screenshot from this section, apart from Game/Atlases, there are Game/NewLocation and Game/AnotherNewLocation. In this case these locations were changed with our automatic packaging option enabled, which resulted in the following settings being applied:

Details

We keep track of the atlased textures and rebuild the corresponding atlas every time they are modified in any way - re-saved, re-imported, deleted, etc. In order for this metadata to be preserved between Editor runs and used in the Runtime module of our plugin, we utilize UE’s serialization to store it in a binary file named AtlasMappingData.cohtmlamd, inside the Content/Atlases folder of your project. This metadata file stores information about each atlased texture’s Atlas Path, Width, Height, ContentRectWidth, ContentRectHeight, OriginX and OriginY.

You can modify the individual atlas settings by opening an atlas file as a normal UTexture in the UE Editor. Even after rebuilding the atlas, these textures will be preserved, with the exception of the texture Compression Settings, which are expected to be set to VectorDisplacementmap(RGBA8), and will be changed back to that value every time the atlas is rebuilt.