Dessin et canevas

Text / Texture / Rect (PIDS)

<mtr/text.hpp> est le portage 1:1 de l’API en chaîne TextWrapper / TextureWrapper / Rect de JS — les noms de méthodes suivent la convention snake_case du C++, avec appels chaînés :

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 (rectangles pleins)

mtr::Rect est le miroir de la classe Rect du JS amont (nommée Rectangle avant l’amont v2.3.0-prerelease.2 ; le nom de la classe Java est inchangé) — elle dessine une facette mtr:white.png aux UV complets, teintée d’une couleur : le moyen le plus léger de construire des blocs de fond, des barres de séparation et des bandes de couleur d’état :

mtr::Rect::create()
    .color(0xFF00539F)          // teinte opaque (ARGB_WHITE par défaut)
    .pos(2, rowY + 18)
    .size(pids.width() - 4, 1)  // 20×20 par défaut
    .draw(ctx);

Méthodes associées du contexte (PidsContext) :

• ctx.set_auto_z_ordering(bool) — ordre z automatique (activé par défaut)
• ctx.set_z_order_step(step) — pas de l’ordre z automatique (0.0002 par défaut)

Couches de rendu (énumération 2D MtrRenderLayer, indépendante de mtr::Matrices) : MTR_LAYER_TEXT (texte), MTR_LAYER_LIGHT (éléments lumineux), MTR_LAYER_EXTERIOR / MTR_LAYER_INTERIOR (extérieur / intérieur), alignées sur le QueuedRenderLayer de MTR.

Matrices et dessin de modèles

<mtr/matrices.hpp> est le miroir du Matrices global de JS : les transformations sont empilées, et compile() compile la pile courante en un jeu de matrices écrit dans la zone de matrices de la frame :

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);   // véhicule
ctx.draw_model(model_handle, &m);                   // eyecandy / ascenseur

Le contexte véhicule propose en outre draw_bogie_model(model, car, bogie, matrices) (bogies), play_car_sound(sound, car, x, y, z, volume, pitch) et play_ann_sound(sound, volume, pitch) (annonces de station audibles uniquement par les joueurs à bord).

Les handles de modèle proviennent des services de l’hôte : ctx.host()->acquire_model(user, "namespace:path/model.json") pour l’acquisition, release_model(user, handle) pour la libération ; acquire_quad_model(...) construit une facette texturée détenue par l’hôte à partir de 4 sommets en espace modèle + UV (transformant une GraphicsTexture en écran applicable sur une voiture). Détails dans ABI C et services de l’hôte.

GraphicsTexture (canevas de pixels)

Dans <mtr/gfx.hpp>, GraphicsTexture garde le tampon de pixels dans votre module ; le jeu ne reçoit que des téléversements de rectangles modifiés — les données pixel ne traversent pas la frontière à chaque frame :

struct LcdState {
    mtr::GraphicsTexture tex;      // à placer dans State : même cycle de vie que l'instance
};

void create(mtr::VehicleContext& ctx, LcdState& s, const mtr::Vehicle&) {
    s.tex.create(ctx.input(), 512, 128);   // enregistre en même temps la texture GPU auprès de l'hôte
    // appliquer la texture sur la voiture : host->acquire_quad_model(...) → draw_car_model(...)
}

void render(mtr::VehicleContext& ctx, LcdState& s, const mtr::Vehicle& vehicle) {
    // 1. dessiner les pixels (Gfx2D ou set_pixel directement)
    // 2. ne téléverser que la zone modifiée :
    s.tex.upload(ctx.frame());
}

Le même en-tête fournit aussi LcdCanvas — un pinceau LCD fondé sur la police matricielle intégrée 5×7 (couleurs allumée/éteinte configurables), adapté aux écrans à matrice de points classiques.

Rastériseur logiciel Gfx2D

<mtr/gfx2d.hpp> réimplémente le sous-ensemble usuel de java.awt.Graphics2D en rastériseur logiciel déterministe, dessinant directement dans une GraphicsTexture. Les logiques fillRect / fillOval / drawLine / GeneralPath / clip / drawString des packs de ressources JS se portent mécaniquement :

mtr::Gfx2D g(s.tex, ctx.host(), "jsblock:shanghai");  // canevas + police de l'hôte

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

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

Aides couleurs : mtr::clr(r, g, b) / mtr::clra(r, g, b, a) (opaque / avec alpha), homonymes des fonctions du config.js de JS. Les couleurs semi-transparentes passent par une composition src-over ; les couleurs opaques bénéficient d’un chemin rapide.

Système de polices

Trois niveaux de polices, avec rétrogradation automatique selon la disponibilité :

Conventions de métriques de la police intégrée : ascent = 0.78 em, descent = 0.22 em (≈ Arial / HanSans) ; pas de 1.0 em pour les CJK pleine chasse. Les métriques des polices de ressource (service de l’hôte measure_font_text) sont calculées sur la police réelle.

Ensuite : mtr::Api et interopérabilité Java — tout ce qui n’est pas dans l’instantané.