Internal Registers

GPU internal registers are written to through GPU commands. They are used to control the GPU’s behavior, that is to say tell it to draw stuff and how we want it drawn.

Each command is at least 8 bytes wide. The first word is the command parameter and the second word constitutes the command header. Optionally, more parameter words may follow (potentially including a padding word to align commands to multiples of 8 bytes).

In the simplest case, a command is exactly 8 bytes wide. You can think of such a command as writing the parameter word to an internal register (the index of which is given in the command header). The more general case where more than one parameter word is given is equivalent to multiple simple commands (one for each parameter word). If consecutive writing mode is enabled in the command header, the current command index will be incremented after each parameter write. Otherwise, the parameters will be consecutively written to the same register.

For example, the sequence “0xAAAAAAAA 0x802F011C 0xBBBBBBBB 0xCCCCCCCC” is equivalent to a call to commands 0xF011C with parameter 0xAAAAAAAA, 0xF011D with parameter 0xBBBBBBBB and 0xF011E with parameter 0xCCCCCCCC. If consecutive writing mode were disabled, the command would be equivalent to three consecutive calls to 0xF011C (once with parameter 0xAAAAAAAA, once with 0xBBBBBBBB, and finally with 0xCCCCCCCC).

Invalid GPU command parameters including NaN floats can cause the GPU to hang, which then causes the GSP module to hang as well.

The size of GPU command buffers must be 0x10-byte aligned; the lower 3 bits of the size are cleared. A common pitfall is having the finalization command (write to register 0x0010) not executed because it was the last 8 bytes of a non-0x10 byte aligned command buffer, and having the GPU hang as a result.

Using a value other than 0xF, parts of a word in internal GPU memory can be updated without touching the other bits of it. For example, setting bit 16 to zero indicates that the least significant byte of the parameter will not be overwritten, setting bit 17 to zero indicates that the parameter’s second LSB will not be overwritten, etc. This means that for instance commands 0x00010107 and 0x00020107 refer to the same thing but write different parts of the parameter.

There are three main types of registers :

• configuration registers, which directly map to various rendering properties (for example: GPUREG_FACECULLING_CONFIG)
• data transfer registers, which can be seen as FIFOs that let us send sequential chunks of data to the GPU, such as shader code or 1D samplers (for example: GPUREG_GSH_CODETRANSFER_DATA)
• action triggering registers, which tell the GPU to do something, like draw a primitive (for example: GPUREG_DRAWARRAYS)

It is possible for multiple register (sequential) IDs to correspond to the same register. This is done to leverage the consecutive writing mode for GPU commands, which makes it possible for a single command to write data to multiple sequential register IDs. For example, register IDs 02C1 through 02C8 all correspond to GPUREG_VSH_FLOATUNIFORM_DATAi so that a consecutively writing command based at 02C0 will write its first parameter to GPUREG_VSH_FLOATUNIFORM_INDEX and ever subsequent ones to GPUREG_VSH_FLOATUNIFORM_DATAi

Writing to this register seems to signal the GPU to stop processing GPU commands from the current buffer; any command following a write to this register will be ignored. The value written to this register does not appear to matter, although 0x12345678 is the value typically written by commercial software. Failure to write to this register in any command buffer will result in the GPU hanging.

This register is used to configure the face culling mode.

Culling mode values:

This register is used to configure the viewport width, along with GPUREG_VIEWPORT_INVW.

This register is used to configure the viewport width, along with GPUREG_VIEWPORT_WIDTH.

This register is used to configure the viewport height, along with GPUREG_VIEWPORT_INVH.

This register is used to configure the viewport height, along with GPUREG_VIEWPORT_HEIGHT.

This register is used to enable clipping planes.

This register is used to configure clipping plane coefficients.

This register is used to configure the depth range scale.

This register is used to configure the depth range bias.

This register is used to configure the total shader output map attributes.

These registers map components of the corresponding vertex shader output register to specific fixed-function semantics.

Semantics that have not been mapped to a component of an output register have a value of 1

Semantic values:

This register configures the early depth test function.

Early depth function values:

