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 colour: the lightest way to build background blocks, separator bars and status colour 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) — the automatic z-ordering step (0.0002 by default)

Render layers (the MtrRenderLayer enum of 2D layers, 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 are pushed onto a stack, and compile() compiles the current stack into a matrix set written into the frame 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) (the in-car announcement, audible only to riding players).

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

GraphicsTexture (pixel canvas)

The GraphicsTexture from <mtr/gfx.hpp> keeps the pixel buffer inside your module; the game side receives only dirty-rectangle uploads—pixel data is not carried across the boundary frame after 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
    // Stick the texture onto 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 plain set_pixel)
    // 2. Upload only the changed region:
    s.tex.upload(ctx.frame());
}

The same header also provides LcdCanvas—an LCD paintbrush built on the built-in 5×7 dot-matrix font (lit/unlit colours configurable), well suited to classic dot-matrix screens.

Gfx2D software rasteriser

<mtr/gfx2d.hpp> implements the commonly used subset of java.awt.Graphics2D as a deterministic software rasteriser that draws straight onto a GraphicsTexture. fillRect / fillOval / drawLine / GeneralPath / clip / drawString logic from JS resource packs can be ported 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();

Colour 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 colours composite with src-over; opaque colours take a fast path.

Font stack

Three tiers of fonts, degrading automatically by availability:

Metric conventions of the built-in font: ascent = 0.78 em, descent = 0.22 em (≈ Arial / HanSans); full-width CJK advances 1.0 em. Resource-font metrics (the measure_font_text host service) are computed from the real font.

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