Cross-Platform Language 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):

     python3 tools/apigen/generate_android.py -j
     

  2. Run beamsplitter to update JavaScript/TypeScript bindings and C++ JSON settings serialization:

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