rdpq.h File Reference

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.
#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)
#define	rdpq_load_tile(tile, s0, t0, s1, t1)
	Load a portion of a texture into TMEM (RDP command: LOAD_TILE)
#define	rdpq_set_tile_size(tile, s0, t0, s1, t1)
	Configure the extents of a tile descriptor (RDP command: SET_TILE_SIZE)
#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.

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.
void	rdpq_close (void)
	Shutdown the RDPQ library.
uint32_t	rdpq_config_set (uint32_t cfg)
	Set the configuration of the RDPQ module.
uint32_t	rdpq_config_enable (uint32_t cfg_enable_bits)
	Enable a specific set of configuration flags.
uint32_t	rdpq_config_disable (uint32_t cfg_disable_bits)
	Disable a specific set of configuration flags.
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)
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)
void	rdpq_load_tlut_raw (rdpq_tile_t tile, int color_idx, int num_colors)
	Load a palette of colors into TMEM (RDP command: LOAD_TLUT)
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)
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)
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)
void	rdpq_set_tile_autotmem (int16_t tmem_bytes)
	Configure the auto-TMEM feature of rdpq_set_tile.
void	rdpq_set_fill_color (color_t color)
	Enqueue a SET_FILL_COLOR RDP command.
void	rdpq_set_fill_color_stripes (color_t color1, color_t color2)
	Enqueue a SET_FILL_COLOR RDP command to draw a striped pattern.
void	rdpq_set_fog_color (color_t color)
	Set the RDP FOG blender register.
void	rdpq_set_blend_color (color_t color)
	Set the RDP BLEND blender register.
void	rdpq_set_prim_color (color_t color)
	Set the RDP PRIM combiner register (color only) (RDP command: SET_PRIM_COLOR)
void	rdpq_set_detail_factor (float value)
	Set the detail/sharpen blending factor (RDP command: SET_PRIM_COLOR (partial))
void	rdpq_set_prim_lod_frac (uint8_t value)
	Set the RDP PRIM LOD FRAC combiner register (RDP command: SET_PRIM_COLOR (partial))
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)
void	rdpq_set_env_color (color_t color)
	Set the RDP ENV combiner register (RDP command: SET_ENV_COLOR)
void	rdpq_set_color_image (const surface_t *surface)
	Configure the framebuffer to render to (RDP command: SET_COLOR_IMAGE)
void	rdpq_set_z_image (const surface_t *surface)
	Configure the Z-buffer to use (RDP command: SET_Z_IMAGE)
void	rdpq_set_texture_image (const surface_t *surface)
	Configure the texture to use (RDP command: SET_TEX_IMAGE)
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.
void	rdpq_set_z_image_raw (uint8_t index, uint32_t offset)
	Low-level version of rdpq_set_z_image, with address lookup capability.
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.
void	rdpq_set_lookup_address (uint8_t index, void *rdram_addr)
	Store an address into the rdpq lookup table.
void	rdpq_sync_pipe (void)
	Schedule a RDP SYNC_PIPE command.
void	rdpq_sync_tile (void)
	Schedule a RDP SYNC_TILE command.
void	rdpq_sync_load (void)
	Schedule a RDP SYNC_LOAD command.
void	rdpq_sync_full (void(*callback)(void *), void *arg)
	Schedule a RDP SYNC_FULL command and register a callback when it is done.
void	rdpq_set_other_modes_raw (uint64_t mode)
	Low-level function to set the rendering mode register.
void	rdpq_change_other_modes_raw (uint64_t mask, uint64_t val)
	Low-level function to partly change the rendering mode register.
uint64_t	rdpq_get_other_modes_raw (void)
	Read the current render mode register.
void	rdpq_set_combiner_raw (uint64_t comb)
	Low-level function to change the RDP combiner.
void	rdpq_fence (void)
	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.

Detailed Description

RDP Command queue.

---

Data Structure Documentation

rdpq_tileparms_t

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

rdpq_tileparms_t.s

struct rdpq_tileparms_t.s

Data Fields
bool	clamp	True if texture needs to be clamped. Otherwise wrap the texture around;.
bool	mirror	True if texture needs to be mirrored. Otherwise wrap the texture without mirroring;.
uint8_t	mask	Power of 2 boundary of the texture in pixels to wrap. (Important note: Mask value of 0 will force clamping to be ON regardless of clamp value);.
int8_t	shift	Power of 2 scale of the texture to wrap on. Range is [-5..10];.

