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 );
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 );
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
, andB8G8R8A8_UNORM_SRGB
data are written as a 32-bit truecolor uncompressed.TGA
file -
B8G8R8X8_UNORM
andB8G8R8X8_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
andA8_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 aflags
parameter. For code compatibility, the library continues to support the non-flags version which forwards withTGA_FLAGS_NONE
.
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
Related Flags
-
TGA_FLAGS_NONE
is the default. -
TGA_FLAGS_BGR
indicates you want 24bpp data returned asDXGI_FORMAT_B8G8R8X8_UNORM
, and 32bpp returned asDXGI_FORMAT_B8G8R8A8_UNORM
which are DXGI 1.1 formats. Normally these are returned asDXGI_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 aDXGI_FORMAT_*_SRGB
format if available. This flag is ignored if you useTGA_FLAGS_IGNORE_SRGB
. -
TGA_FLAGS_FORCE_SRGB
When writing a file, theDXGI_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 anDXGI_FORMAT_*_SRGB
format. -
TGA_FLAGS_FORCE_LINEAR
When writing a file, if the type is not aDXGI_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 aDXGI_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
Implementation Notes
- 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
.
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
For Use
- Universal Windows Platform apps
- Windows desktop apps
- Windows 11
- Windows 10
- Windows 8.1
- Windows 7 Service Pack 1
- Xbox One
- Xbox Series X|S
- Windows Subsystem for Linux
Architecture
- x86
- x64
- ARM64
For Development
- Visual Studio 2022
- Visual Studio 2019 (16.11)
- clang/LLVM v12 - v18
- GCC 10.5, 11.4, 12.3
- MinGW 12.2, 13.2
- CMake 3.20
Related Projects
DirectX Tool Kit for DirectX 11
DirectX Tool Kit for DirectX 12
Tools
See also
All content and source code for this package are subject to the terms of the MIT License.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.