Memory layout
Memory layout of data structures shared with the runtime
Exports
The application must provide the following exports for the host to call:
| Name |
Type |
Description |
| OS |
OS |
This contains all state shared by the host and the app. It's used by the app to check for inputs and update the screen. |
| init |
(os: *os) => *void |
The host calls this function when the WebAssembly module is initialised. The first argument is a pointer to the shared OS data. It can return a pointer to any app specific state, which will then be passed by the host to the frame function. |
| frame |
(os: *os, app_state: *void, dt: f64) => void |
This function is called by the host to request a new frame. The first argument contains the pointer to the shared OS data, the second argument contains a pointer to any app specific state returned by init, and the third parameter is a double precision float containing the amount of time passed since the previous frame. In a browser this will typically be called at 60 FPS however it can vary. |
Types
OS
| Offset (hex) |
Offset (decimal) |
Type |
Size (bytes) |
Name |
Description |
| 0x000000 |
0 |
Config |
256 |
Config |
See Config section below |
| 0x000100 |
256 |
u8[] |
256 |
Inputs |
Each byte in this range corresponds to the state of an input. For keypresses, the value will be set to 1 when the key is initially pressed down, and reset to 0 when the key is released. You may want to reset the value to zero if you only want to capture the initial event, that way you'll receive further keyboard repeats. |
| 0x000200 |
512 |
|
2560 |
Reserved |
|
0x000C00 |
3072 |
Screen Data |
65536 |
Characters |
Specifies the index of the character to display in a given cell. Full-width characters use two bytes, where the first character must be set to 255 to tell the renderer that it's a full-width character, and the following byte specifies the index of the full-width character to display. |
| 0x010C00 |
68608 |
Screen Data |
65536 |
Background Color |
Specifies the index of the palette colour to use as the background for this cell. |
| 0x020C00 |
134144 |
Screen Data |
65536 |
Foreground Color |
Specifies the index of the palette colour to use as the foreground for this cell. |
Config
| Offset (hex) |
Offset (decimal) |
Type |
Size (bytes) |
Name |
Description |
| 0x000000 |
0 |
u8 |
1 |
Columns |
The number of horizontal cells to display |
| 0x000001 |
1 |
u8 |
1 |
Rows |
The number of vertical cells to display |
| 0x000002 |
2 |
u8 |
1 |
Max Columns |
(Set by the runtime) The maximum number of horizontal cells that can be displayed. Can change if the user resizes their window. |
| 0x000003 |
3 |
u8 |
1 |
Max Rows |
(Set by the runtime) The maximum number of vertical cells that can be displayed. Can change if the user resizes their window. |
| 0x000004 |
4 |
|
252 |
Reserved |
|
Screen Data
| Offset (hex) |
Offset (decimal) |
Type |
Size (bytes) |
Name |
Description |
| 0x000000 |
0 |
u8 |
1 |
Update Flag |
The application must set this value to 1 if it has updated any of the values in this struct since the previous frame. The host will reset this to 0 when it uploads the data to the GPU. If the data is not updated between frames, it's best to leave it at zero so the host can avoid doing unnecessary work (and saving the user's battery). |
| 0x000001 |
1 |
u8[] |
65535 |
Cell data |
Each byte of this array represents the associated value for a cell on screen, whether that's ASCII code or palette index. The cells are scanned first in the x direction, then line by line. For example for an 80x30 screen, these values would represent the positions for
[(0, 0), (1, 0), (2, 0), .... (80, 0), (0, 1), (1, 1), ...] |