Materials (Metroid Prime)
|This file format is almost completely documented |
MP1's materials are completely understood, but MP2 introduced two new values that are both unknown.
The materials system in Metroid Prime is heavily dependent on the GameCube and Wii's graphics system, GX. GX is a fixed-function graphics pipeline, similar to old versions of OpenGL. In GX, rendering is done through a series of steps called Texture EnVironment Stages, or or TEV stages for short.
Lighting calculations and tex coord generation are done per-vertex and passed along to TEV; the results of the lighting calculations are saved into up to two color channels that can be used as TEV inputs (as the rasterized vertex color). Each TEV stage takes in four color inputs and four alpha inputs, from one of eight sources. Then these four input colors are combined into one output color, and the output is saved into one of four registers, which can subsequently be used as input in the next TEV stages. The final stage must always save its output into the "previous TEV stage" register; that register is used as the final pixel color that gets displayed onscreen.
Material Set Format
Materials come as part of a set; often there will only be one set per file, but many CMDLs can have more than one. The set begins with a short header before the actual material data begins.
|long||1||Texture count (TC)|
|long||TC||Texture file IDs|
|long||1||Material count (MC)|
|long||MC||Material end offsets (relative to the start of the first material)|
Each material begins with a flags value, followed by a list of texture indices:
|long||1||Texture count (TC)|
|long||TC||Texture indices (these are indices into the material set texture array)|
|long||1||Vertex attribute flags|
|long||1||Unknown (note: only in Echoes)|
|long||1||Unknown (note: only in Echoes)|
|long||1||Konst count (KC); max setting is 4. (note: only present if flag 0x8 is set!)|
|long||KC||Konst colors - 32-bit RGBA colors (note: not present if the Konst count isn't)|
|short||1||Blend destination factor|
|short||1||Blend source factor|
|long||1||Reflection indirect texture slot index (note: only present if flag 0x400 is set!)|
|long||1||Color channel count (CC)|
|long||CC||Color channel flags (note: only one flag value, but you must advance 4*CC bytes instead of 4 for some reason)|
|long||1||TEV stage count|
These are simple boolean settings that can be toggled on and off on each material. These are the known flag settings:
|0||0x1||Unused, always set (never set in Echoes)|
|1||0x2||Unused, always set|
|2||0x4||Unused, never set|
|3||0x8||Has Konst values|
|5||0x20||Masked alpha (compare threshold is hardcoded at 0.25)|
|6||0x40||Enable Samus's reflection|
|8||0x100||Enable Samus's reflection, using the eye position and projection direction from the surface header|
|9||0x200||Shadow occluder mesh; meshes using this material are not rendered, but can be used to cast dynamic shadows on actors|
|10||0x400||Enable indirect texture stage for reflections|
|11||0x800||Indicates a lightmap is present; no ingame effect|
|12||0x1000||Unused, always set (never set in Echoes)|
|13||0x2000||Enable first UV coordinate to use short array instead of float array (used for world lightmaps)|
|14||0x4000||In MP1, unused, never set; in Echoes, unknown|
|15||0x8000||In MP1, unused, never set; in Echoes, unknown|
|16-31||0xFFFF0000||TEV texture flags; a bit set indicates that the corresponding TEV stage uses a texture. No ingame effect.|
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. Starting in Echoes, 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:
Echoes introduces some new attributes using the top byte of the flags value; unlike the other flags, these 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.
|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|
The group index marks groups of materials that all have the same settings, but different textures. The game will check the value after loading the textures (but prior to the vertex attribute flags), and check whether the group index set on the material matches the material currently set up. If it does, it will skip the rest of the material setup. The value typically starts at 0 on the first material and increments by 1 on each new group with different settings.
These values are only present when flag 0x8 is enabled. These allow you to set Konstant values, which can subsequently be used as inputs in TEV stages. The maximum number of Konst values you can set on one material is 4. The colors themselves are simply 32-bit RGBA values.
The two blend factors set the blending mode used. The most common values you'll see are 0/1, which is used on opaque materials; transparent materials will usually have either 1/1, for additive blending, or 5/4, for alpha blending. Here's the full range of possible settings for each value:
|2||GX_BL_SRCCLR / GX_BL_DSTCLR|
|3||GX_BL_INVSRCCLR / GX_BL_INVSRCCLR|
The color channels data consists of a count value indicating the number of color channels, and then one set of flags that controls the COLOR0 channel. The flags correspond to arguments passed to GX_SetChanCtrl(). These are the settings:
|0||0x1||Enable lighting (enable)|
|1||0x2||Ambient color source (ambsrc)|
|2||0x4||Material color source (matsrc)|
|3-10||0x7F8||Light mask; always 0, filled in at runtime (litmask)|
|11-12||0x1800||Diffuse function (diff_fn)|
|13-14||0x6000||Attenuation function (attn_fn)|
There's only one set of flags, which operates on COLOR0. COLOR1 is reserved for dynamic shadows (terrain casting shadows on actors), so its settings can't be directly modified. Here's how the other color channel settings work.
COLOR1A1's settings vary depending on whether shadowmaps are enabled:
- No processing will be done if the count value is 0. Otherwise, the count value is ignored; the game will always set up both color channels.
- COLOR1A1's ambient color is black, and its material color is white.
- COLOR1 will use the diffuse function GX_DF_CLAMP and the attenuation function GX_AF_SPOT. It will have lighting disabled entirely if there are no lights in range
If shadowmaps are disabled:
- COLOR1 is disabled if the count value is not 2. If it is 2, then its ambient color will be black and its material color will be white.
COLOR0 is set up the same way either way:
- COLOR0 will use the flags from the material, with the light mask merged in. It will also have lighting disabled if there are no lights in range.
- If there are no lights in range, COLOR0A0 will have its material color set to match its ambient color. Otherwise, its material color will be set to white.
Finally, an important note is that the formatting of the color channel info is bugged. There is always a color channel count and a single set of flags; 8 bytes total. However, for some reason the game is expecting one set of flags per color channel. To reach the TEV stages, you need to advance (4 * count) bytes past the count value, rather than 4. A likely explanation is that there was one set of flags per channel earlier in development, and the material loading code wasn't fully updated when this was changed. It's not normally an issue because the count is always 1 in every file the game uses, but beware for experimentation/custom materials.
There'll be one of these structures per TEV stage:
|0x0||4||Color Input Flags|
|0x4||4||Alpha Input Flags|
|0x8||4||Color Combine Flags|
|0xC||4||Alpha Combine Flags|
|0x11||1||Konst Alpha Input (possible values)|
|0x12||1||Konst Color Input (possible values)|
|0x13||1||Rasterized Color Input (possible values)|
|0x14||End of TEV stage|
After looping through each TEV stage, there will be one of these structures per stage:
|0x2||1||Texture TEV Input|
|0x3||1||Tex Coord TEV Input|
|0x4||End of structure|
Color Input Flags
These flags set the four color inputs that are used by the TEV stage. Each color is allocated 5 bits, even though only 4 are actually used; the lower bits correspond to the lower input numbers (eg. the bottom 5 bits refer to the first input).
There are 16 possible color sources:
|00000||0x0||Previous stage RGB|
|00001||0x1||Previous stage AAA|
|00010||0x2||Color 0 RGB|
|00011||0x3||Color 0 AAA|
|00100||0x4||Color 1 RGB|
|00101||0x5||Color 1 AAA|
|00110||0x6||Color 2 RGB|
|00111||0x7||Color 2 AAA|
Alpha Input Flags
Similar to the color input flags, these set the four alpha inputs used by the TEV stage. Each value is allocated 5 bits, although only 3 are used. The main difference with alpha is that there are only 8 possible sources instead of 16:
|00000||0x0||Previous stage alpha|
|00001||0x1||Color 0 alpha|
|00010||0x2||Color 1 alpha|
|00011||0x3||Color 2 alpha|
Color Combine Flags
These flags specify how the operation that combines the four input colors into one output color is performed.
This is the combiner function:
tevrigid = (d (tevop) ((1.0-c)*a + c*b) + tevbias) * tevscale;
The values set in the color operation flags correspond to the parameters passed to GX_SetTevColorOp(). These are the settings:
|0-3||0xF||Combiner operator (tevop)|
|4-5||0x30||Bias (tevbias); 00 does nothing; 01 adds 0.5; 10 subtracts 0.5; 11 does nothing.|
|6-7||0xC0||Scale (tevscale); 00 does nothing; 01 multiples by 2; 10 multiplies by 4; 11 divides by 2.|
|8||0x100||Clamp flag; enabling this will clamp the output color between 0 and 1.|
|9-10||0x600||Output register (tevrigid); can be Previous Stage or Color 0/1/2|
Note that the vast majority of materials in the game, if not all of them, don't really bother with any of this; they enable clamping, set an output register, and leave everything else at their defaults of 0.
Alpha Combine Flags
This is exactly the same as the color combine flags; the only difference is it operates on alpha instead of color.
After the TEV stages comes a sequence of flags determining how texgen is executed. Texgen is the process of taking input values and using them to generate texture coordinates (or UV coordinates), which can then be used by the TEV stages. It's important to note that any vertex attribute can be used as a texgen input; in fact, it's rather common for materials to use the vertex normal as an input to simulate reflections. That means the number of texture coords present on each vertex is not the same as the number of texture coords available to TEV.
|long||1||Texgen count (TC)|
The flags correspond to arguments passed to GX_SetTexCoordGen2(). These are the settings:
|0-3||0xF||Texture coord generation type (tgen_typ)|
|4-8||0x1F0||Texture coord source (tgen_src)|
|9-13||0x3E00||Texture matrix index (mtxsrc - add 30)|
|14||0x4000||Normalize flag - normalizes texture coord after it's multiplied by the texture matrix (normalize)|
|15-20||0x1F8000||Post-transform texture matrix index (postmtx - add 64)|
See UV Animations
The UV animations section immediately follows the texgen flags. Its purpose is to generate texture matrices and post-transform matrices, which are then used to transform UV coordinates. This is commonly used to animate textures via simple UV scrolls, but it's also often used to simulate reflective surfaces that move with the camera. Materials can have multiple UV animations; in that case, each animation generates a separate texture/post-transform matrix and are loaded into GX sequentially. Texgen is used to set which matrices are used by which UV coordinates (if any).
The section starts with this short header:
|0x0||4||Material animations section size (includes animation count, so will be 4 at minimum)|
For info on how to read the animation data and how each animation mode works, see UV Animations.