rdpq_rect.h File Reference

RDP Command queue. More...

Go to the source code of this file.

Macros
Standard rectangle functions
These functions can be used to directly draw filled and/or textured rectangles on the screen. While a rectangle can always be drawn via two triangles, directly invoking the rectangle functions when possible is more efficient on both the CPU and the RDP. The functions are defined as macros so that they can efficiently accept either integers or floating point values. Usage of fractional values is required for subpixel precision.
#define	rdpq_fill_rectangle(x0, y0, x1, y1)
	Draw a filled rectangle (RDP command: FILL_RECTANGLE)
#define	rdpq_texture_rectangle(tile, x0, y0, x1, y1, s, t)
	Draw a textured rectangle (RDP command: TEXTURE_RECTANGLE)
#define	rdpq_texture_rectangle_scaled(tile, x0, y0, x1, y1, s0, t0, s1, t1)
	Draw a textured rectangle with scaling (RDP command: TEXTURE_RECTANGLE)
Raw rectangle functions
These functions are similar to the above ones, but they closely match the hardware commands to be sent to RDP. They are exposed for completeness, but most users should use the standard ones, as they provide a easier and more consistent API. The main differences are that these functions accept only positive integers (so clipping on negative numbers should be performed by the caller, if needed), and the textured functions need the per-pixel horizontal and vertical increments.
#define	rdpq_texture_rectangle_raw(tile, x0, y0, x1, y1, s0, t0, dsdx, dtdy)
	Draw a textured rectangle with scaling – raw version (RDP command: TEXTURE_RECTANGLE)
#define	rdpq_texture_rectangle_flip_raw(tile, x0, y0, x1, y1, s, t, dsdy, dtdx)
	Draw a textured flipped rectangle (RDP command: TEXTURE_RECTANGLE_FLIP)

Detailed Description

RDP Command queue.

Macro Definition Documentation

rdpq_fill_rectangle

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

Draw a filled rectangle (RDP command: FILL_RECTANGLE)

This command is used to render a rectangle filled with a solid color.

The rectangle must be defined using exclusive bottom-right bounds, so for instance rdpq_fill_rectangle(10,10,30,30) will draw a square of exactly 20x20 pixels.

Depending on the render mode, the way to configure the color differs:

• In fill mode, the color is normally configured directly via rdpq_set_mode_fill, and can be changed with rdpq_set_fill_color. Notice that fill mode does not support blending.

// Fill the screen with red color.
rdpq_set_mode_fill(RGBA32(255, 0, 0, 0));
rdpq_fill_rectangle(0, 0, 320, 240);

• In standard mode (rdpq_set_mode_standard), the color must be configured using the combiner, so normally by calling rdpq_mode_combiner with RDPQ_COMBINER_FLAT, and setting the color via rdpq_set_prim_color. To draw a blended rectangle, activate the blender via rdpq_mode_blender, normally with RDPQ_BLENDER_MULTIPLY.

// Set the render mode to standard, with blending enabled
rdpq_set_mode_standard();
rdpq_mode_combiner(RDPQ_COMBINER_FLAT);
rdpq_mode_blender(RDPQ_BLENDER_MULTIPLY);
 
// Set color to black, and alpha to 25% (64 out of 255)
rdpq_set_prim_color(RGBA32(0, 0, 0, 64));
 
// Draw the rectangle
rdpq_fill_rectangle(10, 10, 30, 30);

Parameters

[x0]	x0 Top-left X coordinate of the rectangle (integer or float)
[y0]	y0 Top-left Y coordinate of the rectangle (integer or float)
[x1]	x1 Bottom-right exclusive X coordinate of the rectangle (integer or float)
[y1]	y1 Bottom-right exclusive Y coordinate of the rectangle (integer or float)

See also

rdpq_set_fill_color

rdpq_set_fill_color_stripes

rdpq_texture_rectangle

#define rdpq_texture_rectangle	(		tile,
			x0,
			y0,
			x1,
			y1,
			s,
			t
	)

Draw a textured rectangle (RDP command: TEXTURE_RECTANGLE)

This function enqueues a RDP TEXTURE_RECTANGLE command, that allows to draw a textured rectangle onto the framebuffer (similar to a sprite).

The texture must have been already loaded into TMEM via rdpq_load_tile or rdpq_load_block, and a tile descriptor referring to it must be passed to this function.

Input X and Y coordinates are automatically clipped to the screen boundaries (and then scissoring also takes effect), so there is no specific range limit to them. On the contrary, S and T coordinates have a specific range (-1024..1024).

When x0 > x1 or y0 > y1, the rectangle is drawn flipped (mirrored) on either axis (or both, which basically rotates it by 180° instead).

Before calling this function, make sure to also configure an appropriate render mode. It is possible to use the fast copy mode (rdpq_set_mode_copy) with this function, assuming that advanced blending or color combiner capabilities are not needed. The copy mode can in fact just blit the pixels from the texture unmodified, applying only a per-pixel rejection to mask out transparent pixels (via alpha compare). See rdpq_set_mode_copy for more information.