rdpq_tileparms_t.t

struct rdpq_tileparms_t.t

Data Fields
bool	clamp	True if texture needs to be clamped. Otherwise wrap the texture around;.
bool	mirror	True if texture needs to be mirrored. Otherwise wrap the texture without mirroring;.
uint8_t	mask	Power of 2 boundary of the texture in pixels to wrap. (Important note: Mask value of 0 will force clamping to be ON regardless of clamp value);.
int8_t	shift	Power of 2 scale of the texture to wrap on. Range is [-5..10];.

Macro Definition Documentation

RDPQ_OVL_ID

#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.

rdpq_set_scissor

#define rdpq_set_scissor	(		x0,
			y0,
			x1,
			y1
	)

Value:

    ({ \
    int32_t x0fx = (x0)*4; \
    int32_t y0fx = (y0)*4; \
    int32_t x1fx = (x1)*4; \
    int32_t y1fx = (y1)*4; \
    assertf(x0fx <= x1fx, "x1 must be greater or equal to x0"); \
    assertf(y0fx <= y1fx, "y1 must be greater or equal to y0"); \
    assertf(x0fx >= 0, "x0 must be positive"); \
    assertf(y0fx >= 0, "y0 must be positive"); \
    assertf(x1fx <= 0xFFF, "x1 must be less than 1024"); \
    assertf(y1fx <= 0xFFF, "y1 must be less than 1024"); \
    __rdpq_set_scissor( \
        _carg(x0fx, 0xFFF, 12) | _carg(y0fx, 0xFFF, 0), \
        _carg(x1fx, 0xFFF, 12) | _carg(y1fx, 0xFFF, 0)); \
})

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.

Parameters

[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

See also

rdpq_attach

rdpq_set_color_image

rdpq_load_tile

#define rdpq_load_tile	(		tile,
			s0,
			t0,
			s1,
			t1
	)

Value:

    ({ \
    assertf((s0) >= 0 && (t0) >= 0 && (s1) >= 0 && (t1) >= 0, "texture coordinates must be positive"); \
    assertf((s0) < 1024 && (t0) < 1024 && (s1) < 1024 && (t1) < 1024, "texture coordinates must be smaller than 1024"); \
    rdpq_load_tile_fx((tile), (s0)*4, (t0)*4, (s1)*4, (t1)*4); \
})

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.

Note

Beginners are advised to use the rdpq texture API (rdpq_tex.h), for instance rdpq_tex_upload that takes care of everything required.

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.

Parameters

[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

See also

rdpq_tex_upload

rdpq_set_texture_image

rdpq_load_block

rdpq_set_tile

rdpq_load_tile_fx

rdpq_set_tile_size

#define rdpq_set_tile_size	(		tile,
			s0,
			t0,
			s1,
			t1
	)

Value:

    ({ \
    rdpq_set_tile_size_fx((tile), (s0)*4, (t0)*4, (s1)*4, (t1)*4); \
})

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.

Parameters

[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)

See also

rdpq_tex_upload

rdpq_set_tile_size_fx

rdpq_write

#define rdpq_write	(		num_rdp_commands,
			ovl_id,
			cmd_id,
			...
	)

Value:

    ({ \
    int __num_rdp_commands = (num_rdp_commands); \
    if (!__builtin_constant_p(__num_rdp_commands) || __num_rdp_commands != 0) { \
        extern rspq_block_t *rspq_block; \
        if (__builtin_expect(rspq_block != NULL, 0)) { \
            extern void __rdpq_block_reserve(int); \
            __rdpq_block_reserve(__num_rdp_commands); \
        } \
    } \
    rspq_write(ovl_id, cmd_id, ##__VA_ARGS__); \
})

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".

Parameters

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)

See also

rspq_write

Note

Some RDP commands are made of multiple 64 bit words. For the purpose of rdpq_write, please treat 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.

Enumeration Type Documentation

rdpq_tile_t

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.

