mirror of
https://github.com/MaSzyna-EU07/maszyna.git
synced 2026-11-19 06:26:01 +01:00
130 lines
8.6 KiB
Markdown
130 lines
8.6 KiB
Markdown
# WebAssembly screens
|
|
|
|
Screens drawn by WebAssembly modules, alongside the Python screens (`pyscreen:`, `pydestinationsign:`). A module
|
|
gets the same input a Python screen gets (the table in `python_var_doc.md`), returns an RGBA image and, in the cab,
|
|
may send commands. The modules run in the WAMR interpreter (`ref/wamr`), in a sandbox: a module reaches nothing but
|
|
the functions of the `eu07` module below, and reads files only from its own folder.
|
|
|
|
Unlike a Python screen, which refreshes after a time (`python.updatetime`, `updatetime:`), a WebAssembly screen
|
|
refreshes every so many rendered frames, set in `eu07.ini`.
|
|
|
|
## eu07.ini
|
|
|
|
| key | default | meaning |
|
|
|-----------------------|---------|--------------------------------------------------------------------------------|
|
|
| `wasm.enabled` | 1 | 0: no WebAssembly screens; the vehicles show what they did before |
|
|
| `wasm.cabframes` | 4 | a screen in the cab is refreshed every so many frames (1-1000) |
|
|
| `wasm.externalframes` | 30 | a screen outside the cab (destination sign) is refreshed every so many frames |
|
|
|
|
A screen may ask for a longer interval of its own (`frames:` below); the longer of the two counts. Screens sharing
|
|
an interval are spread over its frames, so they don't all refresh on the same one. A screen in the cab is refreshed
|
|
only while the player sits in that cab, a screen outside only while its vehicle is drawn.
|
|
|
|
## .mmd
|
|
|
|
In the cab section, next to `pyscreen:`:
|
|
|
|
```
|
|
wasmscreen: { ekran.wasm target: screen01 frames: 6 parameters: id=1&mode=full }
|
|
```
|
|
|
|
| key | meaning |
|
|
|---------------|---------------------------------------------------------------------------------------------------|
|
|
| (first token) | the module, relative to the vehicle folder when it has no path of its own |
|
|
| `target:` | the submodel the screen is drawn on (its texture is replaced); `none` for a screen that only sends commands |
|
|
| `frames:` | the screen's own refresh interval, used when longer than `wasm.cabframes` |
|
|
| `parameters:` | extra `key=value` pairs, `&`-separated, added to the input |
|
|
|
|
A touch on the screen's submodel comes in the input as the list of points `touches`, as for the Python screens.
|
|
|
|
In `internaldata:`, next to `pydestinationsign:`:
|
|
|
|
```
|
|
wasmdestinationsign: { tablica.wasm frames: 60 instance: name background: tablica_off parameters: style=lcd }
|
|
```
|
|
|
|
The keys are those of `pydestinationsign:` (`instance:`, `parameters:`, `background:`) and `frames:`. The input is
|
|
what a Python sign gets: the timetable (`$timetable`), `_id1` (the train), `_id2` (the instance) and the
|
|
parameters, read anew on every refresh, so the sign can follow the journey. The vehicles of one train showing the
|
|
same request share one screen and one texture. A static destination texture, when there is one, still comes first.
|
|
|
|
A vehicle may have both `pydestinationsign:` and `wasmdestinationsign:`: with the WebAssembly screens on, the
|
|
WebAssembly one is used; with them off (or in a release without them) the Python one. An unknown key in either block
|
|
is skipped together with its value.
|
|
|
|
## The module
|
|
|
|
Exports:
|
|
|
|
| export | meaning |
|
|
|-------------------------------|------------------------------------------------------------------------------------------|
|
|
| `memory` | the linear memory |
|
|
| `screen_init() -> i32` | optional; called once after loading. anything but 0 disables the screen |
|
|
| `screen_render() -> i32` | called on every refresh. returns the address of the image, or 0 to keep the previous one |
|
|
| `screen_width() -> i32` | the width of the image, asked after every `screen_render` that returned an image |
|
|
| `screen_height() -> i32` | the height of the image, up to 4096 on either side |
|
|
|
|
The image is `width * height` pixels of 4 bytes, R G B A, in sRGB, its rows in the order the Python screens give
|
|
them (PIL's `tobytes()`).
|
|
|
|
Imports, module `eu07` (keys and texts are a pointer and a length in bytes, in the module's memory):
|
|
|
|
| import | meaning |
|
|
|-----------------------------------------------------------------|-----------------------------------------------------------------|
|
|
| `value_type(key, key_len) -> i32` | 0 no such value, 1 float, 2 int, 3 bool, 4 string, 5 list of points |
|
|
| `get_float(key, key_len) -> f64` | the value as a number (int and bool too); 0 when there is none |
|
|
| `get_int(key, key_len) -> i32` | the value as an integer (a float is truncated) |
|
|
| `get_bool(key, key_len) -> i32` | 1 or 0 |
|
|
| `get_string(key, key_len, buffer, capacity) -> i32` | copies the text, in UTF-8; returns its whole length, -1 when there is none |
|
|
| `get_vec2_count(key, key_len) -> i32` | the number of points in a list (`touches`) |
|
|
| `get_vec2(key, key_len, index, out) -> i32` | writes the point as two f32 at `out`; returns 1, or 0 when there is none |
|
|
| `command(name, name_len, param1, param2)` | sends a command (the names of `simulation::commandMap`) to the vehicle of the cab; ignored outside the cab |
|
|
| `log(text, text_len)` | writes a line to the log |
|
|
| `time() -> f64` | seconds of a steady clock shared by all screens, for animations (scrolling) that keep their pace whatever the refresh interval |
|
|
| `led_post(source, width, height, target, bloom) -> i32` | `led_util.render_post()` of the Python screens, run natively: each diode of the `width x height` image becomes 2x2 pixels with a darker grid, glowing into its neighbours when `bloom` is not 0, in a 1 pixel black frame; `target` takes `(2 width + 2) x (2 height + 2)`. returns 1, or 0 for sizes over 4096 |
|
|
| `resize_lanczos(source, width, height, target, target_width, target_height) -> i32` | Pillow's `resize(..., Image.LANCZOS)`, run natively, giving the same pixels. returns 1, or 0 for sizes over 4096 |
|
|
| `file_read(path, path_len, buffer, capacity) -> i32` | reads a file from the module's folder or below; returns the file's whole size, -1 when there is none or the path leads outside |
|
|
|
|
`led_post` and `resize_lanczos` take RGBA images in the module's memory and write alpha 255; the source and the
|
|
target may overlap. They are what makes LED boards fast enough: in the interpreter the same filters take some 30
|
|
times longer.
|
|
|
|
A call into the module may run at most 200 million instructions; a module that traps or runs over is disabled and
|
|
the reason goes to the log. The module gets 64 KiB of stack and no heap from the host: it manages its own memory.
|
|
|
|
## Building a module
|
|
|
|
With clang (any version with the `wasm32` target), no C library:
|
|
|
|
```c
|
|
// ekran.c
|
|
#include <stdint.h>
|
|
|
|
#define IMPORT(name) __attribute__((import_module("eu07"), import_name(name)))
|
|
IMPORT("get_float") double get_float(const char *key, int key_len);
|
|
IMPORT("command") void command(const char *name, int name_len, int param1, int param2);
|
|
|
|
#define WIDTH 256
|
|
#define HEIGHT 128
|
|
static uint32_t pixels[WIDTH * HEIGHT];
|
|
|
|
__attribute__((export_name("screen_width"))) int screen_width(void) { return WIDTH; }
|
|
__attribute__((export_name("screen_height"))) int screen_height(void) { return HEIGHT; }
|
|
|
|
__attribute__((export_name("screen_render"))) int screen_render(void) {
|
|
double const velocity = get_float("velocity", 8);
|
|
int const filled = (int)(velocity * WIDTH / 160.0);
|
|
for (int y = 0; y < HEIGHT; ++y)
|
|
for (int x = 0; x < WIDTH; ++x)
|
|
pixels[y * WIDTH + x] = x < filled ? 0xFF00C000u : 0xFF202020u; // A B G R, little-endian
|
|
return (int)(uintptr_t)pixels;
|
|
}
|
|
```
|
|
|
|
```
|
|
clang --target=wasm32 -O2 -nostdlib -Wl,--no-entry -o ekran.wasm ekran.c
|
|
```
|
|
|
|
Any language that compiles to WebAssembly works the same way (Rust `wasm32-unknown-unknown`, Zig, AssemblyScript),
|
|
as long as the module imports nothing but the `eu07` functions above.
|