Expand description
Lets you interact with the mGBA debug output buffer.
This buffer works as a “standard output” sort of interface:
- First
use core::fmt::Write;so that theWritetrait is in scope. - Try to make a logger with
MgbaBufferedLogger::try_new(log_level). - Use the
write!macro to write data into the logger. - The logger will automatically flush itself (using the log level you set) when the buffer is full, on a newline, and when it’s dropped.
Logging is not always available. Obviously the mGBA output buffer can’t be
used if the game isn’t running within the mGBA emulator.
MgbaBufferedLogger::try_new will fail to make a logger when logging
isn’t available. You can also call mgba_logging_available directly to
check if mGBA logging is possible.
use core::fmt::Write;
let log_level = MgbaMessageLevel::Debug;
if let Ok(logger) = MgbaBufferedLogger::try_new(log_level) {
writeln!(logger, "hello").ok();
}Fine Details
Even when the program is running within mGBA, the MGBA_LOG_ENABLE
address needs to be written with the MGBA_LOGGING_ENABLE_REQUEST value
to allow logging. This is automatically done for you by the assembly
runtime. If the MGBA_LOG_ENABLE address reads back
MGBA_LOGGING_ENABLE_RESPONSE then mGBA logging is possible. If you’re
running outside of mGBA then the MGBA_LOG_ENABLE address maps to nothing.
Writes will do no harm, and reads won’t read the correct value.
Once you know that logging is possible, write your message to
MGBA_LOG_BUFFER. This works similar to a C-style string: the first 0
byte in the buffer will be considered the end of the message.
When the message is ready to go out, write a message level to
MGBA_LOG_SEND. This makes the message available within the emulator’s
logs at that message level and also implicitly zeroes the message buffer so
that it’s ready for the next message.