Enumerator
TILE0	Tile #0 (for code readability)
TILE1	Tile #1 (for code readability)
TILE2	Tile #2 (for code readability)
TILE3	Tile #3 (for code readability)
TILE4	Tile #4 (for code readability)
TILE5	Tile #5 (for code readability)
TILE6	Tile #6 (for code readability)
TILE7	Tile #7 (for code readability)

Function Documentation

rdpq_init()

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.

rdpq_close()

void rdpq_close

(

void

)

Shutdown the RDPQ library.

This is mainly used for testing.

rdpq_config_set()

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.

Parameters

cfg	The new configuration to set

Returns

The previous configuration

See also

rdpq_config_enable

rdpq_config_disable

rdpq_config_enable()

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.

Parameters

cfg_enable_bits

Configuration flags to enable

Returns

The previous configuration

See also

rdpq_config_set

rdpq_config_disable

rdpq_config_disable()

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.

// Disable automatic scissor generation
uint32_t old_cfg = rdpq_config_disable(RDPQ_CFG_AUTOSCISSOR);
 
// This will change the render target but will NOT issue a corresponding SET_SCISSOR.
// This is dangerous as the currently-configured scissor might allow to draw outside of
// the surface boundary, but an advanced user will know if this is correct.
rdpq_set_color_image(surface);
 
[...]
 
// Restore the previous configuration
rdpq_config_set(old_cfg);

Parameters

cfg_disable_bits

Configuration flags to disable

Returns

The previous configuration

See also

rdpq_config_set

rdpq_config_enable

rdpq_set_prim_depth_raw()

void rdpq_set_prim_depth_raw ( uint16_t  prim_z, int16_t  prim_dz  )

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.

Parameters

[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.

Note

Pending further investigation of the exact usage of this function, and specifically the prim_dz parameter, rdpq does not currently offer a higher-level function (rdpq_set_prim_depth).

rdpq_load_tile_fx()

void rdpq_load_tile_fx ( rdpq_tile_t  tile, uint16_t  s0, uint16_t  t0, uint16_t  s1, uint16_t  t1  )

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

Note

Beginners are advised to use the rdpq texture API (rdpq_tex.h), for instance rdpq_tex_upload that takes care of everything required.

Parameters

[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

See also

rdpq_load_tile

rdpq_tex_upload

rdpq_load_tlut_raw()

void rdpq_load_tlut_raw ( rdpq_tile_t  tile, int  color_idx, int  num_colors  )

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.

Parameters

[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).

See also

rdpq_tex_upload_tlut

rdpq_set_tile_size_fx()

void rdpq_set_tile_size_fx ( rdpq_tile_t  tile, uint16_t  s0, uint16_t  t0, uint16_t  s1, uint16_t  t1  )

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).

Parameters

	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)

See also

rdpq_tex_upload

rdpq_set_tile_size

rdpq_load_block()

void rdpq_load_block ( rdpq_tile_t  tile, uint16_t  s0, uint16_t  t0, uint16_t  num_texels, uint16_t  tmem_pitch  )

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.

Note

Beginners are advised to use the rdpq texture API (rdpq_tex.h), for instance rdpq_tex_upload that takes care of everything required, including using rdpq_load_block for performance whenever possible.

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.

Note

It is important to notice that the RDP will interpret the tile pitch configured in the tile descriptor with a different semantic: it is used as a number of texels that must be skipped between lines in RDRAM. Normally, for a compact texture, it should then be set to zero in the call to rdpq_set_tile. Instead, The real pitch of the texture in TMEM must be provided to rdpq_load_block itself.

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

1. This allows to fill the TMEM only if a 16-bit or 32-bit texture is used. If you need to load a 4-bit or 8-bit texture, consider configuring the tile descriptor as 16-bit and adjusting the number of texels accordingly. For instance, to transfer a 80x64 4-bit texture (5120 texels), do the transfer as if it was a 20x64 16-bit texture (1280 texels). It doesn't matter if you lie to the RDP during the texture load: what it matters is that the tile descriptor that you will later use for drawing is configured with the correct pixel format.

Parameters

[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)

See also

rdpq_load_tile

rdpq_load_block_fx

rdpq_set_tile

rdpq_tex_upload

rdpq_set_tile()

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  )

inline

Enqueue a RDP SET_TILE command (full version)

Parameters

