![]() |
libdragon
|
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) More... | |
void | rdpq_attach_clear (const surface_t *surf_color, const surface_t *surf_z) |
Attach the RDP to a surface and clear it. More... | |
void | rdpq_clear (color_t color) |
Clear the current render target with the specified color. More... | |
void | rdpq_clear_z (uint16_t z) |
Reset the current Z buffer to a given value. More... | |
void | rdpq_detach (void) |
Detach the RDP from the current surface, and restore the previous one. More... | |
bool | rdpq_is_attached (void) |
Check if the RDP is currently attached to a surface. More... | |
void | rdpq_detach_show (void) |
Detach the RDP from the current framebuffer, and show it on screen. More... | |
void | rdpq_detach_wait (void) |
Detach the RDP from the current surface, waiting for RDP to finish drawing. More... | |
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. More... | |
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.
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.
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.
[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. |
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.
[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). |
|
inline |
Clear the current render target with the specified color.
Note that this function will respect the current scissor rectangle, if configured.
[in] | color | Color to use to clear the surface |
|
inline |
Reset the current Z buffer to a given value.
Note that this function will respect the current scissor rectangle, if configured.
[in] | z | Value to reset the Z buffer to |
|
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.
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.
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).
|
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.
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.
[in] | cb | Callback that will be called when the RDP has finished drawing to the surface. |
[in] | arg | Argument to the callback. |