![]() |
libdragon
|
RDP Command queue. More...
Go to the source code of this file.
Data Structures | |
struct | rdpq_tileparms_t |
Tile parameters for rdpq_set_tile. More... | |
struct | rdpq_tileparms_t.s |
struct | rdpq_tileparms_t.t |
Macros | |
#define | RDPQ_OVL_ID (0xC << 28) |
Static overlay ID of rdpq library. More... | |
#define | RDPQ_CFG_AUTOSYNCPIPE (1 << 0) |
Configuration flag: enable automatic generation of SYNC_PIPE commands. | |
#define | RDPQ_CFG_AUTOSYNCLOAD (1 << 1) |
Configuration flag: enable automatic generation of SYNC_LOAD commands. | |
#define | RDPQ_CFG_AUTOSYNCTILE (1 << 2) |
Configuration flag: enable automatic generation of SYNC_TILE commands. | |
#define | RDPQ_CFG_AUTOSCISSOR (1 << 3) |
Configuration flag: enable automatic generation of SET_SCISSOR commands on render target change. | |
#define | RDPQ_CFG_DEFAULT (0xFFFF) |
Configuration flag: default configuration. | |
#define | RDPQ_TILE_INTERNAL TILE7 |
Tile descriptor internally used by some RDPQ functions. Avoid using if possible. | |
#define | rdpq_set_scissor(x0, y0, x1, y1) |
Configure a scissoring rectangle in screen coordinates (RDP command: SET_SCISSOR) More... | |
#define | rdpq_load_tile(tile, s0, t0, s1, t1) |
Load a portion of a texture into TMEM (RDP command: LOAD_TILE) More... | |
#define | rdpq_set_tile_size(tile, s0, t0, s1, t1) |
Configure the extents of a tile descriptor (RDP command: SET_TILE_SIZE) More... | |
#define | RDPQ_AUTOTMEM (0x8000) |
Special TMEM address to pass to rdpq_set_tile to use automatic TMEM allocation. | |
#define | RDPQ_AUTOTMEM_REUSE(offset) (0x4000 | ((offset)/8)) |
Special TMEM address to pass to rdpq_set_tile to configure a tile with the same address of previous tile. | |
#define | rdpq_write(num_rdp_commands, ovl_id, cmd_id, ...) |
Enqueue a RSP command that also generates RDP commands. More... | |
Enumerations | |
enum | { RDPQ_CMD_NOOP = 0x00 , RDPQ_CMD_SET_LOOKUP_ADDRESS = 0x01 , RDPQ_CMD_FILL_RECTANGLE_EX = 0x02 , RDPQ_CMD_RESET_RENDER_MODE = 0x04 , RDPQ_CMD_SET_COMBINE_MODE_2PASS = 0x05 , RDPQ_CMD_PUSH_RENDER_MODE = 0x06 , RDPQ_CMD_POP_RENDER_MODE = 0x07 , RDPQ_CMD_TRI = 0x08 , RDPQ_CMD_TRI_ZBUF = 0x09 , RDPQ_CMD_TRI_TEX = 0x0A , RDPQ_CMD_TRI_TEX_ZBUF = 0x0B , RDPQ_CMD_TRI_SHADE = 0x0C , RDPQ_CMD_TRI_SHADE_ZBUF = 0x0D , RDPQ_CMD_TRI_SHADE_TEX = 0x0E , RDPQ_CMD_TRI_SHADE_TEX_ZBUF = 0x0F , RDPQ_CMD_TEXTURE_RECTANGLE_EX = 0x10 , RDPQ_CMD_SET_DEBUG_MODE = 0x11 , RDPQ_CMD_SET_SCISSOR_EX = 0x12 , RDPQ_CMD_SET_PRIM_COLOR_COMPONENT = 0x13 , RDPQ_CMD_MODIFY_OTHER_MODES = 0x14 , RDPQ_CMD_SET_FILL_COLOR_32 = 0x16 , RDPQ_CMD_SET_BLENDING_MODE = 0x18 , RDPQ_CMD_SET_FOG_MODE = 0x19 , RDPQ_CMD_SET_COMBINE_MODE_1PASS = 0x1B , RDPQ_CMD_AUTOTMEM_SET_ADDR = 0x1C , RDPQ_CMD_AUTOTMEM_SET_TILE = 0x1D , RDPQ_CMD_TRIANGLE = 0x1E , RDPQ_CMD_TRIANGLE_DATA = 0x1F , RDPQ_CMD_TEXTURE_RECTANGLE = 0x24 , RDPQ_CMD_TEXTURE_RECTANGLE_FLIP = 0x25 , RDPQ_CMD_SYNC_LOAD = 0x26 , RDPQ_CMD_SYNC_PIPE = 0x27 , RDPQ_CMD_SYNC_TILE = 0x28 , RDPQ_CMD_SYNC_FULL = 0x29 , RDPQ_CMD_SET_KEY_GB = 0x2A , RDPQ_CMD_SET_KEY_R = 0x2B , RDPQ_CMD_SET_CONVERT = 0x2C , RDPQ_CMD_SET_SCISSOR = 0x2D , RDPQ_CMD_SET_PRIM_DEPTH = 0x2E , RDPQ_CMD_SET_OTHER_MODES = 0x2F , RDPQ_CMD_LOAD_TLUT = 0x30 , RDPQ_CMD_DEBUG = 0x31 , RDPQ_CMD_SET_TILE_SIZE = 0x32 , RDPQ_CMD_LOAD_BLOCK = 0x33 , RDPQ_CMD_LOAD_TILE = 0x34 , RDPQ_CMD_SET_TILE = 0x35 , RDPQ_CMD_FILL_RECTANGLE = 0x36 , RDPQ_CMD_SET_FILL_COLOR = 0x37 , RDPQ_CMD_SET_FOG_COLOR = 0x38 , RDPQ_CMD_SET_BLEND_COLOR = 0x39 , RDPQ_CMD_SET_PRIM_COLOR = 0x3A , RDPQ_CMD_SET_ENV_COLOR = 0x3B , RDPQ_CMD_SET_COMBINE_MODE_RAW = 0x3C , RDPQ_CMD_SET_TEXTURE_IMAGE = 0x3D , RDPQ_CMD_SET_Z_IMAGE = 0x3E , RDPQ_CMD_SET_COLOR_IMAGE = 0x3F } |
enum | rdpq_tile_t { TILE0 = 0 , TILE1 = 1 , TILE2 = 2 , TILE3 = 3 , TILE4 = 4 , TILE5 = 5 , TILE6 = 6 , TILE7 = 7 } |
Tile descriptors. More... | |
Functions | |
void | rdpq_init (void) |
Initialize the RDPQ library. More... | |
void | rdpq_close (void) |
Shutdown the RDPQ library. More... | |
uint32_t | rdpq_config_set (uint32_t cfg) |
Set the configuration of the RDPQ module. More... | |
uint32_t | rdpq_config_enable (uint32_t cfg_enable_bits) |
Enable a specific set of configuration flags. More... | |
uint32_t | rdpq_config_disable (uint32_t cfg_disable_bits) |
Disable a specific set of configuration flags. More... | |
void | rdpq_set_yuv_parms (uint16_t k0, uint16_t k1, uint16_t k2, uint16_t k3, uint16_t k4, uint16_t k5) |
Low level functions to set the matrix coefficients for texture format conversion. | |
void | rdpq_set_prim_depth_raw (uint16_t prim_z, int16_t prim_dz) |
Set a fixed Z value to be used instead of a per-pixel value (RDP command; SET_PRIM_DEPTH) More... | |
void | rdpq_load_tile_fx (rdpq_tile_t tile, uint16_t s0, uint16_t t0, uint16_t s1, uint16_t t1) |
Load a portion of a texture into TMEM – fixed point version (RDP command: LOAD_TILE) More... | |
void | rdpq_load_tlut_raw (rdpq_tile_t tile, uint8_t color_idx, uint8_t num_colors) |
Load a palette of colors into TMEM (RDP command: LOAD_TLUT) More... | |
void | rdpq_set_tile_size_fx (rdpq_tile_t tile, uint16_t s0, uint16_t t0, uint16_t s1, uint16_t t1) |
Configure the extents of a tile descriptor – fixed point version (RDP command: SET_TILE_SIZE) More... | |
void | rdpq_load_block_fx (rdpq_tile_t tile, uint16_t s0, uint16_t t0, uint16_t num_texels, uint16_t dxt) |
Low level function to load a texture image into TMEM in a single memory transfer. | |
void | rdpq_load_block (rdpq_tile_t tile, uint16_t s0, uint16_t t0, uint16_t num_texels, uint16_t tmem_pitch) |
Load a texture image into TMEM with a single contiguous memory transfer (RDP command: LOAD_BLOCK) More... | |
void | rdpq_set_tile (rdpq_tile_t tile, tex_format_t format, int32_t tmem_addr, uint16_t tmem_pitch, const rdpq_tileparms_t *parms) |
Enqueue a RDP SET_TILE command (full version) More... | |
void | rdpq_set_tile_autotmem (int16_t tmem_bytes) |
Configure the auto-TMEM feature of rdpq_set_tile. More... | |
void | rdpq_set_fill_color (color_t color) |
Enqueue a SET_FILL_COLOR RDP command. More... | |
void | rdpq_set_fill_color_stripes (color_t color1, color_t color2) |
Enqueue a SET_FILL_COLOR RDP command to draw a striped pattern. More... | |
void | rdpq_set_fog_color (color_t color) |
Set the RDP FOG blender register. More... | |
void | rdpq_set_blend_color (color_t color) |
Set the RDP BLEND blender register. More... | |
void | rdpq_set_prim_color (color_t color) |
Set the RDP PRIM combiner register (color only) (RDP command: SET_PRIM_COLOR) More... | |
void | rdpq_set_detail_factor (float value) |
Set the detail/sharpen blending factor (RDP command: SET_PRIM_COLOR (partial)) More... | |
void | rdpq_set_prim_lod_frac (uint8_t value) |
Set the RDP PRIM LOD FRAC combiner register (RDP command: SET_PRIM_COLOR (partial)) More... | |
void | rdpq_set_prim_register_raw (color_t color, uint8_t minlod, uint8_t primlod) |
Set the RDP PRIM combiner register (raw version) (RDP command: SET_PRIM_COLOR) More... | |
void | rdpq_set_env_color (color_t color) |
Set the RDP ENV combiner register (RDP command: SET_ENV_COLOR) More... | |
void | rdpq_set_color_image (const surface_t *surface) |
Configure the framebuffer to render to (RDP command: SET_COLOR_IMAGE) More... | |
void | rdpq_set_z_image (const surface_t *surface) |
Configure the Z-buffer to use (RDP command: SET_Z_IMAGE) More... | |
void | rdpq_set_texture_image (const surface_t *surface) |
Configure the texture to use (RDP command: SET_TEX_IMAGE) More... | |
void | rdpq_set_color_image_raw (uint8_t index, uint32_t offset, tex_format_t format, uint32_t width, uint32_t height, uint32_t stride) |
Low-level version of rdpq_set_color_image, with address lookup capability. More... | |
void | rdpq_set_z_image_raw (uint8_t index, uint32_t offset) |
Low-level version of rdpq_set_z_image, with address lookup capability. More... | |
void | rdpq_set_texture_image_raw (uint8_t index, uint32_t offset, tex_format_t format, uint16_t width, uint16_t height) |
Low-level version of rdpq_set_texture_image, with address lookup capability. More... | |
void | rdpq_set_lookup_address (uint8_t index, void *rdram_addr) |
Store an address into the rdpq lookup table. More... | |
void | rdpq_sync_pipe (void) |
Schedule a RDP SYNC_PIPE command. More... | |
void | rdpq_sync_tile (void) |
Schedule a RDP SYNC_TILE command. More... | |
void | rdpq_sync_load (void) |
Schedule a RDP SYNC_LOAD command. More... | |
void | rdpq_sync_full (void(*callback)(void *), void *arg) |
Schedule a RDP SYNC_FULL command and register a callback when it is done. More... | |
void | rdpq_set_other_modes_raw (uint64_t mode) |
Low-level function to set the rendering mode register. More... | |
void | rdpq_change_other_modes_raw (uint64_t mask, uint64_t val) |
Low-level function to partly change the rendering mode register. More... | |
uint64_t | rdpq_get_other_modes_raw (void) |
Read the current render mode register. More... | |
void | rdpq_set_combiner_raw (uint64_t comb) |
Low-level function to change the RDP combiner. More... | |
void | rdpq_fence (void) |
Add a fence to synchronize RSP with RDP commands. More... | |
void | rdpq_exec (void *buffer, int size) |
Send to the RDP a buffer of RDP commands from RDRAM. More... | |
RDP Command queue.
struct rdpq_tileparms_t |
Tile parameters for rdpq_set_tile.
This structure contains all possible parameters for rdpq_set_tile. All fields have been made so that the 0 value is always the most reasonable default (clamped with default scale, no mirroring). This means that you can simply initialize the structure to 0 and then change only the fields you need (for instance, through a compound literal).
Data Fields | ||
---|---|---|
uint8_t | palette | Optional palette associated to the texture. For textures in FMT_CI4 format, specify the palette index (0-15), otherwise use 0. |
struct rdpq_tileparms_t.s | s | |
struct rdpq_tileparms_t.t | t |
struct rdpq_tileparms_t.s |
struct rdpq_tileparms_t.t |
#define RDPQ_OVL_ID (0xC << 28) |
Static overlay ID of rdpq library.
The rdpq overlay must be registered at this ID via rspq_overlay_register_static.
#define rdpq_set_scissor | ( | x0, | |
y0, | |||
x1, | |||
y1 | |||
) |
Configure a scissoring rectangle in screen coordinates (RDP command: SET_SCISSOR)
This function is used to configure a scissor region that the RDP with adhere to while drawing primitives (triangles or rectangles). Any points that fall outside of the specified scissoring rectangle will be ignored.
The scissoring capability is also the only one that prevents the RDP from drawing outside of the current framebuffer (color surface) extents. As such, rdpq actually calls rdpq_set_scissor automatically any time a new render target is configured (eg: via rdpq_attach or rdpq_set_color_image), because forgetting to do so might easily cause crashes.
Because rdpq_set_color_image will configure a scissoring region automatically, it is normally not required to call this function. Use this function if you want to restrict drawing to a smaller area of the framebuffer.
The scissoring rectangle is defined using unsigned coordinates, and thus negative coordinates will always be clipped. Rectangle-drawing primitives do not allow to specify them at all, but triangle-drawing primitives do.
[in] | x0 | Top-left X coordinate of the rectangle |
[in] | y0 | Top-left Y coordinate of the rectangle |
[in] | x1 | Bottom-right exclusive X coordinate of the rectangle |
[in] | y1 | Bottom-right exclusive Y coordinate of the rectangle |
#define rdpq_load_tile | ( | tile, | |
s0, | |||
t0, | |||
s1, | |||
t1 | |||
) |
Load a portion of a texture into TMEM (RDP command: LOAD_TILE)
This is the main command to load data from RDRAM into TMEM. It is normally used to load a texture (or a portion of it), before using it for drawing.
Before calling rdpq_load_tile, the tile must have been configured using rdpq_set_tile to specify the TMEM address and pitch, and the texture in RDRAM must have been set via rdpq_set_texture_image.
In addition to loading TMEM, this command also records into the tile descriptor the extents of the loaded texture (that is, the texture coordinates), so that subsequence draw commands can still refer to original texture's coordinates to draw. For instance, if you have a large 512x128 texture and you load only a small portion into TMEM, for instance the rectangle at coordinates (16,16) - (48,48), the RDP will remember (through the tile descriptor) that the TMEM contains that specific rectangle, and subsequent triangles or rectangles commands can specify S,T texture coordinates within the range (16,16)-(48,48).
If the portion being loaded is consecutive in RDRAM (rather than being a rectangle within a wider image), prefer using rdpq_load_block for increased performance.
[in] | tile | Tile descriptor to use (TILE0-TILE7). |
[in] | s0 | Upper-left X coordinate of the portion of the texture to load (integer or float). Range: 0-1024 |
[in] | t0 | Upper-left Y coordinate of the portion of the texture to load (integer or float), Range: 0-1024 |
[in] | s1 | Bottom-right X coordinate of the portion of the texture to load (integer or float), Range: 0-1024 |
[in] | t1 | Bottom-right Y coordinate of the portion of the texture to load (integer or float), Range: 0-1024 |
#define rdpq_set_tile_size | ( | tile, | |
s0, | |||
t0, | |||
s1, | |||
t1 | |||
) |
Configure the extents of a tile descriptor (RDP command: SET_TILE_SIZE)
This function allows to set the extents (s0,s1 - t0,t1) of a tile descriptor. Normally, it is not required to call this function because extents are automatically configured when rdpq_load_tile is called to load contents in TMEM. This function is mostly useful when loading contents using rdpq_load_block, or when reinterpreting existing contents of TMEM.
For beginners, it is suggest to use the rdpq texture API (rdpq_tex.h) which automatically configures tile descriptors correctly: for instance, rdpq_tex_upload.
[in] | tile | Tile descriptor (TILE0-TILE7) |
[in] | s0 | Top-left X texture coordinate to store in the descriptor (integer or float). Range: 0-1024 (inclusive) |
[in] | t0 | Top-left Y texture coordinate to store in the descriptor (integer or float). Range: 0-1024 (inclusive) |
[in] | s1 | Bottom-right exclusive X texture coordinate to store in the descriptor (integer or float). Range: 0-1024 (inclusive) |
[in] | t1 | Bottom-right exclusive Y texture coordinate to store in the descriptor (integer or float). Range: 0-1024 (inclusive) |
#define rdpq_write | ( | num_rdp_commands, | |
ovl_id, | |||
cmd_id, | |||
... | |||
) |
Enqueue a RSP command that also generates RDP commands.
This function is similar to rspq_write: it enqueues a RSP command in the RSP command queue for later execution by RSP. The main difference is that this macro also declares that the RSP command is going to generate RDP commands as part of its execution.
RSP commands in overlays can generate RDP commands by including rsp_rdqp.inc and calling RDPQ_Send (or RDPQ_Write8 / RDPQ_Write16 / RDPQ_Finalize). If they do, they must enqueued using rdpq_write instead of rspq_write.
It is important to know that the RSP command is going to generate RDP commands because the space for them needs to be allocated in the static buffer in blocks. When wrongly using rspq_write instead of rdpq_write, the command will work correctly outside of blocks but might fail in surprising ways when called within blocks.
In some cases, it is not possible to know beforehand how many RDP commands will be generated. In these case, num_rdp_commands
should be the maximum possible value in words. If the number is quite high and potentially unbounded, pass the special value "-1".
num_rdp_commands | Maximum number of RDP 8-byte commands that will be generated by the RSP command. Use -1 if the number is unbounded and potentially high. |
ovl_id | ID of the overlay for the command (see rspq_write) |
cmd_id | ID of the command (see rspq_write) |
num_rdp_commands
as it was the "number of 64-bit words". So for instance if the RSP command generates a single RDP TEXTURE_RECTANGLE command, pass 2 as num_rdp_commands
. enum rdpq_tile_t |
Tile descriptors.
These are enums that map to integers 0-7, but they can be used in place of the integers for code readability.
void rdpq_init | ( | void | ) |
Initialize the RDPQ library.
This should be called by the initialization functions of the higher-level libraries using RDPQ to emit RDP commands, and/or by the application main if the application itself calls rdpq functions.
It is safe to call this function multiple times (it does nothing), so that multiple independent libraries using rdpq can call rdpq_init with no side effects.
void rdpq_close | ( | void | ) |
Shutdown the RDPQ library.
This is mainly used for testing.
uint32_t rdpq_config_set | ( | uint32_t | cfg | ) |
Set the configuration of the RDPQ module.
This function allows you to change the configuration of rdpq to enable/disable features. This is useful mainly for advanced users that want to manually tune RDP programming, disabling some automatisms performed by rdpq.
The configuration is a bitmask that can be composed using the RDPQ_CFG_*
macros.
To enable or disable specific configuration options use rdpq_config_enable or rdpq_config_disable.
cfg | The new configuration to set |
uint32_t rdpq_config_enable | ( | uint32_t | cfg_enable_bits | ) |
Enable a specific set of configuration flags.
This function allows you to modify the configuration of rdpq activating a specific set of features. It can be useful to temporarily modify the configuration and then restore it.
cfg_enable_bits | Configuration flags to enable |
uint32_t rdpq_config_disable | ( | uint32_t | cfg_disable_bits | ) |
Disable a specific set of configuration flags.
This function allows you to modify the configuration of rdpq disabling a specific set of features. It can be useful to temporarily modify the configuration and then restore it.
cfg_disable_bits | Configuration flags to disable |
|
inline |
Set a fixed Z value to be used instead of a per-pixel value (RDP command; SET_PRIM_DEPTH)
When using z-buffering, normally the Z value used for z-buffering is calculated by interpolating the Z of each vertex onto each pixel. The RDP allows for usage of a fixed Z value instead, for special effects like particles or decals.
This function allows to configure the RDP register that holds the fixed Z value. It is then necessary to activate this special RDP mode: either manually turning on SOM_ZSOURCE_PRIM via rdpq_change_other_modes_raw.
For beginners, it is suggested to use the mode API instead, via rdpq_mode_zoverride.
[in] | prim_z | Fixed Z value (in range 0..0x7FFF) |
[in] | prim_dz | Delta Z value (must be a signed power of two). Pass 0 initially, and increment to next power of two in case of problems with objects with the same Z. |
rdpq_set_prim_depth
).
|
inline |
Load a portion of a texture into TMEM – fixed point version (RDP command: LOAD_TILE)
This function is similar to rdpq_load_tile, but coordinates can be specified in fixed point format (0.10.2). Refer to rdpq_load_tile for increased performance
[in] | tile | Tile descriptor to use (TILE0-TILE7). |
[in] | s0 | Upper-left X coordinate of the portion of the texture to load (fx 0.10.2). Range: 0-4096 |
[in] | t0 | Upper-left Y coordinate of the portion of the texture to load (fx 0.10.2), Range: 0-4096 |
[in] | s1 | Bottom-right X coordinate of the portion of the texture to load (fx 0.10.2), Range: 0-4096 |
[in] | t1 | Bottom-right Y coordinate of the portion of the texture to load (fx 0.10.2), Range: 0-4096 |
|
inline |
Load a palette of colors into TMEM (RDP command: LOAD_TLUT)
This command is used to load a palette into TMEM. TMEM can hold up to 256 16-bit colors in total to be used as palette, and they must be stored in the upper half of TMEM. These colors are arranged as a single 256-color palette when drawing FMT_CI8 images, or 16 16-colors palettes when drawing FMT_CI4 images.
Storage of colors in TMEM is a bit wasteful, as each color is replicated four times (in fact, 256 colors * 16-bit + 4 = 2048 bytes, which is in fact half of TMEM). This command should be preferred for palette loading as it automatically handles this replication.
Loading a palette manually is a bit involved. It requires configuring the palette in RDRAM via rdpq_set_texture_image, and also configure a tile descriptor with the TMEM destination address (via rdpq_set_tile). Instead, prefer using the simpler rdpq texture API (rdpq_tex.h), via rdpq_tex_upload_tlut.
[in] | tile | Tile descriptor to use (TILE0-TILE7). This is used to extract the destination TMEM address (all other fields of the descriptor are ignored). |
[in] | color_idx | Index of the first color to load into TMEM (0-255). This is a 16-bit offset into the RDRAM buffer set via rdpq_set_texture_image. |
[in] | num_colors | Number of colors to load (1-256). |
|
inline |
Configure the extents of a tile descriptor – fixed point version (RDP command: SET_TILE_SIZE)
This function is similar to rdpq_set_tile_size, but coordinates must be specified using fixed point numbers (10.2).
tile | Tile descriptor (TILE0-TILE7) | |
[in] | s0 | Top-left X texture coordinate to store in the descriptor (fx 10.2) |
[in] | t0 | Top-left Y texture coordinate to store in the descriptor (fx 10.2) |
[in] | s1 | Bottom-right exclusive X texture coordinate to store in the descriptor (fx 10.2) |
[in] | t1 | Bottom-right exclusive Y texture coordinate to store in the descriptor (fx 10.2) |
|
inline |
Load a texture image into TMEM with a single contiguous memory transfer (RDP command: LOAD_BLOCK)
This is a command alternative to rdpq_load_tile to load data from RDRAM into TMEM. It is faster than rdpq_load_tile but only allows to transfer a consecutive block of data; the block can cover multiple lines, but not a sub-rectangle of the texture image.
Before calling rdpq_load_block, the tile must have been configured using rdpq_set_tile to specify the TMEM address, and the texture in RDRAM must have been set via rdpq_set_texture_image.
After the call to rdpq_load_block, it is not possible to reuse the tile descriptor for performing a draw. So a new tile descriptor should be configured from scratch using rdpq_set_tile.
The maximum number of texels that can be transferred by a single call is
[in] | tile | Tile descriptor (TILE0-TILE7) |
[in] | s0 | Top-left X texture coordinate to load |
[in] | t0 | Top-left Y texture coordinate to load |
[in] | num_texels | Number of texels to load (max: 2048) |
[in] | tmem_pitch | Pitch of the texture in TMEM (in bytes) |
|
inline |
Enqueue a RDP SET_TILE command (full version)
[in] | tile | Tile descriptor index (0-7) |
[in] | format | Texture format for the tile. Cannot be 0. Should correspond to X_get_format in surface_t or sprite_t; |
[in] | tmem_addr | Address in tmem where the texture is (or will be loaded). Must be multiple of 8; |
[in] | tmem_pitch | Pitch of the texture in tmem in bytes. Must be multiple of 8. Should correspond to srtide in surface_t; |
[in] | parms | Additional optional parameters for the tile. Can be left NULL or all 0. More information about the struct is in rdpq_tileparms_t |
void rdpq_set_tile_autotmem | ( | int16_t | tmem_bytes | ) |
Configure the auto-TMEM feature of rdpq_set_tile.
This function is used to manage the auto-TMEM allocation feature for rdpq_set_tile. It allows to keep track of the allocated space in TMEM, which can be a simplification. It is used by the rdpq_tex module (eg: rdpq_tex_upload).
The feature works like this:
While this API might seem as a small simplification over manually tracking TMEM allocation, it might help modularizing the code, and also allows to record rspq blocks that handle texture loading without hardcoding the TMEM position.
tmem_bytes | 0: begin, -1: end, >0: number of additional bytes that were used in TMEM. |
|
inline |
Enqueue a SET_FILL_COLOR RDP command.
This command is used to configure the color used by RDP when running in FILL mode (rdpq_set_mode_fill) and normally used by rdpq_fill_rectangle.
Notice that rdpq_set_mode_fill automatically calls this function, because in general it makes no sense to configure the FILL mode without also setting a FILL color.
[in] | color | The color to use to fill |
Enqueue a SET_FILL_COLOR RDP command to draw a striped pattern.
This command is similar to rdpq_set_fill_color, but allows to configure two colors, and creates a fill pattern that alternates horizontally between them every 2 pixels (creating vertical stripes).
This command relies on a low-level hack of how RDP works in filling primitives, so there is no configuration knob: it only works with RGBA 16-bit target buffers, it only allows two colors, and the vertical stripes are exactly 2 pixel width.
[in] | color1 | Color of the first vertical stripe |
[in] | color2 | Color of the second vertical stripe |
|
inline |
Set the RDP FOG blender register.
This function sets the internal RDP FOG register, part of the blender unit. As the name implies, this register is normally used as part of fog calculation, but it is actually a generic color register that can be used in custom blender formulas.
Another similar blender register is the BLEND register, configured via rdpq_set_blend_color.
See RDPQ_BLENDER and RDPQ_BLENDER2 on how to configure the blender (typically, via rdpq_mode_blender).
[in] | color | Color to set the FOG register to |
|
inline |
Set the RDP BLEND blender register.
This function sets the internal RDP BLEND register, part of the blender unit. As the name implies, this register is normally used as part of fog calculation, but it is actually a generic color register that can be used in custom blender formulas.
Another similar blender register is the FOG register, configured via rdpq_set_fog_color.
See RDPQ_BLENDER and RDPQ_BLENDER2 on how to configure the blender (typically, via rdpq_mode_blender).
[in] | color | Color to set the BLEND register to |
|
inline |
Set the RDP PRIM combiner register (color only) (RDP command: SET_PRIM_COLOR)
This function sets the internal RDP PRIM register, part of the color combiner unit. Naming aside, it is a generic color register that can be used in custom color combiner formulas.
Another similar blender register is the ENV register, configured via rdpq_set_env_color.
See RDPQ_COMBINER1 and RDPQ_COMBINER2 on how to configure the color combiner (typicall, via rdpq_mode_combiner).
If you wish to set PRIM LOD or PRIM MIN LOD values of the PRIM register, see rdpq_set_prim_lod_frac, rdpq_set_detail_factor or rdpq_set_prim_register_raw.
[in] | color | Color to set the PRIM register to |
|
inline |
Set the detail/sharpen blending factor (RDP command: SET_PRIM_COLOR (partial))
This function sets the internal minimum clamp for LOD fraction, that is used for determining the interpolation blend factor of a detail or sharpen texture at high magnification.
Range is [0..1] where 0 means no influence, and 1 means full influence. The range is internally inverted and converted to [0..31] for the RDP hardware
[in] | value | Value to set the register to in range [0..1] |
|
inline |
Set the RDP PRIM LOD FRAC combiner register (RDP command: SET_PRIM_COLOR (partial))
This function sets the internal Level of Detail fraction for primitive register, that is used for custom linear interpolation between any two colors in a Color Combiner.
See RDPQ_COMBINER1 and RDPQ_COMBINER2 on how to configure the color combiner (typicall, via rdpq_mode_combiner).
If you wish to set PRIM MIN LOD value, see rdpq_set_detail_factor.
[in] | value | Value to set the PRIM LOD register to in range [0..255] |
|
inline |
Set the RDP PRIM combiner register (raw version) (RDP command: SET_PRIM_COLOR)
This function sets the internal RDP PRIM register, part of the color combiner unit. Naming aside, it is a generic color register that can be used in custom color combiner formulas.
It also sets the PRIM LOD FRAC and PRIM MIN LOD FRAC values for the PRIM register For more information, see rdpq_set_prim_lod_frac, rdpq_set_detail_factor.
Another similar blender register is the ENV register, configured via rdpq_set_env_color.
See RDPQ_COMBINER1 and RDPQ_COMBINER2 on how to configure the color combiner (typicall, via rdpq_mode_combiner).
If you wish to set PRIM COLOR or PRIM LOD or PRIM MIN LOD values individually, see rdpq_set_prim_lod_frac, rdpq_set_detail_factor or rdpq_set_prim_color.
[in] | color | Color to set the PRIM register to |
[in] | minlod | Minimum LOD fraction to set the PRIM register to |
[in] | primlod | Primitive LOD fraction to set the PRIM register to |
|
inline |
Set the RDP ENV combiner register (RDP command: SET_ENV_COLOR)
This function sets the internal RDP ENV register, part of the color combiner unit. Naming aside, it is a generic color register that can be used in custom color combiner formulas.
Another similar blender register is the PRIM register, configured via rdpq_set_prim_color.
See RDPQ_COMBINER1 and RDPQ_COMBINER2 on how to configure the color combiner (typically, via rdpq_mode_combiner).
[in] | color | Color to set the ENV register to |
void rdpq_set_color_image | ( | const surface_t * | surface | ) |
Configure the framebuffer to render to (RDP command: SET_COLOR_IMAGE)
This command is used to specify the render target that the RDP will draw to.
Calling this function also automatically configures scissoring (via rdpq_set_scissor), so that all draw commands are clipped within the buffer, to avoid overwriting memory around it. Use rdpq_config_disable(RDPQ_CFG_AUTOSCISSOR)
if you need to disable this behavior.
If you have a raw pointer instead of a surface_t, you can use surface_make to create a temporary surface structure to pass the information to rdpq_set_color_image.
If the passed surface is NULL, rdpq will be detached from the render target. If a drawing command is issued without a render target, it will be silently ignored (but the validator will flag it as an error).
The only valid formats for a surface to be used as a render target are: FMT_RGBA16, FMT_RGBA32, and FMT_I8.
[in] | surface | Surface to set as render target |
void rdpq_set_z_image | ( | const surface_t * | surface | ) |
Configure the Z-buffer to use (RDP command: SET_Z_IMAGE)
This commands is used to specify the Z-buffer that will be used by RDP for the next rendering commands.
The surface must have the same width and height of the surface set as render target (via rdpq_set_color_image or rdpq_set_color_image_raw). The color format should be FMT_RGBA16, even though Z values will be written to it.
If the passed surface is NULL, rdpq will be detached from the Z buffer. If a drawing command using Z is issued without a Z buffer, the behaviour will be undefined (but the validator will flag it as an error).
surface | Surface to set as Z buffer |
void rdpq_set_texture_image | ( | const surface_t * | surface | ) |
Configure the texture to use (RDP command: SET_TEX_IMAGE)
This commands is used to specify the texture image that will be used by RDP for the next load commands (rdpq_load_tile and rdpq_load_block).
The surface must have the same width and height of the surface set as render target (via rdpq_set_color_image or rdpq_set_color_image_raw). The color format should be FMT_RGBA16, even though Z values will be written to it.
surface | Surface to set as texture |
|
inline |
Low-level version of rdpq_set_color_image, with address lookup capability.
This is a low-level version of rdpq_set_color_image, that exposes the address lookup capability. It allows to either pass a direct buffer, or to use a buffer already stored in the address lookup table, adding optionally an offset. See rdpq_set_lookup_address for more information.
RDP a physical constraint of 64-byte alignment for render targets, so make sure to respect that while configuring a buffer. The validator will flag such a mistake.
index | Index in the rdpq lookup table of the buffer to set as render target. |
offset | Byte offset to add to the buffer stored in the lookup table. Notice that if index is 0, this can be a physical address to a buffer (use PhysicalAddr to convert a C pointer to a physical address). |
format | Format of the buffer. Only FMT_RGBA32, FMT_RGBA16 or FMT_I8 are possible to use as a render target. |
width | Width of the buffer in pixel |
height | Height of the buffer in pixel |
stride | Stride of the buffer in bytes (length of a row) |
|
inline |
Low-level version of rdpq_set_z_image, with address lookup capability.
This is a low-level version of rdpq_set_z_image, that exposes the address lookup capability. It allows to either pass a direct buffer, or to use a buffer already stored in the address lookup table, adding optionally an offset. See rdpq_set_lookup_address for more information.
RDP a physical constraint of 64-byte alignment for render targets, so make sure to respect that while configuring a buffer. The validator will flag such a mistake.
index | Index in the rdpq lookup table of the buffer to set as render target. |
offset | Byte offset to add to the buffer stored in the lookup table. Notice that if index is 0, this can be a physical address to a buffer (use PhysicalAddr to convert a C pointer to a physical address). |
|
inline |
Low-level version of rdpq_set_texture_image, with address lookup capability.
This is a low-level version of rdpq_set_texture_image, that exposes the address lookup capability. It allows to either pass a direct buffer, or to use a buffer already stored in the address lookup table, adding optionally an offset. See rdpq_set_lookup_address for more information.
RDP a physical constraint of 8-byte alignment for textures, so make sure to respect that while configuring a buffer. The validator will flag such a mistake.
index | Index in the rdpq lookup table of the buffer to set as texture image. |
offset | Byte offset to add to the buffer stored in the lookup table. Notice that if index is 0, this can be a physical address to a buffer (use PhysicalAddr to convert a C pointer to a physical address). |
format | Format of the texture (tex_format_t) |
width | Width of the texture in pixel (max 1024) |
height | Height of the texture in pixel (max 1024) |
|
inline |
Store an address into the rdpq lookup table.
This function is for advanced usages, it is not normally required to call it.
This function modifies the internal RDPQ address lookup table, by storing an address into on of the available slots.
The lookup table is used to allow for an indirect access to surface pointers. For instance, some library code might want to record a block that manipulates several surfaces, but without saving the actual surface pointers within the block. Instead, all commands referring to a surface, will actually refer to an index into the lookup table. The caller of the block will then store the actual buffer pointers in the table, before playing back the block.
While recording, you can create a placeholder surface via surface_make_placeholder or surface_make_placeholder_linear that is just an "index" into the lookup table.
index | Index of the slot in the table. Available slots are 1-15 (slot 0 is reserved). |
rdram_addr | Pointer of the buffer to store into the address table. |
void rdpq_sync_pipe | ( | void | ) |
Schedule a RDP SYNC_PIPE command.
This command must be sent before changing the RDP pipeline configuration (eg: color combiner, blender, colors, etc.) if the RDP is currently drawing.
Normally, you do not need to call this function because rdpq automatically emits sync commands whenever necessary. You must call this function only if you have disabled autosync for SYNC_PIPE (see RDPQ_CFG_AUTOSYNCPIPE).
void rdpq_sync_tile | ( | void | ) |
Schedule a RDP SYNC_TILE command.
This command must be sent before changing a RDP tile configuration if the RDP is currently drawing using that same tile.
Normally, you do not need to call this function because rdpq automatically emits sync commands whenever necessary. You must call this function only if you have disabled autosync for SYNC_TILE (see RDPQ_CFG_AUTOSYNCTILE).
void rdpq_sync_load | ( | void | ) |
Schedule a RDP SYNC_LOAD command.
This command must be sent before loading an area of TMEM if the RDP is currently drawing using that same area.
Normally, you do not need to call this function because rdpq automatically emits sync commands whenever necessary. You must call this function only if you have disabled autosync for SYNC_LOAD (see RDPQ_CFG_AUTOSYNCLOAD).
void rdpq_sync_full | ( | void(*)(void *) | callback, |
void * | arg | ||
) |
Schedule a RDP SYNC_FULL command and register a callback when it is done.
This function schedules a RDP SYNC_FULL command into the RSP queue. This command basically forces the RDP to finish drawing everything that has been sent to it before it, and then generate an interrupt when it is done.
This is normally useful at the end of the frame. For instance, it is used internally by rdpq_detach to make sure RDP is finished drawing on the target display before detaching it.
The function can be passed an optional callback that will be called when the RDP interrupt triggers. This can be useful to perform some operations asynchronously.
callback | A callback to invoke under interrupt when the RDP is finished drawing, or NULL if no callback is necessary. |
arg | Opaque argument that will be passed to the callback. |
|
inline |
Low-level function to set the rendering mode register.
This function enqueues a low-level SET_OTHER_MODES RDP command that changes the RDP render mode, setting it to a new value
This function is very low level and requires very good knowledge of internal RDP state management. Moreover, it completely overwrites any existing configuration for all bits, so it must be used with caution within a block.
mode | The new render mode. See the RDP_RM |
|
inline |
Low-level function to partly change the rendering mode register.
This function is very low level and requires very good knowledge of internal RDP state management.
It allows to partially change the RDP render mode register, enqueuing a command that will modify only the requested bits. This function is to be preferred to rdpq_set_other_modes_raw as it preservers existing render mode for all the other bits, so it allows for easier composition.
[in] | mask | Mask of bits of the SOM register that must be changed |
[in] | val | New value for the bits selected by the mask. |
uint64_t rdpq_get_other_modes_raw | ( | void | ) |
Read the current render mode register.
This function executes a full sync (rspq_wait) and then extracts the current raw render mode from the RSP state. This should be used only for debugging purposes.
|
inline |
Low-level function to change the RDP combiner.
This function enqueues a low-level SET_COMBINE RDP command that changes the RDP combiner, setting it to a new value. You can use RDPQ_COMBINER1 and RDPQ_COMBINER2 to create the combiner settings for respectively a 1-pass or 2-pass combiner.
comb | The new combiner setting |
void rdpq_fence | ( | void | ) |
Add a fence to synchronize RSP with RDP commands.
This function schedules a fence in the RSP queue that makes RSP waits until all previously enqueued RDP commands have finished executing. This is useful in the rare cases in which you need to post-process the output of RDP with RSP commands.
Notice that the RSP will spin-lock waiting for RDP to become idle, so, if possible, call rdpq_fence as late as possible, to allow for parallel RDP/RSP execution for the longest possible time.
Notice that this does not block the CPU in any way; the CPU will just schedule the fence command in the RSP queue and continue execution. If you need to block the CPU until the RDP is done, check rspq_wait or rdpq_sync_full instead.
Add a fence to synchronize RSP with RDP commands.
void rdpq_exec | ( | void * | buffer, |
int | size | ||
) |
Send to the RDP a buffer of RDP commands from RDRAM.
This command can be used to execute raw RDP commands from RDRAM. It is normally not necessary to call this function as normal rdpq functions will simply enqueue the commands in the RSP queue, but there can be cases where commands have been prepared in RAM somehow (especially, for compatibility with existing code that assembled RDP commands in RDRAM, or to playback RDP command lists prepared with offline tools).
This function fully interoperates with the rest of RDPQ, so you can freely intermix it with standard rdpq calls.
buffer | Pointer to the buffer containing RDP commands |
size | Size of the buffer, in bytes (must be a multiple of 8) |