Texture Atlasing

Gameface 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 Gameface 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.

If you’re using sprite sheets for CSS animations, they shouldn’t be added to an atlas, as this will lead to undesired behavior. Because the animation is based on specifying different areas from the entire image, a rectangle in the sprite sheet will have different content than the same rectangle in the 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).

Automatically package new atlases option

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:

With the automatic packaging option enabled, changing the default location of an atlas results in the new location being added to the Additional Asset Directories to Cook list of your project’s Packaging Settings.

If this location contains no more Gameface atlases (due to them being moved, or deleted), or if the directory got moved, or deleted, it will get removed from the Additional Asset Directories to Cook list automatically. If the directory got renamed, the old path will be removed and replaced with the new one.

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.

The metadata binary file doesn’t track ContentRectWidth and ContentRectHeight values in Gameface versions prior to 1.15.0, so a metadata file created in such versions can’t be used in versions after 1.14.0. This means you will have to manually delete both the metadata and your .uasset Atlas files (since the new metadata file won’t have information about them), and then recreate your Atlases.

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.

Please don’t change the Maximum Texture Size setting for the atlas texture. If you do that and the atlas is downsized, that will break the internal logic for loading individual images from the atlas and in turn will lead to a broken UI.

Currently, texture atlasing only works with UE textures. This means that only assets that have already been imported in UE can be added to an atlas. The source images must be in .tga format due to artifacts in the transparent areas of the image that other formats have after being imported in UE.

If you want to add an asset to multiple atlases, currently any modifications to that asset will trigger a rebuild only for the last atlas, to which it was added. To rebuild other atlases that contain that asset, you can use the Rebuild button in the Atlas Viewer window. The same rule applies when a page in your UI uses the asset - it will be loaded from the last atlas, to which it was added. If you want to have such functionality, you can subclass our FCohtmlFileHandler and extend it to support such use cases.

Not all texture settings will be transferred to the in-atlas texture representation. In fact, only the textures' visual representation will be copied into the atlas. This means that settings that do not change the texture’s visual representation in the UE Editor immediately, will not affect the atlas at all. For example, most of the LOD settings for the individual textures won’t be taken into account.

Texture Atlasing

Overview #

Adding a new atlas #

Renaming an atlas #

Deleting an atlas #

Modifying an atlas' parameters #

Changing atlas locations #

Packaging and source control #

Details #