Materials (Metroid Prime 3): Difference between revisions

From Retro Modding Wiki
Jump to navigation Jump to search
VisualWikitext
>Aruki
(initial findings from a day reverse engineering the material loading code. more to come)
 
>Aruki
 
(41 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The format for '''materials''' saw a dramatic overhaul in Metroid Prime 3. The format is seen in both the CMDL and MREA formats and is identical in both. This particular material format appears in Metroid Prime 3: Corruption and Donkey Kong Country Returns.
The format for '''materials''' saw a dramatic overhaul in Metroid Prime 3. The format is seen in both the CMDL and MREA formats and is identical in both. This particular material format appears in Metroid Prime 3: Corruption and Donkey Kong Country Returns.


{{research|moderate|Need to find TEV values for each subsection type}}
{{research|moderate|There are a ton of unknowns in this format}}


__TOC__
__TOC__
Line 7: Line 7:
== Material Set Format ==
== Material Set Format ==


Materials come as part of a set; although most files will only have one set, some CMDLs will have more, as indicated by a count value in the header. The set format is merely a 32-bit count value followed by that number of materials, with each material beginning with a 32-bit size value.
Materials come as part of a set; although most files will only have one set, some CMDLs will have more, as indicated by a count value in the header. The set format is merely a 32-bit count value followed by that number of materials. In Metroid Prime 3, each material set will be in its own CMDL/MREA section, but in DKCR each set will be in the same section.


== Material Format ==
== Material Format ==


Every material begins with a 0x1C-byte header, followed by a number of subsections. The header is structured as follows:
The material format starts with a 28-byte header, then after that is broken up into a bunch of subsections.
 
=== Header ===


{| class="wikitable"
{| class="wikitable"
Line 23: Line 25:
| u32
| u32
| 4
| 4
| {{unknown|'''Unknown'''}}
| '''Material size'''
| Likely a flag value similar to the one from MP1/2. Needs verification.
| Does not include size value
|-
|-
| 0x4
| 0x4
| u32
| u32
| 4
| 4
| {{unknown|'''Unknown'''}}
| '''Material flags'''
|
| Only bottom 17 bits are valid
|-
|-
| 0x8
| 0x8
| u32
| 4
| '''Group index'''
| Denotes groups of materials that share the same settings, but different textures.
|-
| 0xC
| u32
| u32
| 4
| 4
Line 38: Line 46:
| Value is possibly unused; the material loading code seems to skip it
| Value is possibly unused; the material loading code seems to skip it
|-
|-
| 0xC
| 0x10
| u32
| u32
| 4
| 4
Line 44: Line 52:
| Functionality is identical to Metroid Prime 2
| Functionality is identical to Metroid Prime 2
|-
|-
| 0x10
| 0x14
| u32
| u32
| 4
| 4
Line 50: Line 58:
| Value is possibly unused; the material loading code seems to skip it
| Value is possibly unused; the material loading code seems to skip it
|-
|-
| 0x14
| 0x18
| u32
| u32
| 4
| 4
Line 56: Line 64:
|
|
|-
|-
| 0x18
| 0x1C
| u32
| u32
| 4
| 4
Line 62: Line 70:
|
|
|-
|-
| 0x1C
| 0x20
| colspan=4 {{unknown|End of header}}
| colspan=4 {{unknown|End of header}}
|}
==== Flags ====
Known flag values:
{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| {{unknown|Unknown}}
|-
| 1
| 0x2
| {{unknown|Unknown}}
|-
| 2
| 0x4
| {{unknown|Unknown}}
|-
| 3
| 0x8
| Enable alpha blending
|-
| 4
| 0x10
| Enable punchthrough alpha. The alpha channel of the texture on the <code>CLR </code> pass will be sampled. Bloom passes will be disabled. The alpha compare function is <code>alpha <= 0.75</code>.
|-
| 5
| 0x20
| Enable additive blending (probably - needs verification)
|-
| 6
| 0x40
| {{unknown|Unknown}}
|-
| 7
| 0x80
| {{unknown|Unknown}}
|-
| 8
| 0x100
| Shadow occluder mesh; meshes using this material are not rendered, but can be used to cast dynamic shadows on actors
|-
| 9
| 0x200
| {{unknown|Unknown}}
|-
| 10
| 0x400
| {{unknown|Unknown}}
|-
| 11
| 0x800
| {{unknown|Unknown}}
|-
| 12
| 0x1000
| {{unknown|Unknown}}
|-
| 13
| 0x2000
| {{unknown|Unknown}}
|-
| 14
| 0x4000
| {{unknown|Unknown}}
|-
| 15
| 0x8000
| {{unknown|Unknown}}
|-
| 16
| 0x10000
| {{unknown|Unknown}}
|-
| 17
| 0x20000
| {{unknown|Unknown; DKCR only}}
|-
| 18
| 0x40000
| {{unknown|Unknown; DKCR only}}
|-
| 19
| 0x80000
| Render with white ambient color. This is used on world geometry that doesn't have lightmaps. DKCR only.
|-
| 20
| -
| Unused in MP3; possibly used in DKCR
|}
==== Vertex Attribute Flags ====
These flags are generally toggled in pairs, with each pair corresponding to a vertex attribute; if a pair is set, then vertices using this material will have the corresponding attribute. This is vital for reading geometry. Each pair is used to indicate the size of the attribute indices in the geometry data, with 3 meaning a 16-bit index and 2 meaning an 8-bit index. (This isn't actually used, though; the original game data always uses 16-bit indices.)
GX supports up to 8 texture coords per vertex, but the game doesn't seem to allow you to assign more than 7 (though this could do with some double-checking).
These are the possible attributes:
{| class="wikitable"
! Bit pair
! Attribute
|-
| 0x3
| Position
|-
| 0xC
| Normal
|-
| 0x30
| Color 0
|-
| 0xC0
| Color 1
|-
| 0x300
| Tex 0
|-
| 0xC00
| Tex 1
|-
| 0x3000
| Tex 2
|-
| 0xC000
| Tex 3
|-
| 0x30000
| Tex 4
|-
| 0xC0000
| Tex 5
|-
| 0x300000
| Tex 6
|}
The top byte is structured differently; unlike the other flags, the bits in the top byte Are not set in pairs. Each individual bit indicates the presence of a different attribute. The indices in the geometry data are always 8 bits.
{| class="wikitable"
! Bit
! Attribute
|-
| 0x1
| Position Matrix Index
|-
| 0x2
| Tex0 Matrix Index
|-
| 0x4
| Tex1 Matrix Index
|-
| 0x8
| Tex2 Matrix Index
|-
| 0x10
| Tex3 Matrix Index
|-
| 0x20
| Tex4 Matrix Index
|-
| 0x40
| Tex5 Matrix Index
|-
| 0x80
| Tex6 Matrix Index
|}
|}


=== Subsections ===
=== Subsections ===


The rest of the material data is made up of a number of subsections. These subsections generally set different texture slots, as well as other parameters like Konst colors and material opacity. There's no count for the number of subsections; it needs to be read in using a while loop. The "END " section denotes the end of the material.
The rest of the material data is made up of a number of subsections. These subsections generally set different texture slots, as well as other parameters like Konst colors and material opacity. There's no count for the number of subsections; it needs to be read in using a while loop. The <code>END </code> section denotes the end of the material.


There are three subsection types (aside from END): PASS, CLR, and INT. Each of these types has a number of subtypes.
The order of the subsections doesn't matter. One material can only have one of each type of subsection; if there's any additional ones, they will overwrite the previous ones.
 
There are three subsection types (aside from <code>END </code>): <code>PASS</code>, <code>CLR </code>, and <code>INT </code>. Each of these types has a number of subtypes.


==== PASS ====
==== PASS ====
The PASS sections set up a single rendering pass, consisting of one TEV stage and potential other data to go with it (like a UV animation). One pass is 32 bytes (without the animation) and is structured as follows:


{| class="wikitable"
{| class="wikitable"
Line 96: Line 279:
| u32
| u32
| 4
| 4
| {{unknown|'''Unknown'''}}
| '''Pass Flags'''
|  
| Only bottom 5 bits are valid
|-
|-
| 0xC
| 0xC
Line 108: Line 291:
| u32
| u32
| 4
| 4
| '''UV Source'''
| Only bottom 4 bits are valid
|-
| 0x18
| u32
| 4
| '''UV Animation Size'''
|
|}
If there's a UV anim, it is structured like this:
{| class="wikitable"
! Offset
! Type
! Size
! Description
|-
| 0x0
| u16
| 2
| {{unknown|'''Unknown'''}}
|-
| 0x2
| u16
| 2
| {{unknown|'''Unknown'''}}
| {{unknown|'''Unknown'''}}
|
|-
|-
| 0x18
| 0x4
| u32
| u32
| 4
| 4
| '''UV animations size'''
| '''[[UV_Animations#Animation_Modes|Animation Type]]'''
| Needs verification
|}
|}


List of possible PASS subtypes:
List of possible PASS subtypes: (note: the pass types are also processed in this order)


{| class="wikitable"
{| class="wikitable"
! Type
! Type
! Description
! Description
! MP3
! DKCR
|-
|-
| <code>DIFF</code>
| <code>DIFF</code>
| Commonly used for lightmaps
| Lightmap
| {{check}}
| {{check}}
|-
| <code>RIML</code>
| Rim lighting map
| {{nocheck}}
| {{check}}
|-
|-
| <code>BLOL</code>
| <code>BLOL</code>
|  
| Bloom lightmap
| {{check}}
| {{nocheck}}
|-
| <code>BLOD</code>
| Bloom diffuse map
| {{check}}
| {{nocheck}}
|-
|-
| <code>CLR </code>
| <code>CLR </code>
| Likely color map, similar to <code>DIFF</code>; commonly used for diffuse maps
| Diffuse map
| {{check}}
| {{check}}
|-
|-
| <code>TRAN</code>
| <code>TRAN</code>
| Greyscale opacity map; white indicates transparent, black indicates opaque (Retro is backwards)
| Opacity map
| {{check}}
| {{check}}
|-
|-
| <code>INCA</code>
| <code>INCA</code>
| Likely incandescence/emissive maps
| Incandescence map
| {{check}}
| {{check}}
|-
|-
| <code>RFLV</code>
| <code>RFLV</code>
|  
| Reflectivity map
| {{check}}
| {{check}}
|-
|-
| <code>RFLD</code>
| <code>RFLD</code>
|  
| Reflection map
| {{check}}
| {{check}}
|-
|-
| <code>LRLD</code>
| <code>LRLD</code>
|  
| {{unknown|Unknown}}
| {{check}}
| {{check}}
|-
|-
| <code>LURD</code>
| <code>LURD</code>
|  
| {{unknown|Unknown}}
|-
| {{check}}
| <code>BLOD</code>
| {{check}}
|  
|-
|-
| <code>BLOI</code>
| <code>BLOI</code>
|  
| Bloom incandescence map
| {{check}}
| {{nocheck}}
|-
|-
| <code>XRAY</code>
| <code>XRAY</code>
| From the name, possibly texture map setting visuals for X-Ray Visor
| Reflection map for X-Ray models; similar to <code>RFLD</code>
| {{check}}
| {{nocheck}}
|-
| <code>TOON</code>
| {{unknown|Unknown; unused}}
| {{nocheck}}
| {{check}}
|}
 
===== Flags =====
 
Known flag settings:
 
{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| {{unknown|Unknown}}
|-
| 1
| 0x2
| {{unknown|Unknown}}
|-
| 2
| 0x4
| On <code>INCA</code>, factors in the texture map as a bloom map as (0.25 * texture alpha)
|-
| 3
| 0x8
| {{unknown|Unknown}}
|-
| 4
| 0x10
| On <code>TRAN</code>, indicates that the texture map is inverted (ie. white is transparent, black is opaque).
|-
| 5+
| -
| Unused
|}
|}
===== UV Animations =====
'' See [[UV Animations]]


==== CLR  ====
==== CLR  ====
Line 188: Line 469:
! Type
! Type
! Description
! Description
! MP3
! DKCR
|-
|-
| <code>CLR </code>
| <code>CLR </code>
|  
| {{unknown|Unknown}}
| {{check}}
| {{check}}
|-
|-
| <code>DIFB</code>
| <code>DIFB</code>
|  
| Lightmap multiplier color
| {{check}}
| {{check}}
|}
|}


