TGA I O Functions

DirectXTex

The Targa Truvision (.TGA) format is commonly used as a texture source file format in game development, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.

GetMetadataFromTGAMemory, GetMetadataFromTGAFile

Returns the TexMetadata metadata from a .TGA file.

HRESULT GetMetadataFromTGAMemory( const void* pSource, size_t size,
    TGA_FLAGS flags,
    TexMetadata& metadata );

HRESULT GetMetadataFromTGAFile( const wchar_t* szFile,
    TGA_FLAGS flags,
    TexMetadata& metadata );

For C++17 or later:

HRESULT GetMetadataFromTGAMemory( const std::byte* pSource, size_t size,
    TGA_FLAGS flags,
    TexMetadata& metadata);

LoadFromTGAMemory, LoadFromTGAFile

Loads a .TGA file.

HRESULT LoadFromTGAMemory( const void* pSource, size_t size,
    TGA_FLAGS flags,
    TexMetadata* metadata, ScratchImage& image );

HRESULT LoadFromTGAFile( const wchar_t* szFile,
    TGA_FLAGS flags,
    TexMetadata* metadata, ScratchImage& image );

For C++17 or later:

HRESULT LoadFromTGAMemory( const std::byte* pSource, size_t size,
    TGA_FLAGS flags,
    TexMetadata* metadata, ScratchImage& image );

SaveToTGAMemory, SaveToTGAFile

Saves an image to a .TGA file.

HRESULT SaveToTGAMemory( const Image& image,
    TGA_FLAGS flags,
    Blob& blob,
    const TexMetadata* metadata = nullptr );

HRESULT SaveToTGAFile( const Image& image,
    TGA_FLAGS flags,
    const wchar_t* szFile,
    const TexMetadata* metadata = nullptr );

• R8G8B8A8_UNORM, R8G8B8A8_UNORM_SRGB, B8G8R8A8_UNORM, and B8G8R8A8_UNORM_SRGB data are written as a 32-bit truecolor uncompressed .TGA file

• B8G8R8X8_UNORM and B8G8R8X8_UNORM_SRGB data is written as a 24-bit truecolor uncompressed .TGA file

• B5G5R5A1_UNORM data is written as a 16-bit truecolor uncompressed .TGA file

• R8_UNORM and A8_UNORM data is written as an 8-bit uncompressed greyscale .TGA file

Parameters

For the load functions, the metadata parameter can be nullptr as this information is also available in the returned ScratchImage.

For the save functions, a TGA 2.0 extension footer is written if metadata is non-null. It sets a 2.2 gamma for SRGB formats, and includes the alpha mode.

Support for writing the TGA 2.0 extension footer was added in DirectXTex for October 2019.

TGA_FLAGS was added to DirectXTex for September 2020. Prior to that, these functions didn't take a flags parameter. For code compatibility, the library continues to support the non-flags version which forwards with TGA_FLAGS_NONE.

Returns

These functions will succeed with an S_OK or will return a HRESULT error code (E_INVALIDARG, E_OUTOFMEMORY, E_FAIL, E_POINTER, E_UNEXPECTED, HRESULT_FROM_WIN32(ERROR_INVALID_DATA), HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED), HRESULT_FROM_WIN32(ERROR_HANDLE_EOF), HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW), or in some cases an HRESULT_FROM_WIN32 result from a Win32 function failure).

Exceptions

These functions are marked noexcept, and do not throw C++ exceptions.

Related Flags

• TGA_FLAGS_NONE is the default.

• TGA_FLAGS_BGR indicates you want 24bpp data returned as DXGI_FORMAT_B8G8R8X8_UNORM, and 32bpp returned as DXGI_FORMAT_B8G8R8A8_UNORM which are DXGI 1.1 formats. Normally these are returned as DXGI_FORMAT_R8G8B8A8_UNORM.

• TGA_FLAGS_ALLOW_ALL_ZERO_ALPHA indicates you want any all-zero alpha channel found in a 16bpp or 32bpp TGA left as all zeros. Normally these are converted to opaque (i.e. 255) when returned as an alpha channel by the reader.

Color space

• TGA_FLAGS_IGNORE_SRGB When reading TGA files with TGA 2.0 metadata, if gamma is set to 2.2 or 2.4 the format is returned as _SRGB. Using this flag disables this behavior.

• TGA_FLAGS_DEFAULT_SRGB When reading TGA files with TGA 2.0 metadata, if gamma is not set then the format is returned as 'linear'. Using this flag will assume no gamma metadata indicates a sRGB colorspace instead and will try to return a DXGI_FORMAT_*_SRGB format if available. This flag is ignored if you use TGA_FLAGS_IGNORE_SRGB.

• TGA_FLAGS_FORCE_SRGB When writing a file, the DXGI_FORMAT_*_SRGB formats are used to indicate the need to write with 'sRGB' metadata. If this flag is specified, 'sRGB' metadata with gamma 2.2 is always written even if the input format is not explicitly an DXGI_FORMAT_*_SRGB format.

• TGA_FLAGS_FORCE_LINEAR When writing a file, if the type is not a DXGI_FORMAT_*_SRGB format, then metadata for a gamma of 1.0 is written to indicate the file is in linear color space. If this flag is specified, 1.0 gamma metadata is always written even if the input format is a DXGI_FORMAT_*_SRGB format.

Using the _FORCE_ flags above requires a non-null metadata parameter for the TGA writer functions as they only impact TGA 2.0 metadata

Remarks

• The reader does not support .TGA files that contain color maps (which are rare in practice)
• The reader does not support interleaved files (this feature was deprecated)
• The reader only supports 8-bit greyscale, 16-bit truecolor, 24-bit truecolor, and 32-bit truecolor images
• The writer always creates uncompressed files, although the reader can load RLE compressed files
• The reader only looks for gamma and alpha mode in the TGA 2.0 metadata if present. The writer can optionally write the TGA 2.0 extension area.
• For 16-bit and 32-bit truecolor images, there is a special-case fixup if the entire alpha channel is 0. It is modified to be fully opaque unless you use TGA_FLAGS_ALLOW_ALL_ZERO_ALPHA.

Examples

This is a simple loading example. The TGA format cannot contain complicated multi-image formats, so the TexMetadata info is redundant information.

auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromTGAFile( L"ROCKS.TGA", TGA_FLAGS_NONE, nullptr, *image );
if ( FAILED(hr) )
    // error

A TGA file can only store one 2D image.

const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToTGAFile( *img, TGA_FLAGS_NONE, L"NEW_IMAGE.TGA" );
if ( FAILED(hr) )
    // error

You can also save data directly from memory without using the intermediate ScratchImage at all. This example assumes a single 2D image is being written out.

Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<a DXGI format from the supported list above>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToTGAFile( img, TGA_FLAGS_NONE, L"NEW_IMAGE.TGA" );
if ( FAILED(hr) )
    // error

Windows Store apps

File access and permissions (Windows Runtime apps)

Load

If you wish to load an image from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromTGAFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).

// Using C++/CX (/ZW) and the Parallel Patterns Library (PPL)
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
    if (file)
    {
        auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
        create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
        {
            if ( tempFile )
            {
                HRESULT hr = LoadFromTGAFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });
}

Save

For SaveToTGAFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:

auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base

If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:

auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base

Further reading

2D graphics format web collection