Wii Graphics Code/Blitting Processor

From Custom Mario Kart
Jump to: navigation, search

The blitting processor of the Wii's Hollywood GPU is responsible for applying materials to polygons that will be drawn. In the case of MDL0 files, this processor is mostly used for shader operations. Those operations control the texture map and coordinates to use, the color channel to use and how they are all blended together. MDL0 files access this processor directly by using Wii Graphics Code, whereas many other operations are hardcoded in the game code.

Register overview

The blitting processor has 82 known variables that are used for a large variety of tasks. The variables that are accessed by materials and shaders inside MDL0 files are as listed below:

Address Name
0x06 - 0x0E Three 2x3 indirect texture matrices
0x10 - 0x1F Indirect texture stages
0x25, 0x26 Indirect texture scale
0x27 Indirect texture references
0x28 - 0x2F Texture references
0x40 Z mode
0x41 Alpha blend mode
0x42 Constant alpha
0xC0 - 0xCE Color blending per TEV stage
0xC1 - 0xCF Alpha blending per TEV stage
0xE0 - 0xE7 Shader colors
0xF3 Alpha test
0xF6 - 0xFD Color table selection per stage
0xFE Mask for next load operation

Material operations

Each material has a number of load calls to set variables used during blending. Variables in the blitting processor are used to control indirect texture matrices, scale and references, texture references, z mode, alpha blend mode and constant alpha. Each material also sets 3 hardcoded colors and 4 constant colors that may be used by the TEV stages. What each variable is used for is explained in the following sections. All tables are ordered from LSB to MSB.

Indirect texture matrix

Offset Size Description
0x0D 11 First row value
0x02 11 Second row value
0x00 2 Scale bits

At address 0x06 in the memory three 2x3 indirect texture matrices are stored together with a scale factor for each of them. To set a matrix three load operations are peformed, one for each column. Each load operation also sets two bits of the six bit scale factor is set; the first column sets the least significant bits, the third column sets the most significant bits. This matrix may be used to transform the texture coordinates of an indirect texture in an indirect texture stage.

The address of the command determines which column of which matrix is set. Addresses 0x06, 0x07 and 0x08 are used for columns one, two and three respectively of matrix 0, addresses 0x09, 0x0A and 0x0B are used for matrix 1 and 0x0C, 0x0D and 0x0E for matrix 2.

Indirect texture scale

Offset Size Description
0x14 4 S Scale stage 0
0x10 4 T Scale stage 0
0x0C 4 S Scale stage 1
0x08 4 T Scale stage 1

Sets the scale of the indirect texture map for each stage. Address 0x25 sets the scale for stages 0 and 1, 0x26 sets the scale for stages 2 and 3. The coordinates are bitwise shifted right by the scale value, which means that actual scale factor is a negative power of two.

Z mode

Offset Size Description
0x17 1 Enable depth test
0x14 3 Compare operation
Value Description
0 Never
1 Less than
2 Equal to
3 Less or equal
4 Greater than
5 Not equal to
6 Greater or equal
7 Always
0x13 1 Enable depth update

Z-buffering settings. Determines which object should be drawn in front.

Alpha blend mode

Offset Size Description
0x17 1 Enable blend
0x16 1 Enable logic operation
0x15 1 Enable dither
0x14 1 Enable color update
0x13 1 Enable alpha update
0x10 3 Destination factor
Value Description
0 Zero
1 One
2 Source color
3 Inverted source color
4 Destination color
5 Inverted destination color
6 Source alpha
7 Inverted source alpha
0x0D 3 Source factor (same values as destination factor)
0x0C 1 Subtract
0x08 4 Logic operation
Value Description
0 CLEAR
1 AND
2 AND_REVERSE
3 COPY
4 AND_INVERTED
5 NOOP
6 XOR
7 OR
8 NOR
9 EQUIV
10 INVERT
11 OR_REVERSE
12 COPY_INVERTED
13 OR_INVERTED
14 NAND
15 SET

