65 lines
2.0 KiB
Markdown
65 lines
2.0 KiB
Markdown
<!-- file: docs/development/007-ANDROID_JNI_BRIDGE.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Bridge Java/JNI Android
|
|
|
|
## Objectif
|
|
|
|
Le bridge Java/JNI sert uniquement aux services réellement Android qui ne sont pas déjà fournis de manière portable par SDL3.
|
|
|
|
L'input tactile de base ne passe pas par JNI : SDL3 fournit directement les événements de doigt et le moteur les convertit en `PointerState`.
|
|
|
|
## Contrat V1
|
|
|
|
La baseline expose un unique appel Java vers Rust :
|
|
|
|
```text
|
|
NativeBridge.nativeContractVersion() -> 2
|
|
```
|
|
|
|
`SaseGameActivity` vérifie ce contrat après `SDLActivity.onCreate()`.
|
|
|
|
Cette vérification détecte au démarrage :
|
|
|
|
- bibliothèque Rust non chargée ;
|
|
- symbole JNI absent ;
|
|
- divergence de version de bridge.
|
|
|
|
## Extension future
|
|
|
|
Les futurs services pourront ajouter des opérations dédiées pour :
|
|
|
|
- haptique Android ;
|
|
- partage natif ;
|
|
- facturation ;
|
|
- publicité ;
|
|
- notifications ;
|
|
- autres services dépendants du framework Android.
|
|
|
|
Ils ne doivent pas servir à réimplémenter les entrées, fenêtres ou événements déjà couverts par SDL3.
|
|
|
|
## Sécurité Rust
|
|
|
|
L'export JNI utilise un symbole nommé explicitement et reçoit deux pointeurs opaques JNI qui ne sont pas déréférencés.
|
|
|
|
Aucun bloc `unsafe` ni fonction `unsafe` n'est autorisé.
|
|
|
|
Si un futur service nécessite de manipuler réellement `JNIEnv`, il devra faire l'objet d'une tranche distincte avec une politique FFI réévaluée plutôt que d'élargir implicitement l'exception actuelle.
|
|
|
|
## Back Android
|
|
|
|
Le contrat v2 ajoute un pont Java/JNI explicite pour Back :
|
|
|
|
```text
|
|
SaseGameActivity
|
|
-> NativeBridge.requestPlatformBack()
|
|
-> nativeRequestPlatformBack()
|
|
-> engine-v1-sdl::request_platform_back()
|
|
-> EngineGame::quit_requested(QuitSource::PlatformBack)
|
|
```
|
|
|
|
Sur API 33+, `SaseGameActivity` enregistre un `OnBackInvokedCallback`.
|
|
Sur les versions antérieures, `onBackPressed()` reste le fallback.
|
|
|
|
Cette voie remplace la dépendance au mapping variable du bouton Back vers `SDL_SCANCODE_AC_BACK`.
|