![]() |
libdragon
|
RDP Command queue: mode setting. More...
Macros | |
#define | rdpq_mode_write(num_rdp_commands, ...) |
Like rdpq_write, but for mode commands. More... | |
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) More... | |
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. More... | |
void | rdpq_mode_pop (void) |
Pop the current render mode from the stack. More... | |
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. More... | |
void | rdpq_set_mode_standard (void) |
Reset render mode to standard. More... | |
void | rdpq_set_mode_yuv (bool bilinear) |
Reset render mode to YUV mode. More... | |
void | rdpq_mode_begin (void) |
Start a batch of RDP mode changes. More... | |
void | rdpq_mode_end (void) |
Finish a batch of RDP mode changes. More... | |
void | rdpq_set_mode_fill (color_t color) |
Reset render mode to FILL type. More... | |
void | rdpq_mode_combiner (rdpq_combiner_t comb) |
Configure the color combiner. More... | |
void | rdpq_mode_blender (rdpq_blender_t blend) |
Configure the formula to use for blending. More... | |
void | rdpq_mode_antialias (rdpq_antialias_t mode) |
Activate antialiasing. More... | |
void | rdpq_mode_fog (rdpq_blender_t fog) |
Enable or disable fog. More... | |
void | rdpq_mode_dithering (rdpq_dither_t dither) |
Change dithering mode. More... | |
void | rdpq_mode_alphacompare (int threshold) |
Activate alpha compare feature. More... | |
void | rdpq_mode_zbuf (bool compare, bool write) |
Activate z-buffer usage. More... | |
void | rdpq_mode_zoverride (bool enable, float z, int16_t deltaz) |
Set a fixed override of Z value. More... | |
void | rdpq_mode_tlut (rdpq_tlut_t tlut) |
Activate palette lookup during drawing. More... | |
void | rdpq_mode_filter (rdpq_filter_t s) |
Activate texture filtering. More... | |
void | rdpq_mode_mipmap (rdpq_mipmap_t mode, int num_levels) |
Activate mip-mapping. More... | |
void | rdpq_mode_persp (bool perspective) |
Activate perspective correction for textures. More... | |
RDP Command queue: mode setting.
#define rdpq_mode_write | ( | num_rdp_commands, | |
... | |||
) |
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.
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.
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).
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.
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.
[in] | transparency | If true, pixels with alpha set to 0 are not drawn |
|
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:
You can further configure the mode by calling one of the many functions in the mode API (rdpq_mode_*
).
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.
[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). |
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:
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.
rdpq_set_mode_*
and rdpq_mode_*
). Any other function is not batched and will be issued immediately. void rdpq_mode_end | ( | void | ) |
Finish a batch of RDP mode changes.
This function completes a batch of changes started with rdpq_mode_begin.
|
inline |
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.
[in] | color | The fill color to use |
|
inline |
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:
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:
comb | The combiner formula to configure |
|
inline |
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:
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):
blend | Blending formula created with RDPQ_BLENDER, or 0 to disable. |
|
inline |
Activate antialiasing.
This function can be used to enable/disable antialias at the RDP level. There are two different kinds of antialias on N64:
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.
mode | Antialiasing mode to use (or AA_NONE to disable) |
|
inline |
Enable or disable fog.
This function enables fog on RDP. Fog on RDP is simulated in the following way:
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.
fog | Fog formula created with RDPQ_BLENDER, or 0 to disable. |
|
inline |
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.
dither | Dithering to perform |
|
inline |
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.
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. |
|
inline |
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).
compare | True if per-pixel depth test must be performed |
update | True if per-pixel depth write must be performed |
|
inline |
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.
enable | Enable/disable the Z-override mode |
z | Z value to use (range 0..1) |
deltaz | DeltaZ value to use. |
|
inline |
Activate palette lookup during drawing.
This function allows to enable / disable palette lookup during drawing. To draw using a texture with palette, it is necessary to first load the texture into TMEM (eg: via rdpq_tex_upload), then load the palette (eg: via rdpq_tex_upload_tlut), and finally activate the palette drawing mode via rdpq_mode_tlut.
tlut | Palette type, or 0 to disable. |
|
inline |
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.
filt | Texture filtering type |
|
inline |
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.
mode | Mipmapping mode (use MIPMAP_NONE to disable) |
num_levels | Number of mipmap levels to use. Pass 0 when setting MIPMAP_NONE. |
|
inline |
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.
perspective | True to activate perspective correction, false to disable it. |