rdpq_sprite.c File Reference

RDP Command queue: high-level sprite loading and blitting. More...

Functions
int	__rdpq_sprite_upload (rdpq_tile_t tile, sprite_t *sprite, const rdpq_texparms_t *parms, bool set_mode)
	Internal implementation of rdpq_sprite_upload that will optionally skip setting render modes.
int	rdpq_sprite_upload (rdpq_tile_t tile, sprite_t *sprite, const rdpq_texparms_t *parms)
	Upload a sprite to TMEM, making it ready for drawing.
void	rdpq_sprite_blit (sprite_t *sprite, float x0, float y0, const rdpq_blitparms_t *parms)
	Blit a sprite to the active framebuffer.

Detailed Description

RDP Command queue: high-level sprite loading and blitting.

Function Documentation

rdpq_sprite_upload()

int rdpq_sprite_upload	(	rdpq_tile_t	tile,
		sprite_t *	sprite,
		const rdpq_texparms_t *	parms
	)

Upload a sprite to TMEM, making it ready for drawing.

This function will upload a sprite to TMEM, making it ready for drawing. It is similar to rdpq_tex_upload which can be used for any surface, but it builds upon it with sprite-specific features:

• If the sprite contains mipmaps, the whole mipmap chain is uploaded to TMEM as well. Moreover, mipmaps are automatically enabled in the render mode (via rdpq_mode_mipmap).
• If the sprite contains a palette, it is uploaded to TMEM as well, and the palette is also activated in the render mode (via rdpq_mode_tlut).
• If the sprite is optimized (via mksprite –optimize), the upload function will be faster.

After calling this function, the specified tile descriptor will be ready to be used in drawing primitives like rdpq_triangle or rdpq_texture_rectangle.

This function is meant for sprites that can be loaded in full into TMEM; it will assert if the sprite does not fit TMEM. For larger sprites, either use rdpq_sprite_blit to directly draw then (handling partial uploads transparently), or use rdpq_tex_upload_sub to manually upload a smaller portion of the sprite.

To load multiple sprites in TMEM at once (for instance, for multitexturing), you can manually specify the parms->tmem_addr for the second sprite, or call rdpq_tex_multi_begin / rdpq_tex_multi_end around multiple calls to rdpq_sprite_upload. For instance:

// Load multiple sprites in TMEM, with auto-TMEM allocation.
rdpq_tex_multi_begin();
rdpq_sprite_upload(TILE0, sprite0, NULL);
rdpq_sprite_upload(TILE1, sprite1, NULL);
rdpq_tex_multi_end();

To speed up loading of a sprite, you can record the loading sequence in a rspq block and replay it any time later. For instance:

sprite_t *hero = sprite_load("rom:/hero.sprite");
 
// Record the loading sequence in a rspq block
rspq_block_begin();
    rdpq_sprite_upload(TILE0, hero, NULL);
rspq_block_t *hero_load = rspq_block_end();
 
// Later, load the sprite
rspq_block_run(hero_load);
 
// Remember to free the block when you don't need it anymore
rspq_wait();     // wait until RSP is idle
rspq_block_free(hero_load);
sprite_free(hero);

Parameters

tile	Tile descriptor that will be initialized with this sprite
sprite	Sprite to upload
parms	Texture upload parameters to use

Returns

Number of bytes used in TMEM for this sprite (excluding palette)

See also

rdpq_tex_upload

rdpq_tex_upload_sub

rdpq_sprite_blit

rdpq_sprite_blit()

void rdpq_sprite_blit	(	sprite_t *	sprite,
		float	x0,
		float	y0,
		const rdpq_blitparms_t *	parms
	)

Blit a sprite to the active framebuffer.

This function will perform a blit of a sprite to the active framebuffer, with several features like source rectangle selection, scaling, rotation, etc.

The function is similar to rdpq_tex_blit, but it works on a sprite rather than a generic surface. In addition to the standard features of rdpq_tex_blit, it will also handle sprite-specific features:

• If the sprite contains a palette, it is uploaded to TMEM as well, and the palette is also activated in the render mode (via rdpq_mode_tlut).
• If the sprite is optimized (via mksprite –optimize), the upload function will be faster.

Just like rdpq_tex_blit, this function is designed to work with sprites of arbitrary sizes; those that won't fit in TMEM will be automatically split in multiple chunks to perform the requested operation.

Please refer to rdpq_tex_blit for a full overview of the features.

Parameters

sprite	Sprite to blit
x0	X coordinate on the framebuffer where to draw the surface
y0	Y coordinate on the framebuffer where to draw the surface
parms	Parameters for the blit operation (or NULL for default)