rdpq_attach.h File Reference

RDP Command queue: surface attachment API. More...

Go to the source code of this file.

Functions
void	rdpq_attach (const surface_t *surf_color, const surface_t *surf_z)
	Attach the RDP to a color surface (and optionally a Z buffer)
void	rdpq_attach_clear (const surface_t *surf_color, const surface_t *surf_z)
	Attach the RDP to a surface and clear it.
void	rdpq_clear (color_t color)
	Clear the current render target with the specified color.
void	rdpq_clear_z (uint16_t z)
	Reset the current Z buffer to a given value.
void	rdpq_detach (void)
	Detach the RDP from the current surface, and restore the previous one.
bool	rdpq_is_attached (void)
	Check if the RDP is currently attached to a surface.
void	rdpq_detach_show (void)
	Detach the RDP from the current framebuffer, and show it on screen.
void	rdpq_detach_wait (void)
	Detach the RDP from the current surface, waiting for RDP to finish drawing.
void	rdpq_detach_cb (void(*cb)(void *), void *arg)
	Detach the RDP from the current surface, and call a callback when the RDP has finished drawing to it.

Detailed Description

RDP Command queue: surface attachment API.

This module implements a higher level API for attaching surfaces to the RDP.

It offers a more common lock/unlock-style API to select render targets that help catching mistakes compared to the raw commands such as rdpq_set_color_image or rdpq_sync_full.

Moreover, a small render target stack is kept internally so to make it easier to temporarily switch rendering to an offscreen surface, and then restore the main render target.

Function Documentation

rdpq_attach()

void rdpq_attach	(	const surface_t *	surf_color,
		const surface_t *	surf_z
	)

Attach the RDP to a color surface (and optionally a Z buffer)

This function configures the new render targets the RDP will draw to. It accepts both a color buffer and optionally a Z buffer, both of which in terms of surface_t pointers.

For instance, it can be used with framebuffers acquired by calling display_get, or to render to an offscreen buffer created with surface_alloc or surface_make.

This function should be called before any rendering operations to ensure that the RDP has a valid render target to operate on. It also resets the scissor rectangle to match the buffer being passed, so that the whole buffer will be writable after attaching to it.

The previous render targets are stored away in a small stack, so that they can be restored later when rdpq_detach is called. This allows to temporarily switch rendering to an offscreen surface, and then restore the main render target.

Parameters

[in]	surf_color	The surface to render to. Supported formats are: FMT_RGBA32, FMT_RGBA16, FMT_CI8, FMT_I8.
[in]	surf_z	The Z-buffer to render to (can be NULL if no Z-buffer is required). The only supported format is FMT_RGBA16.

See also

display_get

surface_alloc

rdpq_attach_clear()

void rdpq_attach_clear	(	const surface_t *	surf_color,
		const surface_t *	surf_z
	)

Attach the RDP to a surface and clear it.

This function is similar to rdpq_attach, but it also clears the surface to full black (color 0) immediately after attaching. If a z-buffer is specified, it is also cleared (to 0xFFFC).

This function is just a shortcut for calling rdpq_attach, rdpq_clear and rdpq_clear_z.

Parameters

[in]	surf_color	The surface to render to.
[in]	surf_z	The Z-buffer to render to (can be NULL if no Z-buffer is required).

See also

display_get

surface_alloc

rdpq_clear

rdpq_clear_z

rdpq_clear()

void rdpq_clear ( color_t  color )

inline

Clear the current render target with the specified color.

Note that this function will respect the current scissor rectangle, if configured.

Parameters

[in]

color

Color to use to clear the surface

rdpq_clear_z()

void rdpq_clear_z ( uint16_t  z )

inline

Reset the current Z buffer to a given value.

This function clears the Z-buffer with the specified packed 16-bit value. This value is composed as follows:

• The top 16-bit contains the Z value in a custom floating point format.
• The bottom 2-bits (plus the 2 hidden bits) contain the Delta-Z value. The Delta-Z value to use while clearing does not matter in practice for normal Z buffer usages, so it can be left as 0.

The default value to use for clearing the Z-buffer is ZBUF_MAX. To set the clear value to a custom Z value, use the ZBUF_VAL macro.

Note that this function will respect the current scissor rectangle, if configured.

Parameters

[in]

z

Value to reset the Z buffer to

rdpq_detach()

void rdpq_detach ( void  )

inline

Detach the RDP from the current surface, and restore the previous one.

This function detaches the RDP from the current surface. Using a small internal stack, the previous render target is restored (if any).

Notice that rdpq_detach does not wait for the RDP to finish rendering, like any other rdpq function. If you need to ensure that the RDP has finished rendering, either call rspq_wait afterwards, or use the rdpq_detach_wait function.

A common use case is detaching from the main framebuffer (obtained via display_get), and then displaying it via display_show. For this case, consider using rdpq_detach_show which basically schedules the display_show to happen automatically without blocking the CPU.

See also

rdpq_attach

rdpq_detach_show

rdpq_detach_wait

rdpq_is_attached()

bool rdpq_is_attached

(

void

)

Check if the RDP is currently attached to a surface.

Returns

true if it is attached, false otherwise.

rdpq_detach_show()

void rdpq_detach_show

(

void

)

Detach the RDP from the current framebuffer, and show it on screen.

This function runs a rdpq_detach on the surface, and then schedules in background for the surface to be displayed on screen after the RDP has finished drawing to it.

The net result is similar to calling rdpq_detach_wait and then display_show manually, but it is more efficient because it does not block the CPU. Thus, if this function is called at the end of the frame, the CPU can immediately start working on the next one (assuming there is a free framebuffer available).

See also

rdpq_detach_wait

display_show

rdpq_detach_wait()

void rdpq_detach_wait ( void  )

inline

Detach the RDP from the current surface, waiting for RDP to finish drawing.

This function is similar to rdpq_detach, but also waits for the RDP to finish drawing to the surface.

See also

rdpq_detach

rdpq_detach_cb()

void rdpq_detach_cb	(	void(*)(void *)	cb,
		void *	arg
	)

Detach the RDP from the current surface, and call a callback when the RDP has finished drawing to it.

This function is similar to rdpq_detach: it does not block the CPU, but schedules for a callback to be called (under interrupt) when the RDP has finished drawing to the surface.

Parameters

[in]	cb	Callback that will be called when the RDP has finished drawing to the surface.
[in]	arg	Argument to the callback.

See also

rdpq_detach