[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

rdpq_set_tile_autotmem()

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:

• First, start auto-TMEM via rdpq_set_tile_autotmem(0)
• Load a texture and configure a tile for it. When configuring the tile, pass RDPQ_AUTOTMEM as tmem_addr. This will allocate the texture in the first available space.
• Call rdpq_set_tile_autotmem again passing the number of used bytes in TMEM. Notice that rdpq can't know this by itself.
• Continue loading the other textures/mipmaps just like before, with RDPQ_AUTOTMEM.
• If the TMEM is full, a RSP assertion will be triggered.
• When you are done, call rdpq_set_tile_autotmem passing -1 to finish. This allows reentrant calls to work, and also helps generating errors in case of misuses.

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.

Note

This function is part of the raw API. For a higher-level API on texture loading, see rdpq_tex_upload.

Parameters

tmem_bytes

0: begin, -1: end, >0: number of additional bytes that were used in TMEM.

See also

rdpq_set_tile

rdpq_tex_upload

rdpq_set_fill_color()

void rdpq_set_fill_color ( color_t  color )

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.

// Fill top half of the screen in red
rdpq_set_mode_fill(RGBA32(255, 0, 0, 0));
rdpq_fill_rectangle(0, 0, 320, 120);
 
// Fill bottom half of the screen in blue.
// No need to change mode again (it's already in fill mode),
// so just change the fill color.
rdpq_set_fill_color(RGBA32(0, 0, 255, 0));
rdpq_fill_rectangle(0, 120, 320, 240);

Parameters

[in]

color

The color to use to fill

See also

rdpq_set_mode_fill

rdpq_set_fill_color_stripes()

void rdpq_set_fill_color_stripes ( color_t  color1, color_t  color2  )

inline

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.

Parameters

[in]	color1	Color of the first vertical stripe
[in]	color2	Color of the second vertical stripe

See also

rdpq_set_fill_color

rdpq_set_fog_color()

void rdpq_set_fog_color ( color_t  color )

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).

Parameters

[in]

color

Color to set the FOG register to

See also

RDPQ_BLENDER

RDPQ_BLENDER2

rdpq_set_blend_color

rdpq_mode_blender

rdpq_set_blend_color()

void rdpq_set_blend_color ( color_t  color )

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).

Parameters

[in]

color

Color to set the BLEND register to

See also

RDPQ_BLENDER

RDPQ_BLENDER2

rdpq_set_fog_color

rdpq_mode_blender

rdpq_set_prim_color()

void rdpq_set_prim_color ( color_t  color )

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.

Parameters

[in]

color

Color to set the PRIM register to

See also

RDPQ_COMBINER1

RDPQ_COMBINER2

rdpq_set_env_color

rdpq_mode_combiner

rdpq_set_prim_lod_frac

rdpq_set_detail_factor

rdpq_set_prim_register_raw

rdpq_set_detail_factor()

void rdpq_set_detail_factor ( float  value )

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

Parameters

[in]

value

Value to set the register to in range [0..1]

See also

RDPQ_COMBINER1

RDPQ_COMBINER2

rdpq_mode_combiner

rdpq_set_prim_lod_frac()

void rdpq_set_prim_lod_frac ( uint8_t  value )

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.

Parameters

[in]

value

Value to set the PRIM LOD register to in range [0..255]

See also

RDPQ_COMBINER1

RDPQ_COMBINER2

rdpq_mode_combiner

rdpq_set_detail_factor

rdpq_set_prim_register_raw()

void rdpq_set_prim_register_raw ( color_t  color, uint8_t  minlod, uint8_t  primlod  )

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.

Parameters

[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

See also

RDPQ_COMBINER1

RDPQ_COMBINER2

rdpq_set_env_color

rdpq_set_prim_color

rdpq_set_prim_lod_frac

rdpq_set_detail_factor

rdpq_set_env_color()

void rdpq_set_env_color ( color_t  color )

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).

Parameters

[in]

color

Color to set the ENV register to

See also

RDPQ_COMBINER1

RDPQ_COMBINER2

rdpq_set_prim_color

rdpq_mode_combiner

rdpq_set_color_image()

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.

Parameters

[in]

surface

Surface to set as render target

See also

rdpq_set_color_image_raw

rdpq_set_z_image()

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).

Parameters