Line 215: Line 502:
| 4
| 4
| '''Value'''
| '''Value'''
|
| Actually an 8-bit value; the top 24 bits are ignored
|}
|}


Line 223: Line 510:
! Type
! Type
! Description
! Description
! MP3
! DKCR
|-
|-
| <code>OPAC</code>
| <code>OPAC</code>
| Sets the opacity of the entire material
| Sets the opacity of the entire material
| {{check}}
| {{check}}
|-
|-
| <code>BLOD</code>
| <code>BLOD</code>
|  
| {{unknown|Unknown; bloom-related?}}
| {{check}}
| {{nocheck}}
|-
|-
| <code>BLOI</code>
| <code>BLOI</code>
|  
| {{unknown|Unknown; bloom-related?}}
| {{check}}
| {{nocheck}}
|-
|-
| <code>BNIF</code>
| <code>BNIF</code>
|  
| {{unknown|Unknown}}
| {{check}}
| {{nocheck}}
|-
|-
| <code>XRBR</code>
| <code>XRBR</code>
|  
| {{unknown|Unknown; X-Ray related?}}
| {{check}}
| {{nocheck}}
|}
|}


Latest revision as of 06:57, 18 February 2016

The format for materials saw a dramatic overhaul in Metroid Prime 3. The format is seen in both the CMDL and MREA formats and is identical in both. This particular material format appears in Metroid Prime 3: Corruption and Donkey Kong Country Returns.