This register sets whether the early depth test is enabled.

This register triggers clearing the early depth data.

This register is used to configure the shader output attribute mode.

This register is used to enable scissor testing.

This register is used to configure the scissor test start position.

This register is used to configure the scissor test end position.

This register is used to configure the viewport position.

This register is used to configure the early depth clear value.

This register is used to enable depth range.

This register is used to configure the output framebuffer dimensions.

This register controls the clock supply to parts relating to certain attributes.

This register is used to enable texture units.

Texture 3 coordinates values:

Texture 2 coordinates values:

This register is used to set a texture unit’s border color.

This register is used to set a texture unit’s dimensions.

This register is used to set a texture unit’s extra parameters.

Filter values:

Wrap values:

Type values:

This register is used to configure a texture unit’s level of detail.

First ADDR register:

Subsequent ADDR registers:

This register is used to set a texture unit’s physical address(es) in memory. Individual texels in a texture are laid out in memory as a 🔗 Z-order curve. Mipmap data is stored directly following the main texture data.

If the texture is a cube:

Otherwise, ADDR(1) points to a 2D texture, and the rest are empty.

This register is used to set a texture unit’s shadow texture properties.

This register is used to set a texture unit’s data format.

Format values:

This register is used to enable lighting.

This register is used to configure the procedural texture unit.

Clamp values:

Mapping function values:

Shift values:

This register is used to configure the procedural texture unit’s U-direction noise amplitude/phase.

This register is used to configure the procedural texture unit’s V-direction noise amplitude/phase.

This register is used to configure the procedural texture unit’s U-direction and V-direction noise frequency.

This register is used to configure the procedural texture unit.

Minification filter values:

This register is used to set the procedural texture unit’s offset. Mipmap level 4-7 seems to be hardcoded at offset 0xF0, 0xF8, 0xFC and 0xFE .

This register is used to set which look-up table to write to, with GPUREG_PROCTEX_LUT_DATAi, at what index.

Reference table values:

These registers behave as a FIFO queue. Each write to these registers writes the provided value to the table selected with GPUREG_PROCTEX_LUT, starting at the selected index.

128 elements:

128 elements:

128 elements:

256 elements:

256 elements:

This register configures a texture combiner’s sources.

Source values:

Using previous source in the first TEV stage returns the primary color, while previous buffer returns zero.

This register configures a texture combiner’s operands.

RGB operand values:

Alpha operand values:

This register configures a texture combiner’s combine mode.

Combine values:

This register configures a texture combiner’s constant color.

This register configures a texture combiner’s scale value.

Scale values:

This register is shared between the gas/fog mode configuration and texture combiner buffer inputs. Texture combiner buffer inputs are typically written with a mask of 0x2, and the gas/fog mode configuration is typically written with a mask of 0x5.

Fog mode values:

Shading density source values:

Buffer input values:

This register is used to configure the color of fog.

This register is used to configure the gas density attenuation.

This register is used to configure the gas maximum density accumulation.

This register is used to set what index to write to with GPUREG_FOG_LUT_DATAi.

These registers behave as a FIFO queue. Each write to these registers writes the provided value to the fog look-up table, starting at the index selected with GPUREG_FOG_LUT_INDEX.

128 elements:

This register is used to configure the texture combiner buffer color.

This register is used to configure the fragment operation mode and whether to use logic ops or blending.

Fragment operation mode values:

Blend mode values:

This register is used to configure the blending function.

Equation values:

Blend equations 5, 6, 7 appear to behave the same as blend equation 0 (Add)

Function values:

This register is used to configure the logic op.

Logic op values:

This register is used to configure the blending color.

This register is used to configure alpha testing.

Function values:

This register is used to configure stencil testing.

Function values:

This register is used to configure stencil result operations.

Operation values:

This register is used to depth testing and framebuffer write masking.

Note that setting the “Depth test enabled” bit to 0 will not also disable depth writes. It will instead behave as if the depth function were set to “Always”. To completely disable depth-related operations both the depth test and depth write bits must be disabled.

Depth function values:

