rdpq_mode.c File Reference

RDP Command queue: mode setting. More...

Macros
#define	rdpq_mode_write(num_rdp_commands, num_frozen_rdp_commands, ...)
	Like rdpq_write, but for mode commands.

Functions
void	__rdpq_fixup_mode (uint32_t cmd_id, uint32_t w0, uint32_t w1)
	Write a fixup that changes the current render mode (8-byte command)
void	__rdpq_fixup_mode3 (uint32_t cmd_id, uint32_t w0, uint32_t w1, uint32_t w2)
	Write a fixup that changes the current render mode (12-byte command)
void	__rdpq_fixup_mode4 (uint32_t cmd_id, uint32_t w0, uint32_t w1, uint32_t w2, uint32_t w3)
	Write a fixup that changes the current render mode (16-byte command)
void	__rdpq_reset_render_mode (uint32_t w0, uint32_t w1, uint32_t w2, uint32_t w3)
	Write a fixup to reset the render mode.
void	rdpq_mode_push (void)
	Push the current render mode into the stack.
void	rdpq_mode_pop (void)
	Pop the current render mode from the stack.
void	__rdpq_set_mode_fill (void)
	Like rdpq_set_mode_fill, but without fill color configuration.
void	rdpq_set_mode_copy (bool transparency)
	Reset render mode to COPY type.
void	rdpq_set_mode_standard (void)
	Reset render mode to standard.
void	rdpq_set_mode_yuv (bool bilinear)
	Reset render mode to YUV mode.
void	rdpq_mode_begin (void)
	Start a batch of RDP mode changes.
void	rdpq_mode_end (void)
	Finish a batch of RDP mode changes.
void	rdpq_set_mode_fill (color_t color)
	Reset render mode to FILL type.
void	rdpq_mode_combiner (rdpq_combiner_t comb)
	Configure the color combiner.
void	rdpq_mode_blender (rdpq_blender_t blend)
	Configure the formula to use for blending.
void	rdpq_mode_antialias (rdpq_antialias_t mode)
	Activate antialiasing.
void	rdpq_mode_fog (rdpq_blender_t fog)
	Enable or disable fog.
void	rdpq_mode_dithering (rdpq_dither_t dither)
	Change dithering mode.
void	rdpq_mode_alphacompare (int threshold)
	Activate alpha compare feature.
void	rdpq_mode_zbuf (bool compare, bool write)
	Activate z-buffer usage.
void	rdpq_mode_zoverride (bool enable, float z, int16_t deltaz)
	Set a fixed override of Z value.
void	rdpq_mode_tlut (rdpq_tlut_t tlut)
	Activate palette lookup during drawing.
void	rdpq_mode_filter (rdpq_filter_t s)
	Activate texture filtering.
void	rdpq_mode_mipmap (rdpq_mipmap_t mode, int num_levels)
	Activate mip-mapping.
void	rdpq_mode_persp (bool perspective)
	Activate perspective correction for textures.

Detailed Description

RDP Command queue: mode setting.

Macro Definition Documentation

rdpq_mode_write

#define rdpq_mode_write	(		num_rdp_commands,
			num_frozen_rdp_commands,
			...
	)