This file format needs more research
There are a ton of unknowns in this format


Material Set Format

Materials come as part of a set; although most files will only have one set, some CMDLs will have more, as indicated by a count value in the header. The set format is merely a 32-bit count value followed by that number of materials. In Metroid Prime 3, each material set will be in its own CMDL/MREA section, but in DKCR each set will be in the same section.

Material Format

The material format starts with a 28-byte header, then after that is broken up into a bunch of subsections.

Header

Offset Type Size Description Notes
0x0 u32 4 Material size Does not include size value
0x4 u32 4 Material flags Only bottom 17 bits are valid
0x8 u32 4 Group index Denotes groups of materials that share the same settings, but different textures.
0xC u32 4 Unknown Value is possibly unused; the material loading code seems to skip it
0x10 u32 4 Vertex attribute flags Functionality is identical to Metroid Prime 2
0x14 u32 4 Unknown Value is possibly unused; the material loading code seems to skip it
0x18 u32 4 Unknown
0x1C u32 4 Unknown
0x20 End of header

Flags

Known flag values:

Bit Hex Description
0 0x1 Unknown
1 0x2 Unknown
2 0x4 Unknown
3 0x8 Enable alpha blending
4 0x10 Enable punchthrough alpha. The alpha channel of the texture on the CLR pass will be sampled. Bloom passes will be disabled. The alpha compare function is alpha <= 0.75.
5 0x20 Enable additive blending (probably - needs verification)
6 0x40 Unknown
7 0x80 Unknown
8 0x100 Shadow occluder mesh; meshes using this material are not rendered, but can be used to cast dynamic shadows on actors
9 0x200 Unknown
10 0x400 Unknown
11 0x800 Unknown
12 0x1000 Unknown
13 0x2000 Unknown
14 0x4000 Unknown
15 0x8000 Unknown
16 0x10000 Unknown
17 0x20000 Unknown; DKCR only
18 0x40000 Unknown; DKCR only
19 0x80000 Render with white ambient color. This is used on world geometry that doesn't have lightmaps. DKCR only.
20 - Unused in MP3; possibly used in DKCR

