Struct ctru::console::Console

pub struct Console<'screen> { /* private fields */ }

Virtual text console.

Console lets the application redirect stdout and stderr to a simple text displayer on the 3DS screen. This means that any text written to stdout and stderr (e.g. using println!, eprintln! or dbg!) will become visible in the area taken by the console.

Notes

The Console will take full possession of the screen handed to it as long as it stays alive. It also supports some ANSI codes, such as text color and cursor positioning. The Console’s window size will be:

• 40x30 on the BottomScreen.
• 50x30 on the normal TopScreen.
• 100x30 on the TopScreen when wide mode is enabled.

Alternatives

If you’d like to see live standard output while running the application but cannot or do not want to show the text on the 3DS itself, you can try using Soc::redirect_to_3dslink while activating the --server flag for 3dslink (also supported by cargo-3ds). More info in the cargo-3ds docs.

Implementations

impl<'screen> Console<'screen>

pub fn new<S: ConsoleScreen>(screen: RefMut<'screen, S>) -> Self

Initialize a console on the chosen screen.

Notes

This operation overwrites whatever was on the screen before the initialization (including other Consoles) and changes the FramebufferFormat of the selected screen to better suit the Console.

The new console is automatically selected for printing.

Console automatically takes care of flushing and swapping buffers for its screen when printing.

Panics

If the Gfx service was initialised via Gfx::with_formats_vram() this function will crash the program with an ARM exception.

Example

use ctru::console::Console;
use ctru::services::gfx::Gfx;

// Initialize graphics (using framebuffers allocated on the HEAP).
let gfx = Gfx::new()?;

// Create a `Console` that takes control of the upper LCD screen.
let top_console = Console::new(gfx.top_screen.borrow_mut());

println!("I'm on the top screen!");

pub fn exists() -> bool

Returns true if a valid Console to print on is currently selected.

Notes

This function is used to check whether one of the two screens has an existing (and selected) Console, so that the program can be sure its output will be shown somewhere.

Example

use ctru::console::Console;
let top_console = Console::new(gfx.top_screen.borrow_mut());

// There is at least one selected `Console`.
assert!(Console::exists());

pub fn select(&self)

Select this console as the current target for standard output.

Notes

Any previously selected console will be unhooked and will not show the stdout and stderr output.

Example

use ctru::console::Console;

// Create a `Console` that takes control of the upper LCD screen.
let top_console = Console::new(gfx.top_screen.borrow_mut());

// Create a `Console` that takes control of the lower LCD screen.
let bottom_console = Console::new(gfx.bottom_screen.borrow_mut());

// Remember that `Console::new` automatically selects the new `Console` for output.
println!("I'm on the bottom screen!");

top_console.select();

println!("Being on the upper screen is much better!");

pub fn clear(&self)

Clear all text from the console.

pub fn set_window( &mut self, x: u8, y: u8, width: u8, height: u8 ) -> Result<(), Error>

Resize the console to fit in a smaller portion of the screen.

Notes

The first two arguments are the desired coordinates of the top-left corner of the new window based on the row/column coordinates of a full-screen console. The second pair is the new width and height.

Example

let mut top_console = Console::new(gfx.top_screen.borrow_mut());
top_console.set_window(10, 10, 16, 6);

println!("I'm becoming claustrophobic in here!");

pub fn reset_window(&mut self)

Reset the window’s size to default parameters.

This can be used to undo the changes made by set_window().

Example

let mut top_console = Console::new(gfx.top_screen.borrow_mut());
top_console.set_window(15, 15, 8, 10);

println!("It's really jammed in here!");

top_console.reset_window();

println!("Phew, finally a breath of fresh air.");

pub fn max_width(&self) -> u8

Returns this Console’s maximum character width depending on the screen used.

Example

let gfx = Gfx::new()?;

let top_console = Console::new(gfx.top_screen.borrow_mut());

// The maximum width for the top screen (without any alterations) is 50 characters.
assert_eq!(top_console.max_width(), 50);

Trait Implementations

impl Drop for Console<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl Flush for Console<'_>

fn flush_buffers(&mut self)

Flushes the video buffer(s) for this screen.

impl Swap for Console<'_>

fn swap_buffers(&mut self)

Swaps the video buffers. Note: The console’s cursor position is not reset, only the framebuffer is changed.

Even if double buffering is disabled, “swapping” the buffers has the side effect of committing any configuration changes to the buffers (e.g. [TopScreen::set_wide_mode()], Screen::set_framebuffer_format(), Swap::set_double_buffering()), so it should still be used.

This should be called once per frame at most.

fn set_double_buffering(&mut self, enabled: bool)

Set whether to use double buffering.