bindings-synchronization

---
name: bindings-synchronization
description: >
  Guidelines and SOP for synchronizing public C++ API changes (methods, enums, options structs) 
  to Java (Android JNI) and JavaScript/TypeScript (Web/WASM Embind).
---

# 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.