Difference between revisions of "GTX\GSH (File Format)"
Jump to navigation
Jump to search
Aboood40091 (talk | contribs) m (→Block types) |
Aboood40091 (talk | contribs) |
||
(30 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | + | '''GTX''' and '''GSH''' files are used in various [[Wii U]] games, including [[Mario Kart 8]]. GSH stands for '''G'''X2 '''SH'''ader and GTX stands for '''G'''X2 '''T'''e'''X'''ture'''. | |
− | == Header | + | == Header == |
+ | Every GTX/GSH file begins with an 0x20 byte '''Gfx2''' header. | ||
− | |||
{| class="wikitable" | {| class="wikitable" | ||
! Offset | ! Offset | ||
Line 15: | Line 15: | ||
| 0x04 | | 0x04 | ||
| 4 | | 4 | ||
− | | '''Size of header in bytes'''. Must | + | | '''Size of header in bytes'''. Must be 0x20 bytes long, or header (and hence file) is unreadable. |
|- | |- | ||
| 0x08 | | 0x08 | ||
| 4 | | 4 | ||
− | | '''Major version number''' | + | | '''Major version number'''. |
|- | |- | ||
| 0x0C | | 0x0C | ||
| 4 | | 4 | ||
− | | '''Minor version number''' | + | | '''Minor version number'''. |
|- | |- | ||
| 0x10 | | 0x10 | ||
Line 35: | Line 35: | ||
| 0x18 | | 0x18 | ||
| 4 | | 4 | ||
− | | ''' | + | | '''Reserved''', Always 0x00. |
|- | |- | ||
| 0x1C | | 0x1C | ||
| 4 | | 4 | ||
− | | ''' | + | | '''Reserved''', Always 0x00. |
|- | |- | ||
| 0x20 | | 0x20 | ||
Line 45: | Line 45: | ||
|} | |} | ||
− | == Blocks == | + | == Data Blocks == |
− | + | After the header comes some data blocks, data blocks contain a 0x20 byte '''BLK{''' block header followed by data specified by the block type. | |
− | After the header comes some blocks, blocks contain a 0x20 byte '''BLK{''' header followed by data specified by the block type. | ||
=== Block Header === | === Block Header === | ||
Line 63: | Line 62: | ||
| 4 | | 4 | ||
| '''Size of block header in bytes'''. | | '''Size of block header in bytes'''. | ||
− | |- | + | |- bgcolor="#AAFFAA" |
+ | | colspan="4" align="center" | '''if Gfx2 version = 6.x''' | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x08 | ||
+ | | 4 | ||
+ | | '''Major version number'''. Must be 0x00 or header is unreadable. | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0C | ||
+ | | 4 | ||
+ | | '''Minor version number'''. Must be 0x01. | ||
+ | |- bgcolor="#FFAAAA" | ||
+ | | colspan="4" align="center" | '''if Gfx2 version = 7.x''' | ||
+ | |- bgcolor="#FFDDDD" | ||
| 0x08 | | 0x08 | ||
| 4 | | 4 | ||
− | | '''Major version number'''. Must | + | | '''Major version number'''. Must be 0x01 or header is unreadable. |
− | |- | + | |- bgcolor="#FFDDDD" |
| 0x0C | | 0x0C | ||
| 4 | | 4 | ||
− | | '''Minor version number'''. | + | | '''Minor version number'''. Must be 0x00. |
|- | |- | ||
| 0x10 | | 0x10 | ||
Line 90: | Line 101: | ||
=== Block types === | === Block types === | ||
− | |||
− | |||
{| class="wikitable" | {| class="wikitable" | ||
Line 98: | Line 107: | ||
|- | |- | ||
| 0x00 | | 0x00 | ||
− | | Not actually a valid Block type. | + | | Not actually a valid Block type. |
|- | |- | ||
| 0x01 | | 0x01 | ||
− | | Follows this block header the | + | | Follows this block header the end of the file. |
|- | |- | ||
| 0x02 | | 0x02 | ||
Line 107: | Line 116: | ||
|- | |- | ||
| 0x03 | | 0x03 | ||
− | | Follows this block header Vertex shader | + | | Follows this block header Vertex shader header. |
|- | |- | ||
| 0x05 | | 0x05 | ||
Line 113: | Line 122: | ||
|- | |- | ||
| 0x06 | | 0x06 | ||
− | | Follows this block header Pixel shader | + | | Follows this block header Pixel shader header. |
|- | |- | ||
| 0x07 | | 0x07 | ||
| Follows this block header Pixel shader program. | | Follows this block header Pixel shader program. | ||
|- | |- | ||
+ | | 0x08 | ||
+ | | Follows this block header Geometry shader header. | ||
+ | |- | ||
+ | | 0x09 | ||
+ | | Follows this block header Geometry shader program. | ||
+ | |- bgcolor="#AAFFAA" | ||
+ | | colspan="4" align="center" | '''if Gfx2 version = 6.x''' | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0A | ||
+ | | Follows this block header the GX2 Surface. | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0B | ||
+ | | Follows this block header the swizzled image data. | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0C | ||
+ | | Follows this block header the swizzled mipmaps data. | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0D | ||
+ | | Follows this block header Geometry copy shader program. | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0E | ||
+ | | Reserved block. | ||
+ | |- bgcolor="#DDFFDD" | ||
+ | | 0x0F | ||
+ | | Reserved block. | ||
+ | |- bgcolor="#FFAAAA" | ||
+ | | colspan="4" align="center" | '''if Gfx2 version = 7.x''' | ||
+ | |- bgcolor="#FFDDDD" | ||
+ | | 0x0A | ||
+ | | Same as 0x09? (Duplicate?) | ||
+ | |- bgcolor="#FFDDDD" | ||
| 0x0B | | 0x0B | ||
− | | Follows this block header the | + | | Follows this block header the GX2 Surface. |
− | |- | + | |- bgcolor="#FFDDDD" |
| 0x0C | | 0x0C | ||
− | | Follows this block header the | + | | Follows this block header the swizzled image data. |
+ | |- bgcolor="#FFDDDD" | ||
+ | | 0x0D | ||
+ | | Follows this block header the swizzled mipmaps data. | ||
+ | |- bgcolor="#FFDDDD" | ||
+ | | 0x0E | ||
+ | | Follows this block header Compute shader header. | ||
+ | |- bgcolor="#FFDDDD" | ||
+ | | 0x0F | ||
+ | | Follows this block header Compute shader program. | ||
|- | |- | ||
− | | | + | | 0x10 |
− | | | + | | Treated like a 0x02 block, users can do what they want with this block. |
|} | |} | ||
− | === | + | === GX2 Surface === |
− | + | The GX2 Surface has an exact size of 0x9C: | |
− | The | ||
{| class="wikitable" | {| class="wikitable" | ||
− | ! Offset | + | ! Offset !! Size !! Type !! Description |
− | ! Size | + | |- |
− | ! Description | + | | 0x00 || 4 || UInt32 || '''Dimension'''. Maps to '''GX2SurfaceDim''' (line 849 [http://pastebin.com/DCrP1w9x here]). Indicates the "shape" of a given surface or texture. |
+ | |- | ||
+ | | 0x04 || 4 || UInt32 || '''Texture width'''. Width of the texture in pixels. | ||
+ | |- | ||
+ | | 0x08 || 4 || UInt32 || '''Texture height'''. Height of the texture in pixels. | ||
+ | |- | ||
+ | | 0x0C || 4 || UInt32 || '''Texture depth'''. | ||
+ | |- | ||
+ | | 0x10 || 4 || UInt32 || '''Number of mipmaps'''. | ||
+ | |- | ||
+ | | 0x14 || 4 || UInt32 || '''Texture format'''. Maps to '''GX2SurfaceFormat''' (line 589 [http://pastebin.com/DCrP1w9x here] for explanation and format values). | ||
+ | |- | ||
+ | | 0x18 || 4 || UInt32 || '''AA mode'''. Maps to '''GX2AAMode''' (line 865 [http://pastebin.com/DCrP1w9x here]). Indicates the AA mode (number of samples) for the surface. | ||
+ | |- | ||
+ | | 0x1C || 4 || UInt32 || '''Usage'''. Maps to '''GX2SurfaceUse''' (line 823 [http://pastebin.com/DCrP1w9x here]). Indicates how the given surface may be used. | ||
+ | |- | ||
+ | | 0x20 || 4 || UInt32 || '''Data length'''. Length of texture data in bytes. | ||
+ | |- | ||
+ | | 0x24 || 4 || UInt32 || '''Data pointer'''. Set at runtime. | ||
+ | |- | ||
+ | | 0x28 || 4 || UInt32 || '''Mipmaps data length'''. Length of mipmaps data in bytes. | ||
+ | |- | ||
+ | | 0x2C || 4 || UInt32 || '''Mipmaps pointer'''. Set at runtime. | ||
|- | |- | ||
− | | | + | | 0x30 || 4 || UInt32 || '''Tile mode'''. Maps to '''GX2TileMode''' (line 795 [http://pastebin.com/DCrP1w9x here]). Indicates the desired tiling mode for the surface. |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x34 || 4 || UInt32 || '''Swizzle value'''. |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x38 || 4 || UInt32 || '''Alignment'''. Always 512 * bytes per pixel. |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x3C || 4 || UInt32 || '''Pitch'''. |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x40 || 0x34 || UInt32[13] || '''Mipmap offsets'''. An array of 13 offsets for each mipmap, relative to the start of the mipmap data. |
− | | | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x74 || 4 || UInt32 || '''First mipmap ID'''. (Usually 0, the main map/image) |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x78 || 4 || UInt32 || '''Number of available mipmaps'''. ("Number of mipmaps" - "First mipmap ID") |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x7C || 4 || UInt32 || '''First slice ID'''. (Usually 0) |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x80 || 4 || UInt32 || '''Number of available slices'''. ("Depth" - "First slice ID") |
− | | 4 | ||
− | | ''' | ||
|- | |- | ||
− | | | + | | 0x84 || 4 || Byte[4] || '''Component Selector''', determines which texture color channels are used for each target channel. The bytes map to the Red, Green, Blue and Alpha channel and can receive one of the following channels. |
− | | 4 | + | {| class="wikitable" |
− | | ''' | + | ! Value !! Name !! Description |
|- | |- | ||
− | | | + | | 0 || R || The channel will receive the red values of the texture. |
− | | | ||
− | | | ||
|- | |- | ||
− | | | + | | 1 || G || The channel will receive the green values of the texture. |
− | | | ||
− | | | ||
|- | |- | ||
− | | | + | | 2 || B || The channel will receive the blue values of the texture. |
− | | | ||
− | | | ||
|- | |- | ||
− | | | + | | 3 || A || The channel will receive the alpha values of the texture. |
− | | | ||
− | | | ||
|- | |- | ||
− | | | + | | 4 || 0 || The channel will always have a value 0. |
− | | | ||
− | | | ||
|- | |- | ||
− | | | + | | 5 || 1 || The channel will always have a value 1. |
− | | | + | |} |
− | | | ||
|- | |- | ||
− | | | + | | 0x88 || 0x14 || UInt32[5] || '''Texture registers'''. 5 registers used to describe the texture. |
− | | | ||
− | | | ||
|} | |} | ||
− | == | + | == Swizzling == |
− | + | [https://pastebin.com/VDvs7q8Y This] code can swizzle image and mipmap data. Call ''swizzle()'' by giving it the width, height, format (in hex), tileMode, swizzle value, pitch and the swizzled data. If you're swizzling then set do_swizzle to ''True''. If you're deswizzling then set do_swizzle to ''False''. | |
− | ''' | ||
= Tools = | = Tools = | ||
− | + | The following tools can handle GTX/GSH files: | |
− | The following | ||
− | |||
* [https://github.com/aboood40091/GTX-Extractor GTX Extractor], by [[User:Aboood40091|AboodXD]] | * [https://github.com/aboood40091/GTX-Extractor GTX Extractor], by [[User:Aboood40091|AboodXD]] | ||
[[Category:File Format]] | [[Category:File Format]] |
Revision as of 09:25, 16 June 2018
GTX and GSH files are used in various Wii U games, including Mario Kart 8. GSH stands for GX2 SHader and GTX stands for GX2 TeXture.
Header
Every GTX/GSH file begins with an 0x20 byte Gfx2 header.
Offset | Size | Description |
---|---|---|
0x00 | 4 | "Gfx2" File identifier, ASCII string. |
0x04 | 4 | Size of header in bytes. Must be 0x20 bytes long, or header (and hence file) is unreadable. |
0x08 | 4 | Major version number. |
0x0C | 4 | Minor version number. |
0x10 | 4 | GPU version for which this file is designed for. |
0x14 | 4 | Align mode. |
0x18 | 4 | Reserved, Always 0x00. |
0x1C | 4 | Reserved, Always 0x00. |
0x20 | End of Gfx2 header. |
Data Blocks
After the header comes some data blocks, data blocks contain a 0x20 byte BLK{ block header followed by data specified by the block type.
Block Header
Offset | Size | Description | |
---|---|---|---|
0x00 | 4 | "BLK{" Header of the block, ASCII string. | |
0x04 | 4 | Size of block header in bytes. | |
if Gfx2 version = 6.x | |||
0x08 | 4 | Major version number. Must be 0x00 or header is unreadable. | |
0x0C | 4 | Minor version number. Must be 0x01. | |
if Gfx2 version = 7.x | |||
0x08 | 4 | Major version number. Must be 0x01 or header is unreadable. | |
0x0C | 4 | Minor version number. Must be 0x00. | |
0x10 | 4 | Block type, it determines the type of the following data. | |
0x14 | 4 | Size of the following data. In bytes, always 0x9C if the block type is 0x0B. | |
0x18 | 4 | A unique identifier for this block, allowing it to be referenced by other blocks | |
0x1C | 4 | An incrementing index for each instance of a given type. |
Block types
Type | Description | ||
---|---|---|---|
0x00 | Not actually a valid Block type. | ||
0x01 | Follows this block header the end of the file. | ||
0x02 | Follows this block header padding. (Used to align following data) | ||
0x03 | Follows this block header Vertex shader header. | ||
0x05 | Follows this block header Vertex shader program. | ||
0x06 | Follows this block header Pixel shader header. | ||
0x07 | Follows this block header Pixel shader program. | ||
0x08 | Follows this block header Geometry shader header. | ||
0x09 | Follows this block header Geometry shader program. | ||
if Gfx2 version = 6.x | |||
0x0A | Follows this block header the GX2 Surface. | ||
0x0B | Follows this block header the swizzled image data. | ||
0x0C | Follows this block header the swizzled mipmaps data. | ||
0x0D | Follows this block header Geometry copy shader program. | ||
0x0E | Reserved block. | ||
0x0F | Reserved block. | ||
if Gfx2 version = 7.x | |||
0x0A | Same as 0x09? (Duplicate?) | ||
0x0B | Follows this block header the GX2 Surface. | ||
0x0C | Follows this block header the swizzled image data. | ||
0x0D | Follows this block header the swizzled mipmaps data. | ||
0x0E | Follows this block header Compute shader header. | ||
0x0F | Follows this block header Compute shader program. | ||
0x10 | Treated like a 0x02 block, users can do what they want with this block. |
GX2 Surface
The GX2 Surface has an exact size of 0x9C:
Offset | Size | Type | Description | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0x00 | 4 | UInt32 | Dimension. Maps to GX2SurfaceDim (line 849 here). Indicates the "shape" of a given surface or texture. | |||||||||||||||||||||
0x04 | 4 | UInt32 | Texture width. Width of the texture in pixels. | |||||||||||||||||||||
0x08 | 4 | UInt32 | Texture height. Height of the texture in pixels. | |||||||||||||||||||||
0x0C | 4 | UInt32 | Texture depth. | |||||||||||||||||||||
0x10 | 4 | UInt32 | Number of mipmaps. | |||||||||||||||||||||
0x14 | 4 | UInt32 | Texture format. Maps to GX2SurfaceFormat (line 589 here for explanation and format values). | |||||||||||||||||||||
0x18 | 4 | UInt32 | AA mode. Maps to GX2AAMode (line 865 here). Indicates the AA mode (number of samples) for the surface. | |||||||||||||||||||||
0x1C | 4 | UInt32 | Usage. Maps to GX2SurfaceUse (line 823 here). Indicates how the given surface may be used. | |||||||||||||||||||||
0x20 | 4 | UInt32 | Data length. Length of texture data in bytes. | |||||||||||||||||||||
0x24 | 4 | UInt32 | Data pointer. Set at runtime. | |||||||||||||||||||||
0x28 | 4 | UInt32 | Mipmaps data length. Length of mipmaps data in bytes. | |||||||||||||||||||||
0x2C | 4 | UInt32 | Mipmaps pointer. Set at runtime. | |||||||||||||||||||||
0x30 | 4 | UInt32 | Tile mode. Maps to GX2TileMode (line 795 here). Indicates the desired tiling mode for the surface. | |||||||||||||||||||||
0x34 | 4 | UInt32 | Swizzle value. | |||||||||||||||||||||
0x38 | 4 | UInt32 | Alignment. Always 512 * bytes per pixel. | |||||||||||||||||||||
0x3C | 4 | UInt32 | Pitch. | |||||||||||||||||||||
0x40 | 0x34 | UInt32[13] | Mipmap offsets. An array of 13 offsets for each mipmap, relative to the start of the mipmap data. | |||||||||||||||||||||
0x74 | 4 | UInt32 | First mipmap ID. (Usually 0, the main map/image) | |||||||||||||||||||||
0x78 | 4 | UInt32 | Number of available mipmaps. ("Number of mipmaps" - "First mipmap ID") | |||||||||||||||||||||
0x7C | 4 | UInt32 | First slice ID. (Usually 0) | |||||||||||||||||||||
0x80 | 4 | UInt32 | Number of available slices. ("Depth" - "First slice ID") | |||||||||||||||||||||
0x84 | 4 | Byte[4] | Component Selector, determines which texture color channels are used for each target channel. The bytes map to the Red, Green, Blue and Alpha channel and can receive one of the following channels.
| |||||||||||||||||||||
0x88 | 0x14 | UInt32[5] | Texture registers. 5 registers used to describe the texture. |
Swizzling
This code can swizzle image and mipmap data. Call swizzle() by giving it the width, height, format (in hex), tileMode, swizzle value, pitch and the swizzled data. If you're swizzling then set do_swizzle to True. If you're deswizzling then set do_swizzle to False.
Tools
The following tools can handle GTX/GSH files:
- GTX Extractor, by AboodXD