[Atom] Image Builder - o3de/o3de GitHub Wiki

Image Builder

The O3DE image builder is the asset builder to convert different type of images files to textures used for O3DE runtime. The builder is called by AssetProcessor. The image builder is located in Atom's ImageProcessingAtom gem which is under O3DE engine's \Gems\Atom\Asset\ImageProcessingAtom\ folder.

Supported Image File Types

Here are a list of supported image file types

  • "*.tif"
  • "*.tiff"
  • "*.png"
  • "*.bmp"
  • "*.jpg"
  • "*.jpeg"
  • "*.tga"
  • "*.gif"
  • "*.dds"
  • "*.exr"

Supported Image Pixel Format

Here are a list of supported image pixel formats: (origin: o3de/Gems/Atom/Asset/ImageProcessingAtom/Code/Source/Processing/PixelFormatInfo.cpp)

Unsigned

  • "R8G8B8A8"
  • "R8G8B8X8"
  • "R8G8"
  • "R8"
  • "A8"
  • "R16G16B16A16"
  • "R16G16"
  • "R16"

ASTC

  • "ASTC_4x4"
  • "ASTC_5x4"
  • "ASTC_5x5"
  • "ASTC_6x5"
  • "ASTC_6x6"
  • "ASTC_8x5"
  • "ASTC_8x6"
  • "ASTC_8x8"
  • "ASTC_10x5"
  • "ASTC_10x6"
  • "ASTC_10x8"
  • "ASTC_10x10"
  • "ASTC_12x10"
  • "ASTC_12x12"

BCn

  • "BC1"
  • "BC3"
  • "BC4"
  • "BC5"
  • "BC6UH"
  • "BC7"

Float formats

  • "R9G9B9E5"
  • "R32G32B32A32F"
  • "R32G32F"
  • "R32F"
  • "R16G16B16A16F"
  • "R16G16F"
  • "R16F"

Image Builder Settings

The default settings used by the image builder is located in O3DE's \Gems\Atom\Asset\ImageProcessingAtom\Assets\Config\ folder which we call it default folder.

There are two types of settings files: one ImageBuilder.settings file and .preset files. Both of these setting files are in json format.

The ImageBuilder.settings defines global settings for the builder. You can find the list of available settings in BuilderSettingManager::Reflect(AZ::ReflectContext* context) function.

A preset file defines all the conversion which could happen in an image conversion process. The available settings are listed in void PresetSettings::Reflect(AZ::ReflectContext* context) function.

Each O3DE project can override or modify both the ImageBuilder.settings file or any preset files. It can also add new presets. These files should be placed in %project%\Config\AtomImageBuilder\ folder which we call it project folder.

For modifying ImageBuilder.settings, user may create a json merge patch in the said folder using the same name ImageBuilder.settings. The image builder will merge this file and \Gems\Atom\Asset\ImageProcessingAtom\Assets\Config\ImageBuilder.settings to get the final settings. For example, the ImageBuilder.settings may look like this:

{
    "ClassData": {
        "PresetsByFileMask": {
            // remove _diff file mask
            "_diff": null,
            // add new mapping to map _alpha to Alpha preset
            "_alpha": [ "Alpha"]
        }
    }
}

For preset files, currently the same preset in project folder is overriding the preset in default folder. (We may consider to switch it to use merge in the future). Users may also adding new preset files in project folder to add new customized presets. It's preferred to add file mask mapping for the new presets in ImageBuilder.settings for easy apply new presets to files. The fileMasks in each preset is still supported but it might be deprecated in the future.

Preset settings

The settings in a preset file (*.preset) are defined in PresetSettings class which is located in o3de\Gems\Atom\Asset\ImageProcessingAtom\Code\Source\BuilderSettings\PresetSettings.h file. The names of the settings are mapped in void PresetSettings::Reflect(AZ::ReflectContext* context) function. Here some common used settings in a preset file. (There are few settings which are not often used are not listed here. You may find them in the header file)

