bindings-synchronization

# Cross-Platform Language Bindings Synchronization When making changes to public Filament C++ APIs, AI agents **must** ensure the changes are mirrored in the Java and JavaScript/TypeScript binding layers. --- ## 1. Trigger Conditions You must check and update the language bindings if your changes touch any public headers under `filament/include/filament/`, specifically: - **New/Modified/Deleted Methods** on core classes (e.g., `View`, `Engine`, `Camera`, `LightManager`, `RenderableManager`). - **Options Structs** (e.g., `AmbientOcclusionOptions`, `BloomOptions`, `FogOptions`). > [!IMPORTANT] > If you modify options structs defined in `filament/include/filament/Options.h`: > 1. **Run `apigen`** to regenerate `View.java` and `View.cpp` (which host the Java POJO options structs and JNI bridges): > ```bash > python3 tools/apigen/generate_android.py -j > ``` > 2. **Run `beamsplitter`** to update JavaScript/TypeScript bindings and C++ JSON settings serialization: > ```bash > cd tools/beamsplitter && go run . > ``` - **Enums & Constants** (e.g., `BlendMode`, `QualityLevel`, `AntiAliasing` under `filament/include/filament/` or nested inside classes). --- ## 2. Java & Android JNI Synchronization All JNI JNI-exported functions use automatic symbol resolution (dynamic mapping), meaning they are mapped by signature rather than a static registration table. ### File Mappings - **Java Class**: `android/filament-android/src/main/java/com/google/android/filament/<ClassName>.java` - **JNI C++ Wrapper**: `android/filament-android/src/main/cpp/<ClassName>.cpp` ### Guidelines 1. **API Consistency**: Keep method visibility `public` (unless the API is strictly internal to the Java package). Follow Java naming conventions (camelCase). 2. **Getter/Setter Completeness**: If you add a Setter (e.g., `setFoo`), always add the corresponding Getter (e.g., `isFoo` or `getFoo`). 3. **JNI Signature**: - Native declarations in Java must be `private static native`. - The corresponding C++ function in JNI must be decorated with `extern "C" JNIEXPORT <ReturnType> JNICALL Java_com_google_android_filament_<ClassName>_<NativeMethodName>`. - Return values from native C++ booleans should be cast to `jboolean` using `(jboolean)` or `static_cast<jboolean>()`. --- ## 3. JavaScript & TypeScript Synchronization Filament uses Emscripten's Embind to export C++ APIs to JS. ### File Mappings - **Embind Source**: `web/filament-js/jsbindings.cpp` - **Enums Embind Source**: `web/filament-js/jsenums.cpp` - **TypeScript Definition**: `web/filament-js/filament.d.ts` - **JS Extension Wrappers**: `web/filament-js/extensions.js` ### Guidelines 1. **Embind Registration**: - Register member functions in `jsbindings.cpp` within the corresponding `class_<ClassName>("<JSClassName>")` block using `.function("methodName", &ClassName::methodName)`. 2. **TypeScript Declarations**: - Always update `filament.d.ts` to match any changes. Every bound C++ method should have a corresponding declaration inside `export class <ClassName>` to avoid IDE type errors. 3. **Complex Option Structs**: - If you modify or add fields to an options struct (like `BloomOptions`), make sure to: - Register the new fields in `jsbindings.cpp` using `.field("fieldName", &ClassName::Options::fieldName)`. - Update the TypeScript interface in `filament.d.ts` to include the new properties. - Check if `extensions.js` contains a prototype-overrides wrapper for merging the options (e.g., `Filament.View.prototype.setBloomOptions`). Update the default options object if needed. --- ## 4. Verification Check Before concluding a task: 1. Double-check JNI signature signatures against the Java class. 2. Verify that type bindings and return types match up. 3. Verify that TS definitions in `filament.d.ts` are 100% synchronized.