Vertex Attribute Flags

These flags are generally toggled in pairs, with each pair corresponding to a vertex attribute; if a pair is set, then vertices using this material will have the corresponding attribute. This is vital for reading geometry. Each pair is used to indicate the size of the attribute indices in the geometry data, with 3 meaning a 16-bit index and 2 meaning an 8-bit index. (This isn't actually used, though; the original game data always uses 16-bit indices.)

GX supports up to 8 texture coords per vertex, but the game doesn't seem to allow you to assign more than 7 (though this could do with some double-checking).

These are the possible attributes:

Bit pair Attribute
0x3 Position
0xC Normal
0x30 Color 0
0xC0 Color 1
0x300 Tex 0
0xC00 Tex 1
0x3000 Tex 2
0xC000 Tex 3
0x30000 Tex 4
0xC0000 Tex 5
0x300000 Tex 6

The top byte is structured differently; unlike the other flags, the bits in the top byte Are not set in pairs. Each individual bit indicates the presence of a different attribute. The indices in the geometry data are always 8 bits.

Bit Attribute
0x1 Position Matrix Index
0x2 Tex0 Matrix Index
0x4 Tex1 Matrix Index
0x8 Tex2 Matrix Index
0x10 Tex3 Matrix Index
0x20 Tex4 Matrix Index
0x40 Tex5 Matrix Index
0x80 Tex6 Matrix Index

Subsections

The rest of the material data is made up of a number of subsections. These subsections generally set different texture slots, as well as other parameters like Konst colors and material opacity. There's no count for the number of subsections; it needs to be read in using a while loop. The END section denotes the end of the material.

The order of the subsections doesn't matter. One material can only have one of each type of subsection; if there's any additional ones, they will overwrite the previous ones.

There are three subsection types (aside from END ): PASS, CLR , and INT . Each of these types has a number of subtypes.

PASS

The PASS sections set up a single rendering pass, consisting of one TEV stage and potential other data to go with it (like a UV animation). One pass is 32 bytes (without the animation) and is structured as follows:

Offset Type Size Description Notes
0x0 u32 4 PASS subsection size
0x4 char[4] 4 Section subtype fourCC See below for possible subtypes
0x8 u32 4 Pass Flags Only bottom 5 bits are valid
0xC TXTR 8 Texture ID
0x14 u32 4 UV Source Only bottom 4 bits are valid
0x18 u32 4 UV Animation Size

If there's a UV anim, it is structured like this:

Offset Type Size Description
0x0 u16 2 Unknown
0x2 u16 2 Unknown
0x4 u32 4 Animation Type

List of possible PASS subtypes: (note: the pass types are also processed in this order)

Type Description MP3 DKCR
DIFF Lightmap ✔ ✔
RIML Rim lighting map ✖ ✔
BLOL Bloom lightmap ✔ ✖
BLOD Bloom diffuse map ✔ ✖
CLR Diffuse map ✔ ✔
TRAN Opacity map ✔ ✔
INCA Incandescence map ✔ ✔
RFLV Reflectivity map ✔ ✔
RFLD Reflection map ✔ ✔
LRLD Unknown ✔ ✔
LURD Unknown ✔ ✔
BLOI Bloom incandescence map ✔ ✖
XRAY Reflection map for X-Ray models; similar to RFLD ✔ ✖
TOON Unknown; unused ✖ ✔
Flags

Known flag settings:

Bit Hex Description
0 0x1 Unknown
1 0x2 Unknown
2 0x4 On INCA, factors in the texture map as a bloom map as (0.25 * texture alpha)
3 0x8 Unknown
4 0x10 On TRAN, indicates that the texture map is inverted (ie. white is transparent, black is opaque).
5+ - Unused
UV Animations

See UV Animations

CLR

Offset Type Size Description Notes
0x0 char[4] 4 Section subtype fourCC See below for possible subtypes
0x4 u32 4 Color value 32-bit RGBA value

List of possible CLR subtypes:

Type Description MP3 DKCR
CLR Unknown ✔ ✔
DIFB Lightmap multiplier color ✔ ✔

INT

Offset Type Size Description Notes
0x0 char[4] 4 Section subtype fourCC See below for possible subtypes
0x4 u32 4 Value Actually an 8-bit value; the top 24 bits are ignored

List of possible INT subtypes:

Type Description MP3 DKCR
OPAC Sets the opacity of the entire material ✔ ✔
BLOD Unknown; bloom-related? ✔ ✖
BLOI Unknown; bloom-related? ✔ ✖
BNIF Unknown ✔ ✖
XRBR Unknown; X-Ray related? ✔ ✖
Retrieved from "https://wiki.axiodl.com/index.php?title=Materials_(Metroid_Prime_3)&oldid=1736"