Setting name Description
Name A unique name of the preset
Description A short description about what the preset is used for
GenerateIBLOnly Controls whether this preset only invokes IBL presets and does not generate its own output product
SourceColor The color space of the source image. It can be sRGB or Linear
DestColor The color space of the output image. It can be sRGB, Linear or Auto
FileMasks A list of file suffixes which files with these suffixed are preferred to choose this preset
PixelFormat The pixel format of output image. The format will be ignored if the OutputTypeHandling is set to UseInputFormat
DiscardAlpha Set to true to discard alpha channel data during converting
MaxTextureSize The maximum texture size for the output image
MinTextureSize The minimum texture size for the output image
SizeReduceLevel Reduce the texture size with specified levels (mip)
GlossFromNormal Set to true to generate glass data from the normal map and save it to alpha channel. The normal map will be normalized.
MipRenormalize Set to true to re-normalize mipmaps
NumberResidentMips Defines how many low level mipmaps are resident mipmaps when create the image. The system will decide how many if it's set to 0
Swizzle Swizzle color channels
CubemapSettings Settings for cubemap
MipMapSetting Settings for generating mipmaps
OutputTypeHandling Decides if the output pixel format uses the PixelFormat or use the source image pixel format

Here is an example preset file for processing textures used for skybox

{
    "Type": "JsonSerialization",
    "Version": 1,
    "ClassName": "MultiplatformPresetSettings",
    "ClassData": {
        "DefaultPreset": {
            "UUID": "{F359CD3B-37E6-4627-B4F6-2DFC2C0E3C1C}",
            "Name": "Skybox",
            "SourceColor": "Linear",
            "DestColor": "Linear",
            "SuppressEngineReduce": true,
            "PixelFormat": "R9G9B9E5",
            "DiscardAlpha": true,
            "MinTextureSize": 256,
            "IsPowerOf2": true,
            "CubemapSettings": {
                "RequiresConvolve": false
            }
        },
        "PlatformsPresets": {
            "android": {
                "UUID": "{F359CD3B-37E6-4627-B4F6-2DFC2C0E3C1C}",
                "Name": "Skybox",
                "SourceColor": "Linear",
                "DestColor": "Linear",
                "SuppressEngineReduce": true,
                "PixelFormat": "R9G9B9E5",
                "DiscardAlpha": true,
                "MinTextureSize": 256,
                "IsPowerOf2": true,
                "CubemapSettings": {
                    "RequiresConvolve": false
                }
            },
            "ios": {
                "UUID": "{F359CD3B-37E6-4627-B4F6-2DFC2C0E3C1C}",
                "Name": "Skybox",
                "SourceColor": "Linear",
                "DestColor": "Linear",
                "SuppressEngineReduce": true,
                "PixelFormat": "R9G9B9E5",
                "DiscardAlpha": true,
                "MinTextureSize": 256,
                "IsPowerOf2": true,
                "CubemapSettings": {
                    "RequiresConvolve": false
                }
            },
            "mac": {
                "UUID": "{F359CD3B-37E6-4627-B4F6-2DFC2C0E3C1C}",
                "Name": "Skybox",
                "SourceColor": "Linear",
                "DestColor": "Linear",
                "SuppressEngineReduce": true,
                "PixelFormat": "R9G9B9E5",
                "DiscardAlpha": true,
                "MinTextureSize": 256,
                "IsPowerOf2": true,
                "CubemapSettings": {
                    "RequiresConvolve": false
                }
            },
            "provo": {
                "UUID": "{F359CD3B-37E6-4627-B4F6-2DFC2C0E3C1C}",
                "Name": "Skybox",
                "SourceColor": "Linear",
                "DestColor": "Linear",
                "SuppressEngineReduce": true,
                "PixelFormat": "R9G9B9E5",
                "DiscardAlpha": true,
                "MinTextureSize": 256,
                "IsPowerOf2": true,
                "CubemapSettings": {
                    "RequiresConvolve": false
                }
            }
        }
    }
}

File Mask Mapping

We are using file masks (suffix) as the primary way to determinate how to choose the right preset for an image file when processing it. This is to avoid user has to create settings for each texture.

If users don't want to use the system suggested preset for specific image file, they could use Texture Settings Editor to select the preset they want for the texture. The per image setting is saved in an .assetinfo file in the same folder as the image.

The Texture Settings Editor can be accessed via Editor->Asset Browser->(right click an image file) Texture Settings Editor.

Other Information

  • The asset job log for image assets in AssetProcessor window may show some useful information for the image. It includes the preset used for processing the image, the image's output resolution, pixel format, file size, compressor, compression time and etc.
  • User can also use right click menu in Asset Browser to save the processed image file (.streamingimage) to a DDS file which can be viewed by some dds viewers.