Sets the blending mode. How blending mode exactly affects blending is unknown.

Constant alpha

Offset Size Description
0x17 1 Enable
0x0F 8 Alpha value

If enabled, the output alpha of the TEV result will always be changed to the number provided by this load function.

Shader colors

Offset Size Description
0x0D 11 Red/Blue
0x0C 1 Unused
0x01 11 Alpha/Green
0x00 1 Constant

Sets color variables that can be used by each TEV stage. If the LSB of the address is 0, then red and alpha are set, otherwise blue and green are set. If the constant bit is set, a constant color is set instead of a regular color. Although the addresses together can hold only four colors, they can still be used to set the three regular colors and four constant colors supported by the TEV stage combiners thanks to the constant bit, it will map internally to the right variable. In the case of regular colors addresses 0xe0 and 0xe1 remain unused, so 0xe2 and 0xe3 are used to set the first color.

Alpha test

Offset Size Description
0x10 8 Ref 0
0x08 8 Ref 1
0x05 3 Comp 0
0x02 3 Comp 1
0x00 2 Logic

Comp 0 and 1 can have the following values:

Value Description
0 Never
1 Less than
2 Equal to
3 Less or equal
4 Greater than
5 Not equal to
6 Greater or equal
7 Always

Logic can have the following values:

Value Description
0 And
1 Or
2 Xor
3 Xnor

Alpha function; if this function returns true, a pixel is drawn. Given a pixel alpha z, the formula is as follows: z <comp0> <ref0> <logic> z <comp1> <ref1>. An example value would be: z > 80 && z ≤ 255.

Shader operations

Indirect texture stage

Offset Size Description
0x16 2 Indirect tex stage ID
0x14 2 Indirect texture coordinate format
Value Description
0 8-bit coordinates
1 5-bit coordinates
2 4-bit coordinates
3 3-bit coordinates
0x11 3 S (LSB), T and U (MSB) bias
0x0F 2 Bump alpha axis
Value Description
0 Disabled
1 S
2 T
3 U
0x0B 4 Indirect texture matrix
Value Description
0 No matrix
1 Matrix 0
2 Matrix 1
3 Matrix 2
0x08 3 S wrapping factor
0x05 3 T wrapping factor
0x04 1 Use unmodified LOD
0x03 1 Add previous TEV stage tex coordinates

Each address in range 0x10 - 0x1F contains an indirect texture TEV stage. Indirect textures are used to generate a new texture mapping grid that is altered by the provided texture and its mapping. This technique is mostly used to generate bump or normal maps on materials, which makes faces seem to have more detail than they really have. The provided matrix is multiplied with the green and blue color values of the indirect texture to shift the texture mapping. An indirect texture stage only affects the current TEV stage, no other TEV stages are affected directly.

Indirect texture references

Offset Size Description
0x15 3 Stage 0 texture
0x12 3 Stage 0 texture coords
0x0F 3 Stage 1 texture
0x0C 3 Stage 1 texture coords
0x09 3 Stage 2 texture
0x06 3 Stage 2 texture coords
0x03 3 Stage 3 texture
0x00 3 Stage 3 texture coords

All texture maps and coordiates for the four indirect texture stages are set at this address. The texture ID is a material layer index which references a texture by name. So if the provided material has layers for TexA, TexB and TexC, a value of 2 will load TexB. The texture coords value references one of the coordinates set in the object section. All references at this address are then used by one or more indirect texture stages for further calculations, the stage ID value is used as index in this table.

Texture references

Offset Size Description
0x0E 10 Stage 0 data
0x02 10 Stage 1 data

The 10-bit data blocks have the following layout:

Offset Size Description
0x08 3 Stage texture map
0x04 3 Stage texture coords
0x03 1 Stage texture enabled
0x00 3 Stage color channel
Value Description
0 Light channel 0
1 Light channel 1
5 Bump alpha
6 Normalized bump alpha

Other values disable the color channel for this stage.

