Struct ctru::services::gfx::Gfx

pub struct Gfx {
    pub top_screen: RefCell<TopScreen>,
    pub bottom_screen: RefCell<BottomScreen>,
    /* private fields */
}

Handle to the GFX service.

This service is a wrapper around the lower-level GSPGPU service that provides helper functions and utilities for software rendering.

Fields

top_screen: RefCell<TopScreen>

Top screen representation.

bottom_screen: RefCell<BottomScreen>

Bottom screen representation.

Implementations

impl Gfx

pub fn new() -> Result<Self>

Initialize a new default service handle.

Notes

The new Gfx instance will allocate the needed framebuffers in the CPU-GPU shared memory region (to ensure compatibiltiy with all possible uses of the Gfx service). As such, it’s the same as calling:

Gfx::with_formats_shared(FramebufferFormat::Bgr8, FramebufferFormat::Bgr8)?;

Have a look at Gfx::with_formats_vram() if you aren’t interested in manipulating the framebuffers using the CPU.

Example

use ctru::services::gfx::Gfx;

let gfx = Gfx::new()?;

pub fn with_formats_shared( top_fb_fmt: FramebufferFormat, bottom_fb_fmt: FramebufferFormat ) -> Result<Self>

Initialize a new service handle with the chosen framebuffer formats on the HEAP for the top and bottom screens.

Use Gfx::new() instead of this function to initialize the module with default parameters

Example

use ctru::services::gfx::Gfx;
use ctru::services::gspgpu::FramebufferFormat;

// Top screen uses RGBA8, bottom screen uses RGB565.
// The screen buffers are allocated in the standard HEAP memory, and not in VRAM.
let gfx = Gfx::with_formats_shared(FramebufferFormat::Rgba8, FramebufferFormat::Rgb565)?;

pub unsafe fn with_formats_vram( top_fb_fmt: FramebufferFormat, bottom_fb_fmt: FramebufferFormat ) -> Result<Self>

Initialize a new service handle with the chosen framebuffer formats on the VRAM for the top and bottom screens.

Notes

Though unsafe to do so, it’s suggested to use VRAM buffers when working exclusively with the GPU, since they result in faster performance and less memory waste.

Safety

By initializing the Gfx service as such, all functionality that relies on CPU manipulation of the framebuffers will be completely unavailable (usually resulting in an ARM panic if wrongly used).

Usage of functionality such as Console and Screen::raw_framebuffer() will result in ARM exceptions.

Example

use ctru::services::{gfx::Gfx, gspgpu::FramebufferFormat};

// Top screen uses RGBA8, bottom screen uses RGB565.
// The screen buffers are allocated in the in VRAM, so they will NOT be accessible from the CPU.
let gfx = unsafe { Gfx::with_formats_vram(FramebufferFormat::Rgba8, FramebufferFormat::Rgb565)? };

pub fn wait_for_vblank(&self)

Waits for the vertical blank event.

Use this to synchronize your application with the refresh rate of the LCD screens

Example

use ctru::services::apt::Apt;
use ctru::services::gfx::Gfx;
let apt = Apt::new()?;
let gfx = Gfx::new()?;

// Simple main loop.
while apt.main_loop() {
    // Main program logic

    // Wait for the screens to refresh.
    // This blocks the current thread to make it run at 60Hz.
    gfx.wait_for_vblank();
}