Canvas

INCLUDE 'os/canvas/-'

This file exposes the os::canvas library, which allows the management of canvases (i.e. windows and terminals). The aim of the library is to provide support for basic input and output in terminals, simple TUI applications in terminals, and graphical applications in windows. Furthermore, the terminal and window canvas interfaces aim to both be valid back-ends for GUI libraries, allowing generic UI applications to be run in both terminals and windows. Additionally, support for hardware-accelerated window rendering will be accessible through the window interface, allowing for platform-independent 3D applications to be written.

It exports the following types and functions:

::os::canvas Canvas VIRTUAL -> os::in::Target
{
    STATIC hosted() Canvas *;
}
::os::canvas Graphical VIRTUAL -> Canvas {}
::os::canvas Textual VIRTUAL -> Canvas {}

::os::canvas Unsupported -> std::Error {}

::os::canvas Terminal -> canvas::Textual {}
::os::canvas TextSurface -> canvas::Textual {}

::os::canvas Window -> canvas::Graphical {}
::os::canvas PixelSurface -> canvas::Graphical {}

Window is a window with a graphical canvas, while Terminal has a text canvas and runs inside a terminal application. Terminals are used for text output and textual interfaces, while windows are used for graphical applications. These classes both create a native OS window upon construction. To get a handle to the canvas the program is run in (if any), call Canvas::hosted(), which returns NULL if the program does not run inside a terminal. This canvas is optionally passed along the os::launch command. Via run-time type checking, determine the kind of canvas the program is run in:

• A Terminal canvas is supplied for programs running inside a terminal window.
• A PixelSurface canvas is supplied for programs running inside a HTML5 canvas.
• Other cases might exist, a sandboxed program might have been launched inside a TextSurface canvas, and possibly, a program might have been launched from within another Window.

Canvas management

Using the os::in::Target API, canvases expose access to user input (mouse, keyboard, joysticks), as well as text/graphics rendering functions. Canvases are categorised into graphical and textual canvases: graphical canvases are pixel-based rendering surfaces, while textual surfaces are character grids, like terminals or the VGA text mode. The canvas constructors allow the creation of windows and terminals that are displayed to the user, as well as text and pixel surfaces for "off-screen" rendering into memory.

Some canvas features, such as title bars, full screen windows, border-less windows, etc. are exposed but do not necessarily have to exist. In such cases, an os::canvas::Unsupported error is thrown. An example of this might be a program running on a server without graphics support or some kind of sandbox, it might not be able to create additional canvases and could be bound to the hosted terminal. Also, such an application might only have access to a simple std::io::OStream for output. These conditions all generate this error when attempting to use functions that require additional capabilities.

To detect input to a canvas, use the os::input::Target functionality.

Rendering

To support a wide range of platforms while maintaining good performance, the rendering API of graphical canvases is designed with modern graphics library standards such as WebGPU and older standards such as WebGL in mind. The rendering API is designed to allow for compatibility with older standards by providing a more abstract and high-level rendering interface, while optionally also exposing more specific and low-level operations that map more directly to newer standards. The higher-level operations are guaranteed to work for older standards such as WebGL, while the low-level operations are only guaranteed to work for newer standards.