Materials (Metroid Prime)

2015-01-30T13:42:46Z

Sdmr: grammar correction and minor improvements in readability

The format for '''materials''' is seen in both the [[CMDL (Metroid Prime)|CMDL]] and [[MREA (File Format)|MREA]] formats and is identical in both. This particular material format appears in both Metroid Prime and Metroid Prime 2 with minor differences.

{{research|moderate|There are a few unknown values, and some unknown settings in known values; there are also a few unknown material animation modes. Also, basically everything that was introduced in Echoes (two general settings and a vertex attribute) is unknown.}}

__TOC__

== GX Explanation ==

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 '''T'''exture '''E'''n'''V'''ironment Stages, or or TEV stages for short.

Prior to TEV stages, per-vertex calculations are performed. Lighting calculations are performed and passed to GX as a rasterized vertex color; texture coordinate generation (texgen) is also performed and made available to TEV.

How TEV stages actually work: Each TEV stage takes in four color (RGB) 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.

{| class="wikitable"
!Type
!Count
!Description
|-
| 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)
|-
| colspan=3 | Materials begin
|}

== Material Format ==

=== General Settings ===

Each material begins with a flags value, followed by a list of texture indices:

{| class="wikitable"
!Type
!Count
!Description
|-
| long
| 1
| '''Flags'''
|-
| 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|'''Unknown''' ''(note: only in Echoes)''}}
|-
| long
| 1
| {{unknown|'''Unknown''' ''(note: only in Echoes)''}}
|-
| long
| 1
| {{unknown|'''Unknown'''}}
|-
| 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
| {{unknown|'''Unknown''' ''(note: only present if flag 0x400 is set!)''}}
|-
| long
| 1
| '''Color channel flag count''' (CC)
|-
| long
| CC
| '''Color channel flags'''
|-
| long
| 1
| '''TEV stage count'''
|}

==== Flags ====

These are the known flag settings:

{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| Appears unused, but always set
|-
| 1
| 0x2
| Appears unused, but always set
|-
| 2
| 0x4
| Appears unused, but always unset
|-
| 3
| 0x8
| Enable Konstant values
|-
| 4
| 0x10
| Mark transparent material
|-
| 5
| 0x20
| Enable punchthrough alpha
|-
| 6
| 0x40
| Enable Samus's reflection
|-
| 7
| 0x80
| Enable depth writing
|-
| 8
| 0x100
| {{unknown|Unknown}}
|-
| 9
| 0x200
| Don't draw
|-
| 10
| 0x400
| Enable second unknown value
|-
| 11
| 0x800
| {{unknown|Unknown}}
|-
| 12
| 0x1000
| {{unknown|Unknown}}
|-
| 13
| 0x2000
| Enable lightmaps; first UV coordinate uses short array instead of float array
|-
| 14
| 0x4000
| {{unknown|Unknown}}
|-
| 15
| 0x8000
| {{unknown|Unknown}}
|-
| 16
| 0x10000
| {{unknown|Unknown}}
|-
| 17
| 0x20000
| {{unknown|Unknown}}
|-
| 18
| 0x40000
| {{unknown|Unknown}}
|-
| 19
| 0x80000
| {{unknown|Unknown}}
|-
| 20+
| 0x100000+
| Unused; never set
|}

==== 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.

An important note is that while the leftmost byte is not used in Prime 1, in Echoes there's occasionally a value there that toggles an extra vertex attribute preceding position. This needs research to determine what the new attribute actually is. Also, 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
|-
| 0xC0000
| Tex 3
|-
| 0x300000
| Tex 4
|-
| 0xC00000
| Tex 5
|-
| 0x3000000
| Tex 6
|}

==== Konst Colors ====

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.

==== Blend Mode ====

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:

{| class="wikitable"
! Value
! Blend factor
|-
| 0
| GX_BL_ZERO
|-
| 1
| GX_BL_ONE
|-
| 2
| GX_BL_SRCCLR / GX_BL_DSTCLR
|-
| 3
| GX_BL_INVSRCCLR / GX_BL_INVSRCCLR
|-
| 4
| GX_BL_SRCALPHA
|-
| 5
| GX_BL_INVSRCALPHA
|-
| 6
| GX_BL_DSTALPHA
|-
| 7
| GX_BL_INVDSTALPHA
|}

==== Color Channels ====

There's an odd quirk with how these values work; although there's a count value listed, the game will only actually read the first value listed and then skip the rest. There's no reason to ever have more than one flag value. Aside from that, how this works is unknown and needs research.

=== TEV Stages ===

