ABI C et services de l’hôte

Exportations du module

Chaque bibliothèque de script exporte 7 fonctions C (mtr_native.h ; les macros d’enregistrement les génèrent toutes automatiquement) :

Entrée et sortie de frame

JcmFrameInput (hôte → module)

typedef struct JcmFrameInput {
    uint32_t abi_version;              /* version ABI négociée */
    int32_t  resource_kind;            /* MtrResourceKind : vehicle/pids/eyecandy/lift/psd */
    const void* snapshot;              /* le Jcm*Snapshot correspondant */
    void*    state;                    /* bloc d'état par instance, alloué par l'hôte */
    size_t   state_size;
    const struct JcmHostServices* host;/* services de l'hôte appelables depuis le thread de rendu */
} JcmFrameInput;

Conventions internes de l’instantané : tous les champs *_offset sont des décalages en octets relatifs au premier octet de l’instantané ; string_pool_offset/len décrit l’emplacement du pool de chaînes UTF-8 partagé. Les enveloppes du SDK font tout l’adressage à votre place.

JcmFrameOutput (module → hôte)

La sortie est un flux plat d’enregistrements + cinq zones — une « zone » (arena) est un grand bloc de mémoire préalloué, alloué séquentiellement au fil de la frame puis restitué d’un bloc à sa fin — dès que mtrRender retourne, l’hôte lit la sortie et récupère la frame (le double tampon entre modules est assuré par l’hôte) :

Depuis ABI 9, la sortie donne aussi la capacité complète de chaque zone — l’hôte ne crée qu’un seul ByteBuffer par zone, dont seul le limit change à chaque frame ; plus aucune allocation de cinq objets d’emballage par frame.

Enregistrements de dessin

Chaque enregistrement commence par un JcmRecordHeader{kind, flags, record_size}, en ordre séquentiel à longueur variable. flags porte des commutateurs au niveau de l’enregistrement : actuellement, seul MTR_RECORD_FLAG_NATURAL_LIGHT est défini (l’option natural_light() de Text / Texture / Rect — prend la lumière du monde au lieu de la luminosité maximale de rendu). Cet octet a été promu sur place depuis un octet de padding : les modules compilés avec d’anciens SDK écrivent toujours 0 et les anciens hôtes l’ignorent — compatibilité binaire dans les deux sens, sans saut de version d’ABI. 8 types :

Pour rejouer ces enregistrements, l’hôte emprunte exactement le même chemin de code de rendu que les scripts JS (PIDSDrawCall / ScriptRenderManager) — le résultat à l’écran est identique.

Services de l’hôte

JcmHostServices est une table de pointeurs de fonctions (in->host), appelable depuis le thread de rendu. Sur les anciens hôtes, les emplacements ajoutés récemment valent null ; testez la vacuité avant l’appel pour rétrograder proprement :

Évolution des versions d’ABI

L’hôte accepte les modules ABI 6–13 (chacun est alimenté selon la disposition de son époque et rapporte son propre numéro d’ABI). Compiler avec le SDK actuel produit des modules ABI 13 :

Couche de transport (interne à l’hôte, invisible pour les scripts)

Depuis 2.3.0-beta-2.yanyang.6 (layout v2), le mod est totalement dépourvu de JNI : deux plans d’appel portent l’intégralité du trafic inter-langages — le plan Panama FFM (JDK 22+, libraryLookup + downcalls jcm_* + vtable d’upcalls) et le plan de scrutation en mémoire partagée (tout JDK ≥ 16 ; un thread poller d’arrière-plan démarré par le constructeur du pont découvre la région par une poignée de main via le système de fichiers, tout est servi via des pages partagées). Le code des scripts n’en a absolument pas conscience — le module ne voit que l’ABI C décrite ci-dessus.

Ensuite : Performance et débogage — rendre les scripts rapides et stables.