18
0
mirror of https://github.com/MaSzyna-EU07/maszyna.git synced 2026-11-19 01:46:01 +01:00
Files
maszyna/wasm_screens_doc.md
2026-11-10 00:57:37 +01:00

8.6 KiB

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:

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