Writing 1 to this register invalidates the framebuffer cache. This should be done when changing the framebuffer or when it is cleared before rendering. Note that it does not flush the cache, so it should always be preceded by a write to GPUREG_FRAMEBUFFER_FLUSH.

Writing 1 to this register flushes the framebuffer cache to memory. This should be done after rendering before changing the framebuffer or using rendering results.

This register configures read access from the color buffer.

This register configures write access to the color buffer.

This register configures read access from the depth and stencil buffers.

This register configures write access to the depth and stencil buffers.

This register configures the depth buffer data format.

Format values:

This register configures the color buffer data format. Color components are laid out in reverse byte order in memory, with the most significant bits used first.

Pixel size values:

Format values:

This register enables the early depth test.

This register configures the framebuffer block mode. To untile the color buffer when using the 32x32 block format, use bit 16 of the display transfer flags. It is unknown if there are any advantages to using the 32x32 format.

Render block mode values:

This register configures the depth buffer physical address.

This register configures the color buffer physical address.

This register configures the framebuffer dimensions.

This register configures gas light planar shading.

This register configures gas light view shading.

This register configures gas light shading in the line-of-sight direction, and the input to the gas color LUT.

Color LUT input values:

This register is used to set what index to write to with GPUREG_GAS_LUT_DATAi.

These registers behave as a FIFO queue. Each write to these registers writes the provided value to the gas look-up table, starting at the index selected with GPUREG_GAS_LUT_INDEX.

16 elements:

First 8 elements:

Last 8 elements:

This register is used to configure the gas depth direction attenuation proportion, as well as the gas depth function.

Gas depth function values:

This register is used to configure shadow properties.

These registers contain the specular0 color of the corresponding light. Usually set to material_specular0*lightX_specular0.

These registers contain the specular1 color of the corresponding light. Usually set to material_specular1*lightX_specular1.

These registers contain the diffuse color of the corresponding light. Usually set to material_diffuse*lightX_diffuse.

These registers contain the ambient color of the corresponding light. Usually set to material_ambient*lightX_ambient.

These registers (along with GPUREG_LIGHTi_Z) represent the light position (for a positional light) or the light direction vector (for a directional light) of the corresponding light.

These registers (along with GPUREG_LIGHTi_XY) represent the light position (for a positional light) or the light direction vector (for a directional light) of the corresponding light.

These registers (along with GPUREG_LIGHTi_SPOTDIR_Z) represent the spot direction (unitary) vector of the corresponding light.

These registers (along with GPUREG_LIGHTi_SPOTDIR_XY) represent the spot direction (unitary) vector of the corresponding light.

This register configures a light’s properties.

These registers contain the distance attenuation bias value of the corresponding light. The attenuation factor is DA(clip(bias + scale*distance, 0.0, 1.0)).

These registers contain the distance attenuation scale value of the corresponding light. The attenuation factor is DA(clip(bias + scale*distance, 0.0, 1.0)).

This register contains the initial value of the fragment primary color before the partial colors that correspond to each enabled light are added. Usually set to material_emission + material_ambient*scene_ambient.

This register configures the number of active lights.

This register configures the light environment.

Fresnel selector values:

The light environment configuration controls which LUTs are available for use. If a LUT is not available in the selected configuration, its value will always read a constant 1.0 regardless of the enable state in GPUREG_LIGHTING_CONFIG1. If RR is enabled but not RG or RB, the output of RR is used for the three components; Red, Green and Blue.

Light environment configuration values:

Bump mode values:

This register is used to disable various aspects of the light environment.

This register controls which LUT and what offset into it the GPUREG_LIGHTING_LUT_DATAi register writes to.

Lookup table values:

This register is set to 1 when fragment lighting is disabled, and to 0 when it is enabled.

Lighting LUT data is written here.

A LUT contains data for the input domain [-1.0, 1.0], which is indexed using a signed 8-bit number [-128, 127]. Therefore a LUT contains 256 entries. The index of a value is (int)(x/127.0f) & 0xFF.

DA: The input domain is [0.0, 1.0], and the index is an unsigned 8-bit number [0, 255] instead.

Format of an entry: