Drawing and canvases

Text / Texture / Rect (PIDS)

<mtr/text.hpp> is a 1:1 port of the JS TextWrapper / TextureWrapper / Rect fluent APIs — method names follow the C++ snake_case convention, and calls are chained:

mtr::Text::create()
    .text("Tsim Sha Tsui")
    .scale(1.725)
    .size(100, 9)
    .stretch_xy()
    .font_mc()
    .color(0xFC9700)
    .pos(3, rowY)
    .draw(ctx);

Rect (solid rectangles)

mtr::Rect mirrors the upstream JS Rect class (renamed from Rectangle as of upstream v2.3.0-prerelease.2; the Java class name is unchanged) — it draws a full-UV quad of mtr:white.png tinted with a color: the lightest way to build background blocks, separator bars and status color strips:

mtr::Rect::create()
    .color(0xFF00539F)          // opaque tint (default ARGB_WHITE)
    .pos(2, rowY + 18)
    .size(pids.width() - 4, 1)  // default 20x20
    .draw(ctx);

Companion context methods (PidsContext):

• ctx.set_auto_z_ordering(bool) — automatic z-ordering (on by default)
• ctx.set_z_order_step(step) — automatic z-ordering step (0.0002 by default)

Render layers (the 2D layer enum MtrRenderLayer, independent of mtr::Matrices): MTR_LAYER_TEXT (text), MTR_LAYER_LIGHT (light-emitting objects), MTR_LAYER_EXTERIOR / MTR_LAYER_INTERIOR (exterior / interior), matching MTR's QueuedRenderLayer.

Matrices and model drawing

<mtr/matrices.hpp> mirrors the JS global Matrices: transforms push onto a stack, and compile() compiles the current stack into a matrix set written into the frame's matrix arena:

mtr::Matrices m;
m.translate(0.5f, 1.0f, 0.0f);
m.rotate_y_degrees(90.0f);
m.scale(1.0f, 1.0f, 1.0f);
ctx.draw_car_model(model_handle, car_index, &m);   // vehicle
ctx.draw_model(model_handle, &m);                   // eyecandy / lift

The vehicle context additionally offers draw_bogie_model(model, car, bogie, matrices) (bogies), play_car_sound(sound, car, x, y, z, volume, pitch), and play_ann_sound(sound, volume, pitch) (announcements audible only to riding players).

Model handles come from the host services: ctx.host()->acquire_model(user, "namespace:path/model.json") to acquire, release_model(user, handle) to release; acquire_quad_model(...) builds a host-owned textured quad from 4 model-space vertices + UVs (turning a GraphicsTexture into a screen you can mount on a car). See C ABI and host services for details.

GraphicsTexture (pixel canvas)

GraphicsTexture from <mtr/gfx.hpp> keeps the pixel buffer inside your module; the game side only receives dirty-rectangle uploads — pixel data is not hauled across the boundary every frame:

struct LcdState {
    mtr::GraphicsTexture tex;      // Best kept in State: same lifetime as the instance
};

void create(mtr::VehicleContext& ctx, LcdState& s, const mtr::Vehicle&) {
    s.tex.create(ctx.input(), 512, 128);   // Also registers the GPU texture with the host
    // Mount the texture on a car: host->acquire_quad_model(...) → draw_car_model(...)
}

void render(mtr::VehicleContext& ctx, LcdState& s, const mtr::Vehicle& vehicle) {
    // 1. Draw pixels (Gfx2D, or set_pixel directly)
    // 2. Upload only the changed region:
    s.tex.upload(ctx.frame());
}

The same header also provides LcdCanvas — an LCD paintbrush on the built-in 5×7 dot-matrix font (on/off colors configurable), a good fit for classic dot-matrix screens.

Gfx2D software rasterizer

<mtr/gfx2d.hpp> implements the commonly used subset of java.awt.Graphics2D as a deterministic software rasterizer that draws straight onto a GraphicsTexture. The fillRect / fillOval / drawLine / GeneralPath / clip / drawString logic from JS resource packs ports over mechanically:

mtr::Gfx2D g(s.tex, ctx.host(), "jsblock:shanghai");  // canvas + host font

g.set_color(mtr::clr(12, 28, 44));                    // dark background
g.fill_rect(0, 0, W, H);

g.push_clip(8, 8, W - 16, 40);                       // clip stack
g.set_color(mtr::clra(255, 205, 66, 255));
g.draw_text_centered(W / 2, 30, 18.0, "下一站 Next");
g.pop_clip();

Color helpers: mtr::clr(r, g, b) / mtr::clra(r, g, b, a) (opaque / with alpha), matching the same-named functions in the JS config.js. Semi-transparent colors composite with src-over; opaque colors take a fast path.

Font stack

Three font tiers, falling back automatically by availability:

Metric conventions of the built-in font: ascent = 0.78 em, descent = 0.22 em (≈ Arial / HanSans); CJK full-width glyphs advance 1.0 em. Resource-pack fonts are measured (measure_font_text host service) with their real font metrics.

Up next: mtr::Api and Java interop — everything beyond the snapshots.