TPL (File Format)
TPL files (Texture Palette Library) are containers for one or more images. They are used in Mario Kart Wii, along with many other games and even the Wii menu. In Mario Kart Wii most TPL files a part of U8 files.
File Format
A TPL file consists of one or more images:
| TPL file header | |
| Image offset table | |
| For each image | Palette header (optional) |
| Palette data (optional) | |
| Image header | |
| Image data | |
The file header starts always at offset 0x00. All other part are linked by offsets. All offsets are relative to the beginning of the file header.
File Header
The file header consists of 12 bytes:
| Offset | Size | Description |
|---|---|---|
| 0x00 | 4 | File identifier, originally the version number. Always 0x00 0x20 0xAF 0x30 |
| 0x04 | 4 | Number of images. In MKW this is always 1 with one exception: savebanner.tpl has 2 images. |
| 0x08 | 4 | Offset of the Image Table, always 0x0c in MKW. 0x1c for TPLx. |
Image Offset Table
The image table contains one pair of values for each image:
| Image | Offset | Size | Description |
|---|---|---|---|
| Image #0 | 0x00 | 4 | Offset of image header. |
| 0x04 | 4 | Offset of palette header or NULL. | |
| Image #1 | 0x08 | 4 | Offset of image header. |
| 0x0c | 4 | Offset of palette header or NULL. | |
| ... | |||
Palette Header
The palette header usually occurs directly after the file header, at the address specified in the image offset table.
| Offset | Size | Description |
|---|---|---|
| 0x00 | 2 | Entry Count |
| 0x02 | 1 | Unpacked |
| 0x03 | 1 | 1 byte of padding |
| 0x04 | 4 | Palette Format |
| 0x08 | 4 | Palette Data Address |
The palette data address is relative to the start of the file. The palette format values are listed below.
| Value | Name |
|---|---|
| 0x00 | IA8 |
| 0x01 | RGB565 |
| 0x02 | RGB5A3 |
Image Header
The image header normally occurs after the palette header and data. The image data usually follows, after padding to the nearest 0x20 bytes.
| Offset | Type | Description |
|---|---|---|
| 0x00 | u16 | Height |
| 0x02 | u16 | Width |
| 0x04 | u32 | Format |
| 0x08 | u32 | Image Data Address |
| 0x0C | u32 | WrapS |
| 0x10 | u32 | WrapT |
| 0x14 | u32 | MinFilter |
| 0x18 | u32 | MagFilter |
| 0x1C | float | LODBias |
| 0x20 | u8 | EdgeLODEnable |
| 0x21 | u8 | MinLOD |
| 0x22 | u8 | MaxLOD |
| 0x23 | u8 | Unpacked |
The image data address is relative to the start of the file. The image format values are listed below.
| ID | Name | Bits per pixel | Block width | Block height | Block size | Type |
|---|---|---|---|---|---|---|
| 0x00 | I4 | 4 | 8 | 8 | 32 bytes | Gray |
| 0x01 | I8 | 8 | 8 | 4 | 32 bytes | Gray |
| 0x02 | IA4 | 8 | 8 | 4 | 32 bytes | Gray + Alpha |
| 0x03 | IA8 | 16 | 4 | 4 | 32 bytes | Gray + Alpha |
| 0x04 | RGB565 | 16 | 4 | 4 | 32 bytes | Color |
| 0x05 | RGB5A3 | 16 | 4 | 4 | 32 bytes | Color + Alpha |
| 0x06 | RGBA32 (RGBA8) | 32 | 4 | 4 | 64 bytes | Color + Alpha |
| 0x08 | C4 (CI4) | 4 | 8 | 8 | 32 bytes | Palette (IA8, RGB565, RGB5A3) |
| 0x09 | C8 (CI8) | 8 | 8 | 4 | 32 bytes | Palette (IA8, RGB565, RGB5A3) |
| 0x0A | C14X2 (CI14x2) | 16 | 4 | 4 | 32 bytes | Palette (IA8, RGB565, RGB5A3) |
| 0x0E | CMPR | 4 | 8 | 8 | 32 bytes | Color + optional Alpha (compressed) |
Image
The image data itself is encoded using the same implementations of each of the formats as TEX0 files. Detailed explanation of each format is given on the Image Formats page.
TPLx (Extended TPL)
.png){kind=logo}
TPLx is an extension of TPL that is fully compatible with TPL. It was developed by Wiimm to manage particularly high images with a height of 65536 or more pixels. Such images are required for LE-CODE cup icons. TPLx claims that the image has other dimensions. For example, instead of 128x80000, the values 256x40000 are entered in the image header. The original size is then saved in the extended header. So it can be read with the correct dimensions. The extended header is placed directly behind the file header at file offset 0x0c. The image data is not changed.
This format can be used by all LE-CODE versions to support any number of cup icons with any size.
| Offset | Size | Description |
|---|---|---|
| 0x00 | 4 | File identifier, always "TPLx" (0x54504c78). |
| 0x04 | 4 | Width of the original image. |
| 0x08 | 4 | Height of the original image. |
| 0x0c | 4 | Number of icons. |
Special Signature
TPLx expands the image by up to 8 pixel lines, resulting in at least 32 bytes of additional memory at the end. A signature is stored in these 32 bytes, which contains, among other things, the width and height of the original icons. Mario Kart Wii ignores the extended TPL header. LE-CODE can therefore be informed about the metrics with this signature. If the signature exists and is valid, then LE-CODE uses the width from the signature and ignores the LPAR setting CUP-ICON-SIZE.
The structure of the optional signature:
| Offset | Size | Description |
|---|---|---|
| 0x00 | 8 | First identifier to check validity. Always LE-CODE\0 (0x4c452d43 0x4f444500). |
| 0x08 | 4 | Width of the original image. |
| 0x0c | 4 | Height of the original image. |
| 0x10 | 4 | Number of icons. |
| 0x14 | 2 | Image format. |
| 0x16 | 2 | Palette format. |
| 0x18 | 8 | Second identifier to check validity. Always Cup Icon (0x43757020 0x49636f6e). |
Tools
The following tools can handle TPL files:
- BrawlBox, by Kryal and BlackJax96
- CTools Pack, by Chadderz
- SZS Modifier, by Chadderz
- Wiimms SZS Tools, by Wiimm: can convert BREFT, BTI, TEX0, TPL, TPLx and PNG images in any directions. It may also convert the image and palette formats.
- Wexos's Toolbox, by Wexos