surface

Surface to set as Z buffer

See also

rdpq_set_z_image_raw

rdpq_set_texture_image()

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.

Parameters

surface

Surface to set as texture

See also

rdpq_set_texture_image_raw

rdpq_set_color_image_raw()

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  )

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.

Parameters

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)

See also

rdpq_set_color_image

rdpq_set_lookup_address

rdpq_set_z_image_raw()

void rdpq_set_z_image_raw ( uint8_t  index, uint32_t  offset  )

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.

Parameters

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).

See also

rdpq_set_z_image

rdpq_set_lookup_address

rdpq_set_texture_image_raw()

void rdpq_set_texture_image_raw ( uint8_t  index, uint32_t  offset, tex_format_t  format, uint16_t  width, uint16_t  height  )

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.

Parameters

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)

See also

rdpq_set_texture_image

rdpq_set_lookup_address

rdpq_set_lookup_address()

void rdpq_set_lookup_address ( uint8_t  index, void *  rdram_addr  )

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.

// Create placeholder surfaces with indices 3 and 4
surface_t tex1 = surface_make_placeholder_linear(3, FMT_RGBA16, 32, 32);
surface_t tex2 = surface_make_placeholder_linear(4, FMT_RGBA16, 32, 32);
 
// Start recording a block.
rspq_block_begin();
rdpq_set_mode_standard();
 
// Load texture from lookup table (slot 3) and draw it to the screen
rdpq_set_texture_image(&tex1);
rdpq_load_tile(0, 0, 32, 32);
rdpq_texture_rectangle(0, 0, 32, 32);
 
// Load texture from lookup table (slot 4) and draw it to the screen
rdpq_set_texture_image(&tex2);
rdpq_load_tile(0, 0, 32, 32);
rdpq_texture_rectangle(32, 0, 64, 32);
 
rspq_block_t *bl = rspq_block_end();
 
[...]
 
// Set two real textures into the the lookup table and call the block
rdpq_set_lookup_address(3, robot->buffer);
rdpq_set_lookup_address(4, dragon->buffer);
rspq_block_run(bl);

Note

RDP has some alignment constraints: color and Z buffers must be 64-byte aligned, and textures must be 8-byte aligned.

Parameters

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.

rdpq_sync_pipe()

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).

Note

No software emulator currently requires this command, so manually sending SYNC_PIPE should be developed on real hardware.

rdpq_sync_tile()

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).

Note

No software emulator currently requires this command, so manually sending SYNC_TILE should be developed on real hardware.

rdpq_sync_load()

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).

Note

No software emulator currently requires this command, so manually sending SYNC_LOAD should be developed on real hardware.

rdpq_sync_full()

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_wait 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.

Parameters

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.

See also

rspq_wait

rdpq_fence

rdpq_set_other_modes_raw()

void rdpq_set_other_modes_raw ( uint64_t  mode )

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.

Note

If possible, prefer using the RDPQ mode API (defined in rdpq_mode.h), that expose a higher level API for changing the RDP modes

Parameters

mode	The new render mode. See the RDP_RM

rdpq_change_other_modes_raw()

void rdpq_change_other_modes_raw ( uint64_t  mask, uint64_t  val  )

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.

Note

If possible, prefer using the RDPQ mode API (defined in rdpq_mode.h), that expose a higher level API for changing the RDP modes

Parameters

[in]	mask	Mask of bits of the SOM register that must be changed
[in]	val	New value for the bits selected by the mask.

rdpq_get_other_modes_raw()

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.

Returns

THe current value of the render mode register.

rdpq_set_combiner_raw()

void rdpq_set_combiner_raw ( uint64_t  comb )

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.

Note

Prefer using rdpq_mode_combiner (part of the RDPQ mode API), as it better handles integration with other render mode changes.

Parameters

comb	The new combiner setting

See also

rdpq_mode_combiner

RDPQ_COMBINER1

RDPQ_COMBINER2

rdpq_fence()

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.

See also

rdpq_sync_full

rspq_wait

Add a fence to synchronize RSP with RDP commands.

rdpq_exec()

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.

Parameters

buffer	Pointer to the buffer containing RDP commands
size	Size of the buffer, in bytes (must be a multiple of 8)

Note

This function cannot be called within a block.