Sets the texture map, texture coordinate and color channel for each TEV stage. At each address the texture references for two stages are set: 0x28 sets stage 0 and stage 1, 0x29 sets stage 2 and stage 3, etc. In total there can be eight stages. Similarly to the indirect texture stage, the texture map is a material layer index and the texture coords are a reference to one of the uv maps set in the object section. Offset 0x03 of the texture data block is used to enable or disable the texture drawing. The stage color channel sets the channel that will be used as raster color. Light channel 0 is often used as vertex color. The bump alpha is the value set by offset 0x0F at the indirect texture stage address, this value can be used to add shadow detail to faces whereas indirect texture maps on their own can only affect texture coordinates.

Color TEV stage

Offset Size Description
0x14 4 Argument A
0x10 4 Argument B
0x0C 4 Argument C
0x08 4 Argument D
0x06 2 Bias
Value Description
0 Zero
1 Add half
2 Subtract half
3 Special case
0x05 1 Operation
Value Description
0 Addition
1 Subtraction
0x04 1 Clamp
0x02 2 Shift
Value Description
0 Multiply by 1
1 Multiply by 2
2 Multiply by 4
3 Divide by 2
0x00 2 Destination
Value Description
0 Pixel output
1 Temp 0
2 Temp 1
3 Temp 2

The four four-bit arguments can have the following values:

Value Description
0 Pixel output
1 Pixel output alpha
2 Temp0
3 Temp0 alpha
4 Temp1
5 Temp1 alpha
6 Temp2
7 Temp2 alpha
8 Texture color
9 Texture alpha
10 Raster color
11 Raster alpha
12 One (white)
13 Half
14 Constant color
15 Zero (black)

This operation is the meat of each shader. It controls how colours are blended together and what is finally shown on the screen. Each shader stage has one such operation, each shader can have up to 8 stages. The texture color and raster (light channel) color are determined by the references set by the operation above. The input to Argument D is a bias, this value is always taken as base before further blending occurs. The bias value is added to argument D if it isn't set to 3.

If bias is below 3, a linear interpolation is performed over arguments A and B for argument C as parameter. If argument C is zero, then the result is argument A. If argument C is one, then it is argument B. The formula is as follows: lerp(a,b,c) = a + (b - a) * c. It can also be written as a * c + (1 - c) * b. The result of this function is either subtracted or added (depending on the operation bit) to the sum of argument D and the bias. Finally the shift operation is performed over this result and the result is moved to the destination. The final formula is: destination = shift * (bias + d op lerp(a,b,c)).

If bias is set to special case, then a comparison is performed between arguments A and B. If the comparison returns true, then argument C is returned. Otherwise black. The type of comparison depends on the values of shift and operation. The possible values for bitset ss|o (shift * 2 + operation) are:

Value Description
0 ArgA.red > ArgB.red
1 ArgA.red == ArgB.red
2 ArgA.rg > ArgB.rg
3 ArgA.rg == ArgB.rg
4 ArgA.rgb > ArgB.rgb
5 ArgA.rgb == ArgB.rgb
6 ArgA > ArgB (per channel)
7 ArgA == ArgB (per channel)

In the case of values 2 to 5, the blue comparison gets priority over green and red. If the blue channel is equal for both arguments, then the green channel is compared. Likewise green gets priority over red. 6 and 7 compare each channel individually.

Alpha TEV Stage

The alpha TEV stage combiner works the same as the color TEV stage combiner. The only difference is the format of the least significant 16 bits of the data structure:

Offset Size Description
0x16 2 Rswap
0x14 2 Lswap
0x11 3 Argument A
0x0E 3 Argument B
0x0B 3 Argument C
0x08 3 Argument D

The four three-bit arguments can have the following values:

Value Description
0 Pixel output
1 Temp0
2 Temp1
3 Temp2
4 Texture alpha
5 Raster alpha
6 Constant alpha
7 Zero

The Rswap and Lswap values are references to the color swap tables. The special case works the same as the color combiner special case, so the comparisons will be done on the color channels.