# 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 #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.