Format:TPL texture palette
| Platforms | Platform:Nintendo GameCube, Platform:Nintendo Wii |
|---|---|
| Magic | 00 20 AF 30 (version number, no text magic) |
| Extensions | .tpl |
| Endianness | big |
| On this wiki | Facts · Code · Notes · Topics |
Texture palette of GameCube and Wii games (.tpl): a header with version number 0x0020AF30 (2142000), a descriptor count and an offset to an array of descriptors, each pointing to an image header (size, GX texture format, wrap and filter modes, data offset) and an optional palette header; the SDK's TPLBind turns the stored offsets into pointers.
Overview
The TPL file is a memory image meant to be loaded whole and fixed up in place. The layout below is read from the matching decompilation of the Wii SDK's TPL library in zeldaret/tp (CC0-1.0) at commit c8fa8c9e2a: libs/revolution/include/revolution/tpl.h and libs/revolution/src/tpl/TPL.c. The GameCube SDK has the same structures under the names TEXPalette and TEXDescriptor (libs/dolphin/include/dolphin/charPipeline/texPalette.h).
Header
TPLPalette (tpl.h lines 39-43), big endian: u32 versionNumber, u32 numDescriptors, u32 descriptorArray (a file offset on disk, a pointer after binding). TPLBind panics with "invalid version number for texture palette" unless versionNumber is 2142000, i.e. 0x0020AF30, so the first four bytes 00 20 AF 30 identify the format (TPL.c lines 4-9).
Descriptors and headers
- TPLDescriptor (8 bytes): u32 textureHeader and u32 CLUTHeader, both offsets from the file start, 0 when absent (tpl.h lines 34-37).
- TPLHeader (0x24 bytes): u16 height, u16 width, u32 format (a GX texture format, see below), u32 data (image offset), u32 wrapS, u32 wrapT, u32 minFilter, u32 magFilter, f32 LODBias, u8 edgeLODEnable, u8 minLOD, u8 maxLOD, u8 unpacked (tpl.h lines 18-32). Height comes before width.
- TPLClutHeader (12 bytes): u16 numEntries, u8 unpacked, 1 byte padding, u32 format (GX TLUT format), u32 data (palette offset) (tpl.h lines 10-16).
- The unpacked byte is 0 on disk. TPLBind adds the palette's base address to textureHeader, CLUTHeader and each data offset and sets unpacked to 1, so binding twice does not shift the offsets twice (TPL.c lines 11-31).
- TPLGet takes the index modulo numDescriptors (TPL.c lines 34-37).
Enums used by the headers
Source: libs/revolution/include/revolution/gx/GXEnum.h.
- Wrap mode: 0 GX_CLAMP, 1 GX_REPEAT, 2 GX_MIRROR (lines 164-169).
- Filter: 0 GX_NEAR, 1 GX_LINEAR, 2 GX_NEAR_MIP_NEAR, 3 GX_LIN_MIP_NEAR, 4 GX_NEAR_MIP_LIN, 5 GX_LIN_MIP_LIN (lines 171-178).
- Texture format: 0 I4, 1 I8, 2 IA4, 3 IA8, 4 RGB565, 5 RGB5A3, 6 RGBA8, 8 C4, 9 C8, 0xA C14X2, 0xE CMPR (S3TC-like 4x4 blocks) (lines 126-133, 159-161).
- TLUT format: 0 IA8, 1 RGB565, 2 RGB5A3 (lines 872-877).
Pixel data is stored in GX tiles (for example 8x8 for the 16-bit formats and 4x4 blocks for CMPR). Tile sizes, bits per texel and the RGBA8 and CMPR layouts, read from Dolphin's TextureDecoder and noclip's gx_texture.ts, are on Format:GX texture formats (GameCube and Wii). The BTI header of JSystem is a close relative: Format:BTI texture (JSystem).
Related
Platform:Nintendo GameCube, Platform:Nintendo Wii, Library:Dolphin SDK.
Code & repositories
- https://github.com/zeldaret/tp @
c8fa8c9e2aab72cf4e5db0e5d1c84a9ea6ee6eb0· license: CC0-1.0 (declared by the contributor; GitHub's detector did not recognize LICENSE.md)
libs/revolution/include/revolution/tpl.h, src/tpl/TPL.c and gx/GXEnum.h: matching decompilation of the Wii SDK TPL library, showing the structures and the version check
Tested on: source read, not run: source read at c8fa8c9e2a, not run · checked 2026-10-19