There'll be one of these structures per TEV stage:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Color Input Flags'''
|-
| 0x4
| 4
| '''Alpha Input Flags'''
|-
| 0x8
| 4
| '''Color Combine Flags'''
|-
| 0xC
| 4
| '''Alpha Combine Flags'''
|-
| 0x10
| 1
| '''Padding'''
|-
| 0x11
| 1
| '''Konst Alpha Input'''
|-
| 0x12
| 1
| '''Konst Color Input'''
|-
| 0x13
| 1
| '''Rasterized Color Input'''
|-
| 0x14
| colspan=2 {{unknown|End of TEV stage}}
|}

After looping through each TEV stage, there will be one of these structures per stage:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Padding'''
|-
| 0x2
| 1
| '''Texture TEV Input'''
|-
| 0x3
| 1
| '''Tex Coord TEV Input'''
|-
| 0x4
| colspan=2 {{unknown|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:

{| class="wikitable"
! Binary
! Hex
! Color Source
|-
| 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
|-
| 01000
| 0x8
| Texture RGB
|-
| 01001
| 0x9
| Texture AAA
|-
| 01010
| 0xA
| Rasterized RGB
|-
| 01011
| 0xB
| Rasterized AAA
|-
| 01100
| 0xC
| One
|-
| 01101
| 0xD
| Half
|-
| 01110
| 0xE
| Konstant RGB
|-
| 01111
| 0xF
| Zero
|}

==== 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:

{| class="wikitable"
! Binary
! Hex
! Alpha Source
|-
| 00000
| 0x0
| Previous stage alpha
|-
| 00001
| 0x1
| Color 0 alpha
|-
| 00010
| 0x2
| Color 1 alpha
|-
| 00011
| 0x3
| Color 2 alpha
|-
| 00100
| 0x4
| Texture alpha
|-
| 00101
| 0x5
| Rasterized alpha
|-
| 00110
| 0x6
| Konstant alpha
|-
| 00111
| 0x7
| Zero
|}

==== 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:

<pre>tevrigid = (d (tevop) ((1.0-c)*a + c*b) + tevbias) * tevscale;</pre>

The values set in the color operation flags correspond to the parameters passed to [http://libogc.devkitpro.org/gx_8h.html#a067b875ff1e3e6760d0d7d7838c6c4c2 GX_SetTevColorOp()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0-3
| 0xF
| '''Combiner operator''' ([http://libogc.devkitpro.org/group__tevop.html tevop])
|-
| 4-5
| 0x30
| '''Bias''' ([http://libogc.devkitpro.org/group__tevbias.html tevbias]); 00 does nothing; 01 adds 0.5; 10 subtracts 0.5; 11 does nothing.
|-
| 6-7
| 0xC0
| '''Scale''' ([http://libogc.devkitpro.org/group__tevscale.html 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''' ([http://libogc.devkitpro.org/group__tevcoloutreg.html tevrigid]); can be Previous Stage or Color 0/1/2
|-
| 11+
| 0xFFFFF800
| Unused.
|}

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.

=== Texgen ===

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''.

{| class="wikitable"
! Type
! Count
! Description
|-
| long
| 1
| '''Texgen count''' (TC)
|-
| long
| TC
| '''Texgen flags'''
|}

The flags correspond to arguments passed to [http://libogc.devkitpro.org/gx_8h.html#a55a426a3ff796db584302bddd829f002 GX_SetTexCoordGen2()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0-3
| 0xF
| '''Texture coord generation type''' ([http://libogc.devkitpro.org/group__texgentyp.html tgen_typ])
|-
| 4-8
| 0x1F0
| '''Texture coord source''' ([http://libogc.devkitpro.org/group__texgensrc.html tgen_src])
|-
| 9-13
| 0x3E00
| '''Texture matrix index''' ([http://libogc.devkitpro.org/group__texmtx.html 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''' ([http://libogc.devkitpro.org/group__dttmtx.html postmtx] - add 64)
|-
| 21+
| 0xFFE00000
| Unused
|}

=== Material Animations ===

The material animations section immediately follows the texgen flags. It starts with this short header:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Material animations section size''' (includes animation count, so will be 4 at minimum)
|-
| 0x4
| 4
| '''Animation count'''
|}

The structure of the animations themselves is somewhat simple. Each animation has a 32-bit ''mode'' setting, followed by a number of float parameters. The number and usage of these float parameters varies depending on what mode is set. There are 7 possible modes, but only modes 2 through 5 are known.

For all of the following modes, let ''s'' be equal to ''seconds mod 900''.

==== Mode 2: UV Offset ====

This mode is used to scroll both U and V at the same time. It has four float parameters: ''offsetA'', ''offsetB'', ''scaleA'', and ''scaleB''.

<pre>uOffset = (s * scaleA) + offsetA;
vOffset = (s * scaleB) + offsetB;</pre>

==== Mode 3: Rotation ====

This mode rotates the material. It has two float parameters: ''offset'' and ''scale''.

<pre>angle = (s * scale) + offset;</pre>

The material is then rotated by ''angle'' degrees.

==== Mode 4/5: U/V Offset ====

This mode can be used to scroll U and V independently from each other. It has four float parameters. The offset calculation for these modes is unknown; however, the same code is used for both modes, with the only difference being whether the calculated offset is applied to U or V.

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

SCAN (Metroid Prime)

2015-01-30T13:32:49Z

Sdmr: grammar correction and minor improvements in readability

The '''.SCAN file format''' describes scannable objects and has references to several resources. It is a relatively simple format and has a static size.

{{researchmoderate|reason=Too many unknowns.}}

__TOC__

== Format ==

The SCAN format is very simple; it has a header with data that contains general settings related to the scan, and then four structs defining how the scan images work. Even if a scan doesn't use four images, there are always four image structs, which means that the SCAN format has a static size; every SCAN file is 0x89 bytes (or 0xA0 bytes padded).

=== Header ===

The header is rather simple, and consists of the following:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Version'''; 3 for the demo, 5 for the final
|-
| 0x4
| 4
| '''Magic'''; always 0x0BADBEEF
|-
| 0x8
| 4
| '''[[FRME (File Format)|FRME]] ID'''
|-
| 0xC
| 4
| '''Scan text [[STRG (File Format)|STRG]] ID'''
|-
| 0x10
| 4
| '''Scan Speed Flag'''; 0 = normal fast scan, 1 = slower scan (usually found in boss fights)
|-
| 0x14
| 4
| '''Logbook Category'''; see below
|-
| 0x18
| 1
| '''Scan Icon Flag'''; 0 = orange icon, 1 = red icon
|-
| 0x19
| colspan=2 {{unknown|End of header}}
|}

==== Logbook Category ====

There are five possible values:

{| class="wikitable"
! ID
! Category
|-
| 0
| Not a logbook scan
|-
| 1
| Space Pirate Data
|-
| 2
| Chozo Lore
|-
| 3
| Creatures
|-
| 4
| Research
|}

=== Scan Images ===
[[File:Scan_positions1.png|thumb|300px|Offsets for the different scan images and their positions]]
[[File:Scan_positions2.png|thumb|300px]]
Following the header is an array of four structs that contain settings for up to four scan images. Although there can be anywhere from 0 to 4 scan images attached to a scan, there are always four scan image entries here. Entries that aren't used have their TXTR ID set to 0xFFFFFFFF, with the rest of the settings mostly left at defaults. They follow this format:

{| class="wikitable"
! Offset
! Size
! Type
! Description
|-
| 0x0
| 4
| long
| '''[[TXTR (Metroid Prime)|TXTR]] ID'''
|-
| 0x4
| 4
| float
| '''Appearance %'''; image will appear when the scan is this% complete. Should range from 0 to 1.
|-
| 0x8
| 4
| long
| {{unknown|'''Unknown (Fade in duration?)'''}}
|-
| 0xC
| 4
| long
| {{unknown|'''Unknown'''}}
|-
| 0x10
| 4
| long
| {{unknown|'''Unknown'''}}
|-
| 0x14
| 4
| long
| {{unknown|'''Unknown'''}}
|-
| 0x18
| 4
| float
| {{unknown|'''Unknown'''}}
|-
| 0x1C
| colspan=3 {{unknown|End of entry}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]

SCAN (Metroid Prime 2)

2015-01-30T13:29:34Z

Sdmr: grammar correction and minor improvements in readability

The '''.SCAN file format''' describes SCAN POI data and has references to several resources. This variation of the format is completely different than its [[SCAN (Metroid Prime)|Metroid Prime]] counterpart.

{{researchmajor|reason=Crack SNFO}}

__TOC__

=Header=
The header is rather simple and consists of the following:
{|class="wikitable"
!Offset
!Size
!Description
|-
|0x0
|4
|'''Magic''' FourCC
|-
|0x4
|4
|'''Version''' Always 2, no matter what game
|-
|0x8
|1
|{{unknown|Boolean?}}
|-
|0x9
|4
|{{unknown|Unknown}}
|}

=SNFO Chunk=
The SNFO header is simply a FourCC and the total length in bytes. Due to the fact that there is nothing in the header to determine which version of SCAN we're working with, we have to rely on the size of the SNFO chunk. If it's less than 0x0251 bytes, it's Metroid Prime 2. Otherwise it's Metroid Prime 3.

Other than that, SNFO is entirely unknown.

=Dependency List=
The dependency list follows the same format as [[DGRP (File Format)|DGRP]]
[[Category:File Formats]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Major research needed]]

Retro Modding Wiki - User contributions [en]

Materials (Metroid Prime)

SCAN (Metroid Prime)

SCAN (Metroid Prime 2)