CMDL (Donkey Kong Country Returns) and TXTR (Metroid Prime): Difference between pages

From Retro Modding Wiki
(Difference between pages)
Jump to navigation Jump to search
>Aruki
mNo edit summary
 
>Aruki
No edit summary
 
Line 1: Line 1:
''See [[CMDL (File Format)]] for the other revisions of this format.''
'''TXTR''' is, as the name suggests, the Retro Studios texture format. The format remains completely unchanged from Metroid Prime all the way up to Donkey Kong Country Returns.
 
The '''CMDL format''' is DKCR's model format. It's similar to the CMDL format found in the Metroid Prime trilogy, but with a lot of additions and changes, and some layout changes.
 
{{research|moderate|Where to begin? Materials need a lot of research (they're very similar if not the same as Metroid Prime 3). A lot of the visibility group data is unknown. The submesh headers contain a lot of unknowns, and the possible vertex format settings are unknown. Geometry should be split off into a separate article if it's confirmed that it's the same format that's used in MREA (which is fairly likely). Materials should also be split off once more is known about them.}}


__TOC__
__TOC__
Line 9: Line 5:
== Format ==
== Format ==


Like the previous CMDL formats, DKCR CMDL files are split up into a number of 32-byte aligned ''sections''. Every section both starts and ends on a 32-byte boundary. These are used to separate different parts of the file; different types of sections typically indicate different sets of data. The header declares the section count and the size of each one; using these is the only way to navigate the file.
TXTR files contain a very short 12-byte header, followed by the image data.


=== Header ===
=== Header ===
Line 15: Line 11:
{| class="wikitable"
{| class="wikitable"
! Offset
! Offset
! Type
! Size
! Size
! Description
! Description
|-
|-
| 0x0
| 0x0
| u32
| 4
| 4
| {{unknown|'''Unknown'''; always 0x9381000A - likely either magic value or 16-bit magic/version}}
| '''Image format'''. Possible values range from 0x0 to 0xA; see below for more details.
|-
|-
| 0x4
| 0x4
| u32
| 2
| 4
| '''Width'''
| '''Flags'''; see blow
|-
| 0x8
| float[6]
| 0x18
| '''Model Bounding Box'''
|-
| 0x20
| u32
| 4
| '''Section count''' (SC)
|-
| 0x24
| u32
| 4
| '''Material set count'''
|-
| 0x28
| -
| -
| '''Visibility group data'''; present if flag 0x10 is set. See below for structure.
|-
| -
| u32[]
| 4 × SC
| '''Section sizes'''
|-
| colspan=4 {{unknown|End of header; pad to multiple of 32 before first section starts}}
|}
 
==== Flags ====
 
The following flags are possible:
 
{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| {{unknown|Unknown}}
|-
| 1
| 0x2
| {{unknown|Unknown}}
|-
|-
| 0x6
| 2
| 2
| 0x4
| '''Height'''
| {{unknown|Unknown}}
|-
|-
| 3
| 0x8
| 0x8
| {{unknown|Unknown}}
|-
| 4
| 4
| 0x10
| '''Mipmap count'''
| Enable visibility groups
|-
|-
| 5
| 0xC
| 0x20
| colspan=2 | End of header
| Store vertex positions as shorts
|}
|}


==== Visibility Groups ====
=== Palettes ===


This data chunk is present in the header if bit 0x10 is set, after the material set count and before the section sizes.
The C4 and C8 image formats contain a palette table after the header, before the image data begins.


{| class="wikitable"
{| class="wikitable"
! Offset
! Offset
! Type
! Size
! Size
! Description
! Description
|-
|-
| 0x0
| 0x0
| u32
| 4
| 4
| {{unknown|'''Unknown'''}}
| '''Palette format'''. Possible values range from 0 to 2.
|-
|-
| 0x4
| 0x4
| u32
| 2
| 4
| Always 0x1 in C4, 0x100 in C8
| '''Visibility Group count'''
|}
 
The following structure repeats for each group:
 
{| class="wikitable"
! Offset
! Type
! Size
! Description
|-
|-
| 0x0
| 0x6
| u32
| 2
| 4
| Always 0x10 in C4, 0x1 in C8
| '''Name length'''
|-
| 0x4
| string
| -
| '''Visibility Group name'''
|}
 
Finally, it ends with this before the sizes begin:
 
{| class="wikitable"
! Offset
! Type
! Size
! Description
|-
| 0x0
| u32
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x4
| u32
| 4
| {{unknown|'''Unknown'''}}
|-
|-
| 0x8
| 0x8
| u32
| Varies
| 4
| '''Palette colors'''. 16-bit color values; 16 colors in C4, 256 in C8.
| {{unknown|'''Unknown'''}}
|-
|-
| 0xC
| colspan=3 | End of palette table; image data begins immediately after
| u32
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x10
| u32
| 4
| {{unknown|'''Unknown'''}}
|}
|}


=== Materials ===
== Image Formats ==
 
There's not much known about the material format currently; DKCR seems to use the same material format as Metroid Prime 3. The main difference in DKCR compared to Prime 3 is that in Prime 3, each material set would get its own section. In DKCR, every material set is in the same section. Each material set begins with a material count, and each material begins with its own size. The main thing that's needed to read geometry is the vertex attribute flags, which are located at 0xC in the material structure (not counting the size).
 
=== Geometry ===
 
==== Vertex Coordinates ====
 
Vertex coords can be stored as either floats or signed shorts, depending whether flag 0x20 is set in the header. If they're shorts, then they need to be divided by 0x2000 to get the corresponding float value. Since they're signed numbers, that means that 0 to 0x7FFF correspond to the range 0.0-4.0, and 0x8000 to 0xFFFF correspond to the range -4.0-0.0.
 
==== Normals ====
 
Vertex normals are usually stored as shorts.
 
==== Vertex Color ====


Normally unused, so this section is typically empty and zeroed out.
There are 11 different image formats; these are built directly into GX, so they remain the same across all GameCube and Wii games. Rather than storing pixels in a linear left-to-right order, GX textures encode pixels in large blocks. The size of the block varies depending on the image format.


==== Float UV Coordinates ====
For example, suppose you have a format that stores 4x4 blocks. Pixels 1-4 of the image will make up the first row of the first block; pixels 5-8 will make up the second row; 9-12 will make up the third row; 13-16 will make up the fourth row, completing the block; and the 17-20 will begin the first row of the second block, appearing directly to the right of the first row of the first block.
 
These are stored as a sequence of two floats.
 
==== Short UV Coordinates ====
 
Like the short vertex coordinates, these are stored as signed shorts that should be divided by 0x2000 to get the corresponding float value. The short UVs section has received a fairly significant increase in usage in DKCR compared to the Prime series; in the Prime games, they were generally only used for lightmaps, whereas in DKCR they're often used by pretty much anything.
 
==== Submesh Definitions ====
 
This section is very small and simple; it simply declares a submesh count and then lists the offsets to the end of each submesh. Following this section, there'll be one additional section per submesh.


{| class="wikitable"
{| class="wikitable"
! Offset
! ID
! Type
! Name
! Size
! Bits per pixel
! Block size
! Description
! Description
|-
|-
| 0x0
| 0x0
| u32
| I4
| 4
| 4
| '''Submesh count''' (SC)
| 8x8
| 4-bit greyscale intensity values. Two pixels per byte.
|-
|-
| 0x4
| 0x1
| u32[]
| I8
| 4 × SC
| 8
| '''Submesh offsets''' (relative to the start of the first submesh)
| 8x4
| 8-bit greyscale intensity values.
|-
|-
| colspan=4 {{unknown|Submesh sections begin}}
| 0x2
|}
| IA4
 
| 8
==== Submesh ====
| 8x4
 
| 4-bit greyscale intensity values with an additional 4-bit alpha channel.
There will be one of these sections per submesh. Each submesh starts with a small 0x20-byte header; after that, the primitive data begins.
 
{| class="wikitable"
! Offset
! Type
! Size
! Description
|-
|-
| 0x0
| 0x3
| float[3]
| IA8
| 0xC
| 16
| '''Position''' (or pivot location); unknown purpose
| 4x4
| 8-bit greyscale intensity values with an additional 8-bit alpha channel.
|-
|-
| 0xC
| 0x4
| u16
| C4
| 4
| '''Mantissa'''  - always 0x8000
|-
| 0xE
| u16
| 2
| '''Primitive table size''' (''this value may not be reliable'')
|-
| 0x10
| u32
| 4
| 4
| {{unknown|'''Unknown'''; always 0?}}
| 8x8
| 4-bit palette indices.
|-
|-
| 0x14
| 0x5
| u32
| C8
| 4
| 8
| {{unknown|'''Unknown'''; always 0?}}
| 8x4
| 8-bit palette indices.
|-
|-
| 0x18
| 0x6
| u16
| C14x2
| 2
| 16
| {{unknown|'''Unknown'''; value varies, but is sometimes 0xFFFF
| 4x4
| Another palette format. Not used by any official textures.
|-
|-
| 0x1A
| 0x7
| u16
| RGB565
| 2
| 16
| '''Material ID'''
| 4x4
| 16-bit colors without alpha.
|-
|-
| 0x1C
| 0x8
| u8
| RGB5A3
| 1
| 16
| {{unknown|'''Unknown'''; always 0xFF?}}
| 4x4
| 16-bit colors with alpha.
|-
|-
| 0x1D
| 0x9
| u8
| RGBA8
| 1
| 32
| '''Visibility Group index'''
| 4x4
| Uncompressed 32-bit colors with alpha.
|-
|-
| 0x1E
| 0xA
| u16
| CMPR
| 2
| 4
| '''UV array flag'''; 0 indicates this submesh uses float UVs, 1 indicates it uses short UVs
| 8x8
|-
| DXT1-compressed textures.
| 0x20
| colspan=3 {{unknown|End of header; primitive data starts}}
|}
|}


The primitive data is a standard GX display list. Each primitive begins with a byte that contains the primitive type in the upper 5 bits, and the vertex format setting in the lower 3. After that is a 16-bit vertex count, followed by a series of 16-bit vertex attribute indices.
== External links ==
 
You'll need to check some settings on the material to read the primitive data properly; the material determines which vertex attributes are present.


There is no primitive count value; you'll need to continue reading data until you hit the end of the primitive table. There are a couple values you can use for reference; either the submesh's section size, or the submesh's end offset. It's not recommended to use the primitive table size value because that value has been shown to be inaccurate in some cases in the Prime series and this may be the case in DKCR as well.
* [http://wiki.tockdom.com/wiki/Image_Formats Custom Mario Kart Wiiki]: More detailed information on each format, and how to decode them.


There are 7 primitive types supported by GX, indicated in the upper 5 bits of the flag value. Note that the game only ever actually uses triangles, triangle strips, and triangle fans; however, all of these primitives are supported by GX and are therefore supported by the game, and so they could be used in custom model files.
{| class="wikitable"
! Value
! Primitive
|-
| 0x80
| Quads
|-
| 0x90
| Triangles
|-
| 0x98
| Triangle strip
|-
| 0xA0
| Triangle fan
|-
| 0xA8
| Lines
|-
| 0xB0
| Line strip
|-
| 0xB8
| Points
|}


[[Category:File Formats]]
[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]
[[Category:Donkey Kong Country Returns]]

Revision as of 14:44, 23 January 2015

TXTR is, as the name suggests, the Retro Studios texture format. The format remains completely unchanged from Metroid Prime all the way up to Donkey Kong Country Returns.

Format

TXTR files contain a very short 12-byte header, followed by the image data.

Header

Offset Size Description
0x0 4 Image format. Possible values range from 0x0 to 0xA; see below for more details.
0x4 2 Width
0x6 2 Height
0x8 4 Mipmap count
0xC End of header

Palettes

The C4 and C8 image formats contain a palette table after the header, before the image data begins.

Offset Size Description
0x0 4 Palette format. Possible values range from 0 to 2.
0x4 2 Always 0x1 in C4, 0x100 in C8
0x6 2 Always 0x10 in C4, 0x1 in C8
0x8 Varies Palette colors. 16-bit color values; 16 colors in C4, 256 in C8.
End of palette table; image data begins immediately after

Image Formats

There are 11 different image formats; these are built directly into GX, so they remain the same across all GameCube and Wii games. Rather than storing pixels in a linear left-to-right order, GX textures encode pixels in large blocks. The size of the block varies depending on the image format.

For example, suppose you have a format that stores 4x4 blocks. Pixels 1-4 of the image will make up the first row of the first block; pixels 5-8 will make up the second row; 9-12 will make up the third row; 13-16 will make up the fourth row, completing the block; and the 17-20 will begin the first row of the second block, appearing directly to the right of the first row of the first block.

ID Name Bits per pixel Block size Description
0x0 I4 4 8x8 4-bit greyscale intensity values. Two pixels per byte.
0x1 I8 8 8x4 8-bit greyscale intensity values.
0x2 IA4 8 8x4 4-bit greyscale intensity values with an additional 4-bit alpha channel.
0x3 IA8 16 4x4 8-bit greyscale intensity values with an additional 8-bit alpha channel.
0x4 C4 4 8x8 4-bit palette indices.
0x5 C8 8 8x4 8-bit palette indices.
0x6 C14x2 16 4x4 Another palette format. Not used by any official textures.
0x7 RGB565 16 4x4 16-bit colors without alpha.
0x8 RGB5A3 16 4x4 16-bit colors with alpha.
0x9 RGBA8 32 4x4 Uncompressed 32-bit colors with alpha.
0xA CMPR 4 8x8 DXT1-compressed textures.

External links