Value:

    ({ \
    rdpq_write(rdpq_tracking.mode_freeze ? num_frozen_rdp_commands : num_rdp_commands, ##__VA_ARGS__); \
})

Like rdpq_write, but for mode commands.

During freeze (rdpq_mode_begin), mode commands don't emit RDP commands as they are batched instead, so we can avoid reserving space in the RDP static buffer in blocks.

Function Documentation

__rdpq_fixup_mode()

void __rdpq_fixup_mode	(	uint32_t	cmd_id,
		uint32_t	w0,
		uint32_t	w1
	)

Write a fixup that changes the current render mode (8-byte command)

All the mode fixups always need to update the RDP render mode and thus generate two RDP commands: SET_COMBINE and SET_OTHER_MODES.

rdpq_mode_push()

void rdpq_mode_push

(

void

)

Push the current render mode into the stack.

This function allows to push the current render mode into an internal stack. It allows to temporarily modify the render mode, and later recover its value.

This is effective on all render mode changes that can be modified via rdpq_mode_* function. It does not affect other RDP configurations such as the various colors.

The stack has 4 slots (including the current one).

rdpq_mode_pop()

void rdpq_mode_pop

(

void

)

Pop the current render mode from the stack.

This function allows to pop a previously pushed render mode from the stack, setting it as current again.

rdpq_set_mode_copy()

void rdpq_set_mode_copy

(

bool

transparency

)

Reset render mode to COPY type.

This function sets the render mode type to COPY, which is used to quickly blit bitmaps. In COPY mode, only texture rectangles (aka "sprites") can be drawn and no advanced render mode features are working (rdpq_mode_* functions).

The only available feature is transparency: pixels with alpha set to 0 can optionally be discarded during blit, so that the target buffer contents is not overwritten for those pixels. This is implemented using alpha compare.

The COPY mode is approximately 4 times faster at drawing than the standard mode, so make sure to enable it whenever it is possible.

Note

The COPY mode only works with 16-bpp framebuffers. It will trigger a hardware crash (!) on 32-bpp framebuffers, so avoid using it. The validator will warn you about this anyway.

Parameters

[in]

transparency

If true, pixels with alpha set to 0 are not drawn

See also

rdpq_set_mode_standard

rdpq_set_mode_standard()

void rdpq_set_mode_standard ( void  )

inline

Reset render mode to standard.

This is the most basic and general mode reset function. It configures the RDP processor in a standard and very basic way:

• Basic texturing (without shading)
• No dithering, antialiasing, blending, etc.

You can further configure the mode by calling one of the many functions in the mode API (rdpq_mode_*).

rdpq_set_mode_yuv()

void rdpq_set_mode_yuv

(

bool

bilinear

)

Reset render mode to YUV mode.

This is a helper function to configure a render mode for YUV conversion. In addition of setting the render mode, this function also configures a combiner (given that YUV conversion happens also at the combiner level), and set standard YUV parameters (for BT.601 TV Range).

After setting the YUV mode, you can load YUV textures to TMEM (using a surface with FMT_YUV16), and then draw them on the screen as part of triangles or rectangles.

Parameters

[in]

bilinear

If true, YUV textures will also be filtered with bilinear interpolation (note: this will require 2-cycle mode so it will be twice as slow).

rdpq_mode_begin()

void rdpq_mode_begin

(

void

)

Start a batch of RDP mode changes.

This function can be used as an optimization when changing render mode and/or multiple render states. It allows to batch the changes, so that RDP hardware registers are updated only once.

To use it, put a call to rdpq_mode_begin and rdpq_mode_end around the mode functions that you would like to batch. For instance:

rdpq_mode_begin();
    rdpq_set_mode_standard();
    rdpq_mode_mipmap(MIPMAP_INTERPOLATE, 2);
    rdpq_mode_dithering(DITHER_SQUARE_SQUARE);
    rdpq_mode_blender(RDPQ_BLENDING_MULTIPLY);
rdpq_mode_end();

The only effect of using rdpq_mode_begin is more efficient RSP and RDP usage, there is no semantic change in the way RDP is programmed when rdpq_mode_end is called.

Note

The functions affected by rdpq_mode_begin / rdpq_mode_end are just those that are part of the mode API (that is, rdpq_set_mode_* and rdpq_mode_*). Any other function is not batched and will be issued immediately.

rdpq_mode_end()

void rdpq_mode_end

(

void

)

Finish a batch of RDP mode changes.

This function completes a batch of changes started with rdpq_mode_begin.

See also

rdpq_mode_begin

rdpq_set_mode_fill()

void rdpq_set_mode_fill ( color_t  color )

externinline

Reset render mode to FILL type.

This function sets the render mode type to FILL, which is used to quickly fill portions of the screens with a solid color. The specified color is configured via rdpq_set_fill_color, and can be changed later.

Notice that in FILL mode most of the RDP features are disabled, so all other render modes settings (rdpq_mode_* functions) do not work.

Parameters

[in]

color

The fill color to use

rdpq_mode_combiner()

void rdpq_mode_combiner ( rdpq_combiner_t  comb )

externinline

Configure the color combiner.

This function allows to configure the color combiner formula to be used. The color combiner is the internal RDP hardware unit that mixes inputs from textures, colors and other sources and produces a RGB/Alpha value, that is then sent to the blender unit. If the blender is disabled (eg: the polygon is solid), the value produced by the combiner is the one that will be written into the framebuffer.

For common use cases, rdpq offers ready-to-use macros that you can pass to rdpq_mode_combiner: RDPQ_COMBINER_FLAT, RDPQ_COMBINER_SHADE, RDPQ_COMBINER_TEX, RDPQ_COMBINER_TEX_FLAT, RDPQ_COMBINER_TEX_SHADE.

For example, to draw a texture rectangle modulated with a flat color:

// Reset to standard rendering mode.
rdpq_set_mode_standard();
 
// Configure the combiner
rdpq_mode_combiner(RDPQ_COMBINER_TEX_FLAT);
 
// Configure the flat color that will modulate the texture
rdpq_set_prim_color(RGBA32(192, 168, 74, 255));
 
// Upload a texture into TMEM (tile descriptor #4)
rdpq_tex_upload(TILE4, &texture, 0);
 
// Draw the rectangle
rdpq_texture_rectangle(TILE4,
    0, 0, 32, 16,     // x0, y0, x1, y1
    0, 0, 1.0, 1.0f   // s, t, ds, dt
);

Alternatively, you can use your own combiner formulas, created with either RDPQ_COMBINER1 (one pass) or RDPQ_COMBINER2 (two passes). See the respective documentation for all the details on how to create a custom formula.

When using a custom formula, you must take into account that some render states also rely on the combiner to work. Specifically:

• Mipmap (rdpq_mode_mipmap): when activating interpolated mipmapping (MIPMAP_INTERPOLATE, also known as "trilinear filterig"), a dedicated color combiner pass is needed, so if you set a custom formula, it has to be a one-pass formula. Otherwise, a RSP assertion will trigger.
• Fog (rdpq_mode_fog): fogging is generally made by substituting the alpha component of the shade color with a depth value, which is then used in the blender formula (eg: RDPQ_FOG_STANDARD). The only interaction with the color combiner is that the SHADE alpha component should not be used as a modulation factor in the combiner, otherwise you get wrong results (if you then use the alpha for blending). rdpq automatically adjusts standard combiners using shade (RDPQ_COMBINER_SHADE and RDPQ_COMBINER_TEX_SHADE) when fog is enabled, but for custom combiners it is up to the user to take care of that.

Parameters

comb	The combiner formula to configure

See also

RDPQ_COMBINER1

RDPQ_COMBINER2

Note

For programmers with previous RDP programming experience: this function makes sure that the current cycle type can work correctly with the specified combiner formula. Specifically, it switches automatically between 1-cycle and 2-cycle depending on the formula being set and the blender unit configuration, and also automatically adapts combiner formulas to the required cycle mode. See the documentation in rdpq.c for more information.

rdpq_mode_blender()

void rdpq_mode_blender ( rdpq_blender_t  blend )

externinline

Configure the formula to use for blending.

This function can be used to configure the formula used in the blender unit.

The standard blending formulas are:

• RDPQ_BLENDER_MULTIPLY: multiplicative alpha blending using texture's alpha
• RDPQ_BLENDER_MULTIPLY_CONST: multiplicative alpha blending using a constant alpha
• RDPQ_BLENDER_ADDITIVE: additive alpha blending (mostly broken).

Normally, you would use RDPQ_BLENDER_MULTIPLY when your source texture has an internal alpha channel that you want to use for blending. Otherwise, if you just want to add a fixed-level semi-transparency to an existing texture, use RDPQ_BLENDER_MULTIPLY_CONST.

RDPQ_BLENDER_ADDITIVE is mostly broken on RDP, as it doesn't handle correctly overflowing values. Basically, values up to 1.5 are correctly clamped to 1, but values above 1.5 are wrapped back to 0, which makes the mode almost useless.

It is possible to also create custom formulas. The blender unit allows for up to two passes. Use RDPQ_BLENDER to create a one-pass blending formula, or RDPQ_BLENDER2 to create a two-pass formula.

Please notice that two-pass formulas are not compatible with fogging (rdpq_mode_fog). Also notice that rdpq_mode assumes that any formula that you set here (either one-pass or two-passes) does blend with the background. If you want to use a formula that does not blend with the background, set it via rdpq_mode_fog, otherwise you might get incorrect results when using anti-alias (see rdpq_mode_antialias).

The following example shows how to draw a texture rectangle using a fixed blending value of 0.5 (ignoring the alpha channel of the texture):

// Set standard mode
rdpq_set_mode_standard();
 
// Use blending with a constant semi-transparency value
rdpq_mode_blender(RDPQ_BLENDER_MULTIPLY_CONST);
 
// Configure the blending value to 128 (0.5). Notice that RGB
// values are ignored in this formula.
rdpq_set_fog_color(RGBA32(0,0,0, 128));
 
// Load a texture into TMEM
rdpq_tex_upload(TILE0, texture, 0);
 
// Draw it
rdpq_texture_rectangle(TILE0,
    0, 0, 64, 64,   // x0,y0 - x1,y1
    0, 0, 1.0, 1.0  // s0,t0 - ds,dt
);

Parameters

blend

Blending formula created with RDPQ_BLENDER, or 0 to disable.

See also

rdpq_mode_fog

RDPQ_BLENDER

RDPQ_BLENDER_MULTIPLY

RDPQ_BLENDER_MULTIPLY_CONST

RDPQ_BLENDER_ADDITIVE

rdpq_mode_antialias()

void rdpq_mode_antialias ( rdpq_antialias_t  mode )

externinline

Activate antialiasing.

This function can be used to enable/disable antialias at the RDP level. There are two different kinds of antialias on N64:

• Antialias on internal edges: this is fully performed by RDP.
• Antialias on external edges: this is prepared by RDP but is actually performed as a post-processing filter by VI.

This function activates both kinds of antialias, but to display correctly the second type, make sure that you did pass FILTERS_RESAMPLE_ANTIALIAS or FILTERS_RESAMPLE_ANTIALIAS_DEDITHER to display_init.

On the other hand, if you want to make sure that no antialias is performed, disable antialias with rdpq_mode_antialias(false) (which is the default for rdpq_set_mode_standard), and that will make sure that the VI will not do anything to the image, even if display_init was called with FILTERS_RESAMPLE_ANTIALIAS or FILTERS_RESAMPLE_ANTIALIAS_DEDITHER.

Note

Antialiasing internally uses the blender unit. If you already configured a formula via rdpq_mode_blender, antialias will just rely on that one to correctly blend pixels with the framebuffer. It is thus important that a custom formula configured via rdpq_mode_blender does blend with the background somehow.

Parameters

mode	Antialiasing mode to use (or AA_NONE to disable)

rdpq_mode_fog()

void rdpq_mode_fog ( rdpq_blender_t  fog )

externinline

Enable or disable fog.

This function enables fog on RDP. Fog on RDP is simulated in the following way:

• The T&L pipeline must calculate a depth information for each vertex of the primitive and put it into the alpha channel of the per-vertex color. This is outside of the scope of rdpq, so rdpq assumes that this has already been done when rdpq_mode_fog is called.
• The RDP blender unit is programmed to modulate a "fog color" with the polygon pixel, using SHADE_ALPHA as interpolation factor. Since SHADE_ALPHA contains a depth information, the farther the object, the stronger it will assume the fog color.

To enable fog, pass RDPQ_FOG_STANDARD to this function, and call rdpq_set_fog_color to configure the fog color. This is the standard fogging formula.

If you want, you can instead build a custom fogging formula using RDPQ_BLENDER. Notice that rdpq_mode assumes that the formula that you set with rdpq_mode_fog does not blend with the background; for that, use rdpq_mode_blender.

To disable fog, call rdpq_mode_fog passing 0.

Note

Fogging uses one pass of the blender unit (the first), so this can coexist with a blending formula (rdpq_mode_blender) as long as it's a single pass one (created via RDPQ_BLENDER). If a two-pass blending formula (RDPQ_BLENDER2) was set with rdpq_mode_blender, fogging cannot be used.

Parameters

fog	Fog formula created with RDPQ_BLENDER, or 0 to disable.

See also

RDPQ_FOG_STANDARD

rdpq_set_fog_color

RDPQ_BLENDER

rdpq_mode_blender

rdpq_mode_dithering()

void rdpq_mode_dithering ( rdpq_dither_t  dither )

externinline

Change dithering mode.

This function allows to change the dithering algorithm performed by RDP on RGB and alpha channels. Note that by default, rdpq_set_mode_standard disables any dithering.

See rdpq_dither_t for an explanation of how RDP applies dithering and how the different dithering algorithms work.

Parameters

dither

Dithering to perform

See also

rdpq_dither_t

rdpq_mode_alphacompare()

void rdpq_mode_alphacompare ( int  threshold )

externinline

Activate alpha compare feature.

This function activates the alpha compare feature. It allows to do per-pixel rejection (masking) depending on the value of the alpha component of the pixel. The value output from the combiner is compared with a configured threshold and if the value is lower, the pixel is not written to the framebuffer.

Moreover, RDP also support a random noise alpha compare mode, where the threshold value is calculated as a random number for each pixel. This can be used for special graphic effects.

Note

Alpha compare becomes more limited if antialiasing is enabled (both full and reduced, see rdpq_mode_antialias). In that case, any threshold value not equal to 0 will internally be treated as if 255 was specified. This implies that noise-based alpha compare is not supported under this condition.

Parameters

threshold

Threshold value. All pixels whose alpha is less than this threshold will not be drawn. Use 0 to disable. Use a negative value for activating the noise-based alpha compare.

rdpq_mode_zbuf()

void rdpq_mode_zbuf ( bool  compare, bool  update  )

externinline

Activate z-buffer usage.

Activate usage of Z-buffer. The Z-buffer surface must be configured via rdpq_set_z_image.

It is possible to separately activate the depth comparison (reading from the Z-buffer) and the Z update (writing to the Z-buffer).

Parameters

compare	True if per-pixel depth test must be performed
update	True if per-pixel depth write must be performed

See also

rdpq_set_z_image

rdpq_mode_zoverride()

void rdpq_mode_zoverride ( bool  enable, float  z, int16_t  deltaz  )

externinline

Set a fixed override of Z value.

This function activates a special mode in which RDP will use a fixed value of Z for the next drawn primitives. This works with both rectangles (rdpq_fill_rectangle and rdpq_texture_rectangle) and triangles (rdpq_triangle).

If a triangle is drawn with per-vertex Z while the Z-override is active, the per-vertex Z will be ignored.

Parameters

enable	Enable/disable the Z-override mode
z	Z value to use (range 0..1)
deltaz	DeltaZ value to use.

See also

rdpq_set_prim_depth_raw

rdpq_mode_tlut()

void rdpq_mode_tlut ( rdpq_tlut_t  tlut )

externinline

Activate palette lookup during drawing.

This function allows to enable / disable palette lookup during drawing. Uploading a palette to TMEM can be done via rdpq_tex_upload_tlut, or lower-level functions such as rdpq_load_tlut_raw.

Parameters

tlut	Palette type, or 0 to disable.

See also

rdpq_tex_upload

rdpq_tex_upload_tlut

rdpq_tlut_t

rdpq_mode_filter()

void rdpq_mode_filter ( rdpq_filter_t  filt )

externinline

Activate texture filtering.

This function allows to configure the kind of texture filtering that will be used while sampling textures.

Available in render modes: standard, copy.

Parameters

filt	Texture filtering type

See also

rdpq_filter_t

rdpq_mode_mipmap()

void rdpq_mode_mipmap ( rdpq_mipmap_t  mode, int  num_levels  )

externinline

Activate mip-mapping.

This function can be used to turn on mip-mapping.

TMEM must have been loaded with multiple level of details (LOds) of the texture (a task for which rdpq is currently missing a helper, so it has to be done manually). Also, multiple consecutive tile descriptors (one for each LOD) must have been configured.

If you call rdpq_triangle when mipmap is active via rdpq_mode_mipmap, pass 0 to the number of mipmaps in rdpq_trifmt_t, as the number of levels set here will win over it.

Parameters

mode	Mipmapping mode (use MIPMAP_NONE to disable)
num_levels	Number of mipmap levels to use. Pass 0 when setting MIPMAP_NONE.

rdpq_mode_persp()

void rdpq_mode_persp ( bool  perspective )

externinline

Activate perspective correction for textures.

This function enables or disables the perspective correction for texturing. Perspective correction does not slow down rendering, and thus it is basically free.

To be able to use perspective correction, make sure to pass the Z and W values in the triangle vertices.

Parameters

perspective

True to activate perspective correction, false to disable it.