Building a new Console vs the existing libctru console

[ian-h-chamberlain]

Based on the discussion from #57 I wanted to open more of a conversation about Console, and see if we could come to some kind of consensus on how we should handle this.

As I see it, the default console has several drawbacks / missing features:

• CPU rendering only
• Little control over rendering; using this console:
  • forces a specific framebuffer format
  • disables double buffering for the screen
  • Automatically flushes the buffer on \n or \r, or when clearing
• Custom fonts are implemented, but it's kind of unclear what format is required?
• Doesn't seem to support unicode characters, variable font width, etc.
• I don't think there's any way to render to e.g. an in-memory console that could be toggled on/off

It has some nice things too, though:

• Handles ANSI control characters for colors, cursor position, etc. already
• Automatically hooks into stdout/stderr
• Supports a custom PrintChar callback to override print behavior

---

So, with all that said, I think we have a few different options for a better console:

1. Use the existing one with some hacks to override behavior, like in Write a console that does not flush gfx buffers #57

   • Feels hacky and potentially unsafe, relies on implementation details of the console
   • Still can't use GPU or custom framebuffer, etc.
   • Keeps most of the drawbacks above

2. Keep using the existing console, but fully implement a PrintChar callback

   • Still can't use GPU rendering or custom flushing, I think
   • We can implement custom fonts this way (control writing to framebuffer)
   • Automatic hookup to stdout/stderr
   • callback must be extern "C", i.e. global state or stateless (other than the state already found in PrintConsole)

3. Write a new console from scratch in Rust

   • We can have all the features we want, probably!
   • A lot of work, probably
   • I'm not sure how hard it is to hook up to stdout/stderr. consoleInit does this with some calls to setvbuf and devoptab_list, which I suppose we might be able to do in our custom implementation?

4. Try to find some external library? Maybe the above option but with less work... there are certainly some font libs out there and things like that so we can probably use them to reduce the workload.

---

I guess based on all that, writing one from scratch seems like a good option. It probably can be a separate crate that depends on ctru (or ctru-sys). For this to work, I think the main issue is figuring out how to hook it up to std output streams, and then obviously just the implementation work.

Another decision would be whether to use GPU rendering (citro2d?) or render directly to the framebuffer like libctru. Or possibly two separate implementations at the user's choice?

Thoughts @Meziu @AzureMarker ?

[AzureMarker]

forces a specific framebuffer format

I thought we could pass in a framebuffer format?

Custom fonts are implemented, but it's kind of unclear what format is required?

I think it's 2d pixel arrays for each character (from when I looked at it last).

Overall, I think we can have a separate from-scratch console, just not in ctru itself. We can definitely look into using some existing libraries. GPU rendering would be cool, though sounds like a lot of work to integrate with the 3DS GPU (we'll have to do this eventually I think).
The existing Console struct should probably stay the same, since it's supposed to be a wrapper around the libctru one.

[Meziu]

forces a specific framebuffer format

I thought we could pass in a framebuffer format?

Yes, but there is a very good reason why libctru uses a wacky format and not the standard extended one: the pixel have a smaller size on the framebuffer, thus the CPU has to cycle less. The performance hit of using the console with CPU rendering is very much there, and if you want an app based around it, you will notice it.

[ian-h-chamberlain]

Based on this discussion, I tried to implement my own console and see if I could get it to work.

I've managed to hack a proof of concept together over at https://github.com/ian-h-chamberlain/console_3ds – take a look at let me know what you think!

Some notes about the implementation

• Software rendering

• There is a crapton of unsafe + messy hacky C bindings. Ideally we could just leverage ctru-sys or libc, but a lot of this stuff seems very newlib- or toolchain-specific

• Only bottom screen + stdout for now, but I think the rest ought to be doable

• No scrolling or ANSI code support yet

• I picked a random free font, but we might want to try a few different ones and see what makes sense. Most fonts are not optimized for this pixel density, it seems. Can also look into subpixel rendering

• Framebuffer format would need to be configurable, right now it's strictly Rgb565

• Font loading is pretty slow in debug mode – maybe we can investigate other libraries that can do it statically at build time instead?

[AzureMarker]

Cool! It looks like the C bindings are mostly to get stdout working?

[ian-h-chamberlain]

Yeah, it's basically #include <sys/iosupport.h> plus a handful of handwritten bindings... since I'm not actually using the majority of the fields there, I might be able to tweak the bindgen command to make it a little less... sizeable, or even just write them by hand.

Probably it would make sense to break those pieces out as a stdio-sys crate or something, or even move it to ctru-sys ? I'm not sure if downstream users or ctru itself would be likely to use these bindings ever as they are pretty low-level and modifying global state.

[ian-h-chamberlain]

To make this console API a little better, I'm experimenting with a Console trait that could have multiple implementations (GPU text rendering, console with a scrollback buffer, etc.)

I think to start out it makes sense for the API to match what we have in ctru::console, i.e. fn init(screen: RefMut<'a, dyn Screen>) -> Self – the only problem is, the current Screen API doesn't expose a way to get the raw frame buffer, which is needed when software rendering.

What do you think about having either a struct TopScreenLeft or something and adding get_raw_framebuffer to trait Screen? Otherwise I'm not sure how to make this generic enough for use with both screens (admittedly, the right side of the top screen would probably almost never be used for a console, but ... maybe someone will have some crazy use case).

Alternatively, I could probably just have the API accept a RefMut<'screen, FrameBuffer<'screen>> (edit: realized this can just be a RawFrameBuffer<'screen>, which is a little easier) or something, but we'd have to change how get_raw_framebuffer works in that case. Then the caller would be responsible for picking the screen and handing out its buffer.

Thoughts?

[Meziu]

I’d wait on any of this for more extended control on GPU rendering and such, as the API’s for a Citro3D port will definetly shape our ctru::gfx module. This isn’t needed now, as there is the native alternative.