Alternatively, it is possible to use this command also in standard render mode (rdpq_set_mode_standard), with all the per-pixel blending / combining features.

Normally, rectangles are drawn without any respect for the z-buffer (if any is configured). The only option here is to provide a single Z value valid for the whole rectangle by using rdpq_mode_zoverride in the mode API (or manually calling rdpq_set_prim_depth_raw). In fact, it is not possible to specify a per-vertex Z value.

Similarly, it is not possible to specify a per-vertex color/shade value, but instead it is possible to setup a combiner that applies a fixed color to the pixels of the rectangle (eg: RDPQ_COMBINER_TEX_FLAT).

If you need a full Z-buffering or shading support, an alternative is to call rdpq_triangle instead, and thus draw the rectangles as two triangles. This will however incur in more overhead on the CPU to setup the primitives.

NOTE: implemented using a macro here to support both integer and float inputs without ever forcing a useless additional conversion.

Parameters

[in]	tile	Tile descriptor referring to the texture in TMEM to use for drawing
[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
[in]	s	S coordinate of the texture at the top-left corner (range: -1024..1024)
[in]	t	T coordinate of the texture at the top-left corner (range: -1024..1024)

rdpq_texture_rectangle_scaled

#define rdpq_texture_rectangle_scaled	(		tile,
			x0,
			y0,
			x1,
			y1,
			s0,
			t0,
			s1,
			t1
	)

Draw a textured rectangle with scaling (RDP command: TEXTURE_RECTANGLE)

This function is similar to rdpq_texture_rectangle but allows the rectangle to be scaled horizontally and/or vertically, by specifying both the source rectangle in the texture, and the rectangle on the screen.

Refer to rdpq_texture_rectangle for more details on how this command works.

Parameters

[in]	tile	Tile descriptor referring to the texture in TMEM to use for drawing
[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
[in]	s0	S coordinate of the texture at the top-left corner (range: -1024..1024)
[in]	t0	T coordinate of the texture at the top-left corner (range: -1024..1024)
[in]	s1	S coordinate of the texture at the bottom-right corner (exclusive) (range: -1024..1024)
[in]	t1	T coordinate of the texture at the bottom-right corner (exclusive) (range: -1024..1024)

rdpq_texture_rectangle_raw

#define rdpq_texture_rectangle_raw	(		tile,
			x0,
			y0,
			x1,
			y1,
			s0,
			t0,
			dsdx,
			dtdy
	)

Draw a textured rectangle with scaling – raw version (RDP command: TEXTURE_RECTANGLE)

This function is similar to rdpq_texture_rectangle but it does not perform any preprocessing on the input coordinates. Most users should use rdpq_texture_rectangle or rdpq_texture_rectangle_scaled instead.

Refer to rdpq_texture_rectangle for more details on how this command works.

Parameters

tile	Tile descriptor referring to the texture in TMEM to use for drawing
x0	Top-left X coordinate of the rectangle (range: 0..1024)
y0	Top-left Y coordinate of the rectangle (range: 0..1024)
x1	Bottom-right exclusive X coordinate of the rectangle (range: 0..1024)
y1	Bottom-right exclusive Y coordinate of the rectangle (range: 0..1024)
s0	S coordinate of the texture at the top-left corner (range: -1024..1024)
t0	T coordinate of the texture at the top-left corner (range: -1024..1024)
dsdx	Horizontal increment of S coordinate per pixel (range: -32..32)
dtdy	Vertical increment of T coordinate per pixel (range: -32..32)

See also

rdpq_texture_rectangle

rdpq_texture_rectangle_scaled

rdpq_texture_rectangle_flip_raw

#define rdpq_texture_rectangle_flip_raw	(		tile,
			x0,
			y0,
			x1,
			y1,
			s,
			t,
			dsdy,
			dtdx
	)

Draw a textured flipped rectangle (RDP command: TEXTURE_RECTANGLE_FLIP)

The RDP command TEXTURE_RECTANGLE_FLIP is similar to TEXTURE_RECTANGLE, but the texture S coordinate is incremented over the Y axis, while the texture T coordinate is incremented over the X axis. The graphical effect is similar to a 90° degree rotation plus a mirroring of the texture.

Notice that this command cannot work in COPY mode, so the standard render mode must be activated (via rdpq_set_mode_standard).

Refer to rdpq_texture_rectangle_raw for further information.

Parameters

[in]	tile	Tile descriptor referring to the texture in TMEM to use for drawing
[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
[in]	s	S coordinate of the texture at the top-left corner
[in]	t	T coordinate of the texture at the top-left corner
[in]	dsdy	Signed increment of S coordinate for each vertical pixel.
[in]	dtdx	Signed increment of T coordinate for each horizontal pixel.