filament-kmp 0.7.0: from four actuals per class to one API generated from C++

[Erkko68]

0.7.0 is out. On the surface it's a source-breaking minor release. Underneath, it rebuilds how the library
binds Filament. This post explains what changed, why we did it, how we got there one step at a time, and
what we learned wrapping a large C++ engine for Kotlin Multiplatform. If you're binding a big native
library in KMP yourself, most of the lessons at the end apply to you.

TL;DR

• Before: every API class was an expect class in commonMain with four hand-written actuals. Each
  one sat on a different underlying binding: upstream's Android Java, our hand-written C (JVM through
  Panama, iOS through cinterop), and upstream's embind filament.js on web.
• Now: every class is written once, in commonMain, and calls one Fila* C API generated from
  Filament's C++ headers. Only the way an external fun reaches its C symbol differs per platform, and
  nobody writes that part by hand.
• The Kotlin API now follows Filament's C++ API (names, owners, overloads, defaults). This is the
  breaking part. The migration guide
  lists every change.

---

Where we were in 0.6.0

KMP's textbook answer to "same API, different implementation per platform" is expect/actual, and
that's how filament-kmp started. Here is Scene in 0.6.0, trimmed to one method:

// commonMain
expect class Scene {
    fun addEntity(entity: Entity)
    fun addEntities(entities: IntArray)
    // …
}

// androidMain: wraps upstream's Java binding from the filament-android AAR
actual class Scene(internal val nativeScene: com.google.android.filament.Scene) {
    actual fun addEntities(entities: IntArray) = nativeScene.addEntities(entities)
}

// jvmMain: Project Panama (FFM) over our hand-written C, through jextract
actual class Scene(internal var nativeHandle: MemorySegment?) {
    actual fun addEntities(entities: IntArray) {
        confined { arena -> FilamentC.FilaScene_addEntities(nativeHandle, arena.ints(entities), entities.size.toLong()) }
    }
}

// nativeMain: cinterop over the same hand-written C
actual class Scene(internal var nativeHandle: CPointer<FilaScene>?) {
    actual fun addEntities(entities: IntArray) {
        entities.usePinned { FilaScene_addEntities(nativeHandle, it.addressOf(0).reinterpret(), entities.size.toULong()) }
    }
}

// webMain: upstream's embind filament.js, through hand-maintained externals
actual class Scene(internal val jsScene: JSScene) {
    // Scene has no getEntities() in C++, only forEach(Invocable), which embind
    // cannot bind, so membership is mirrored here to back getEntities()/forEach().
    private val _entities = mutableSetOf<Int>()
    // …
}

flowchart TB
    E["commonMain: expect class Scene"]
    E --> A["androidMain actual"] --> AJ["upstream Java (filament-android AAR)"] --> F[Filament C++]
    E --> J["jvmMain actual"] --> P["Panama / jextract"] --> C["hand-written C"] --> F
    E --> N["nativeMain actual"] --> CI["cinterop"] --> C
    E --> W["webMain actual"] --> EM["upstream embind filament.js"] --> F

Loading

That's three different underlying APIs, each written by someone else or by hand, for every class. It worked,
and 0.1 to 0.6 shipped on it. The cost grew with every release, though:

• Four sources of truth. Each binding had its own gaps and quirks. In 0.6.0 we tracked 118
  @PlatformGap annotations: methods that did nothing, did something different, or threw on some
  platform. The web actual above keeps its own copy of the scene's entities because embind can't bind
  Scene::forEach.
• Gaps we couldn't close ourselves. On web we could only expose what upstream's filament.js exposed.
  Closing a web gap meant an upstream PR. On Android we were tied to upstream's Java API and to when Google
  published the AARs. 0.5.0 had to force compileSdk = 37 on everyone because the AARs required it.
• The wrong reference. Our API-parity check (check-common-api.sh) compared commonMain against
  upstream's Android Java API, which is itself a lossy, hand-curated copy of the C++ headers.
• Every feature written four times. A new Filament method meant a C function, a Panama call, a
  cinterop call, an Android forwarder and an embind lookup, each with its own types (MemorySegment,
  CPointer, a Java object, a JS object), its own memory handling and its own bugs. The 0.5.0 changelog
  has a "Fixed" list that's mostly one-platform bugs: callbacks leaking on JVM/iOS, Engine.config
  wrong on JVM/iOS, Filamat.init() a no-op on iOS, texture formats falling back on web…
• Platform floors we didn't choose. Panama meant desktop needed JDK 22+.

By 0.6.0 we had about 22,500 lines of platform-specific Kotlin (android 4.6k, jvm 5.4k, native 5.5k,
web 7.0k) and roughly 4,900 actual declarations.

Where we are in 0.7.0

flowchart TB
    H["Filament C++ headers"] -->|"generateCApi"| C["Fila* C API (generated, committed)"]
    C -->|"generateKotlinExternals"| X["commonMain capi: internal external fun FilaScene_addEntity(…)"]
    K["commonMain: class Scene { fun addEntity(e) = FilaScene_addEntity(handle, e) }"] --> X
    X -->|"iOS: @SymbolName, direct call"| C
    X -->|"JVM + Android: JNI, forwarders generated"| C
    X -->|"js + wasmJs: wasm export installed as a global"| C

Loading

Scene today:

// commonMain, the only Scene there is
class Scene @InternalFilamentApi constructor(internal var nativeHandle: NativePointer) {
    fun addEntity(entity: Entity) = FilaScene_addEntity(nativeHandle, entity)

    fun addEntities(entities: IntArray) = interopScope {
        FilaScene_addEntities(nativeHandle, toInterop(entities), entities.size)
    }
    // …
}

It calls an external generated from the C header:

// commonMain/…/capi/FilaScene.kt (generated)
@ExternalSymbolName("FilaScene_addEntity")
internal external fun FilaScene_addEntity(self: NativePointer, entity: Int)

The external binds a C function generated from the C++ header:

// c/filament/generated/FilaScene.cpp (generated)
void FilaScene_addEntity(FilaScene* self, FilaEntity entity) {
    fila::cpp(self)->addEntity(utils::Entity::import(entity));
}

The only expect/actual left is a small interop runtime: what a pointer is, how an array gets
into native memory, and how a callback gets back out.

Declaration	JVM + Android (JNI)	iOS (Kotlin/Native)	js + wasmJs
NativePointer	Long	Long	Int (wasm32 address)
NullPointer	0L	0L	0
ExternalSymbolName	absent	@SymbolName	absent
InteropScope	copies through JNI	pins	copies into the wasm heap
singleThreaded	false	false	true

How we got there

We didn't plan this as one rewrite. It happened in five steps, each shipped on main with every test
suite green on all five targets before the next one started.

1. Web moves onto our C API (#154)

Web was the platform with the most gaps and the least control, so it went first. We compiled our C layer
with Emscripten into our own filament-kmp.wasm and dropped embind entirely. Web suddenly had the same
API as JVM and iOS: shadow types, HDR decoding, IBL prefiltering, morph targets, readPixels and more,
all at once. MaterialBuilder works on web too, through an optional filamat-kmp.wasm.

That PR also proved the idea behind everything that followed. Once the Kotlin externals were generated
from the C headers, web had the same API as the other platforms by construction.

2. Android moves onto our C API (#159)

Android dropped upstream's filament-android, gltfio-android, filament-utils-android and
filamat-android AARs and bound our C API through JNI instead, building one libfilament-c.so per ABI
from upstream's native prebuilts. Upgrades stopped waiting for Google Maven, and Android-only bugs went
away because Android now runs the same C code as everything else. Porting also turned up real bugs: the
generated uberarchive.h was falling through to the Linux size on Android, so UbershaderProvider found
no materials.

After this step every platform called the same C API, but each still had its own actual, calling
that C API with its own pointer type.

3. Write each class once (#162)

This is the step that removed expect/actual from the API, and the model comes straight from
skiko, which binds Skia the same way. In commonMain you can
declare an external fun, and each Kotlin backend reads it differently:

• Kotlin/Native: with @SymbolName (through an optional expectation, so common code can use it) the
  call goes straight to the C symbol. No cinterop stubs; the cinterop only packs the static libraries into
  the klib.
• JVM and Android: it's a JNI native method. A build task scans the common externals and writes one
  Java_… forwarder each. The forwarders include the real C headers, so the C compiler rejects a Kotlin
  declaration that disagrees with the C prototype.
• js and wasmJs: an external fun with no module resolves to a global of the same name. The wasm
  runtime copies every _FilaX export onto globalThis.FilaX at startup.

Because JVM desktop and Android now share a jniMain source set, Project Panama and jextract went
away, and the desktop JDK floor dropped from 22 to 17. The same PR collapsed the build around one
registry of native targets and one CMake entry point, and deleted ~38k lines.

4. Generate the C API from the C++ headers (#163, #171)

At this point the C layer itself was the last hand-written translation of Filament's API, and the last
thing tying us to a reference that wasn't the headers. So we built a generator:

include/ (Filament headers)
   │  c/api-headers.txt: which headers, which C module, what to skip, and why
   ▼
clang JSON AST ─► C++ API model ─► generateCApi ──────────► c/<module>/generated   (committed)
                                   generateKotlinExternals ─► <module>/capi/*.kt    (committed)
                                   generateBindings ───────► JNI forwarders, wasm tables (build/)

A few decisions shaped it:

• The scope is declared, not inferred. c/api-headers.txt lists the headers that count as API, and
  -filament::View::setDebugCamera-style lines leave declarations out. Every skip carries a comment
  saying why, and a skip line that matches nothing fails the build, so the list can't quietly go stale
  across upgrades.
• One C mapping per C++ shape. Classes become opaque handles. Value structs (BloomOptions,
  Engine::Config) become handles with _create/_destroy and a getter/setter per field, seeded with
  C++'s defaults, so struct layouts never cross the boundary. std::optional becomes a nullable pointer
  or a bool plus out-pointer. std::function becomes a C function pointer plus void* user. Overloads
  get suffixed by the parameter types that tell them apart. Templates are bound for the instantiations a
  table lists.
• A hole for hand-written code, and the generator points at it. What has no mechanical mapping is
  written by hand in c/<module>/manual, and the generated header leaves a note with the C++ signature
  each one replaces. Today that's about 600 lines, next to ~14,000 generated.
• Generated code is committed. After a Filament upgrade, the diff in c/*/generated and capi is
  the review.

Then we moved the modules over one record at a time: filamat, gltfio, filament-utils, then filament's
buffers, Camera, Scene, the managers, Material, View, and finally Engine, after which the
hand-written filament C layer was deleted.

This is also where the Kotlin API changed. With the C API generated from the headers, keeping a Kotlin
API modeled on Android's Java made no sense. The Kotlin API now follows the C++ headers: C++'s class
names, method names, owners, overloads and default values, adapted to Kotlin only where Kotlin has a
shape for it (properties for get/set pairs, nullable results, AutoCloseable). So engine.destroyView(v)
is now engine.destroy(v), View.BloomOptions is now the top-level BloomOptions from Options.h, and
Engine.create() returns Engine?. The migration guide's rule of thumb covers anything it doesn't list:
look the class up in the C++ header. The Kotlin name is the C++ name.

5. Measure what's left (#178, #179)

A generator tells you what it bound. It doesn't tell you what it missed, or whether anyone wraps what it
bound. Two reports answer that:

• apiGaps checks from the other side. It lists Filament's public C++ methods from clang's AST
  (inline ones included), compiles our C objects at -O0, and compares symbols. It never parses names and
  doesn't trust the generator.
• apiCoverage writes the committed c/api-coverage.txt, one line per C function: wrapped (public
  Kotlin calls it), unwrapped (bound but no wrapper yet), todo (needs hand-written C) or skipped
  (on purpose, with the reason). After an upgrade, git diff c/api-coverage.txt shows what upstream added
  and how far each addition got.

#179 then closed the real gaps it found: unsigned MaterialInstance parameters, computeAABB,
FramePacer, FramePipelineEstimator, InstanceBuffer, Exposure, color spaces, and the async API
(runCommandAsync, setBufferAsync, setImageAsync, …). Today: 1,797 wrapped, 222 unwrapped (all
deliberate: values Kotlin holds itself, overloads another path covers, deprecated fields), 5 todo, 83
skipped.

By the numbers

	0.6.0	0.7.0
Platform-specific Kotlin (android + jvm + native + web + jni)	~22,500 lines	~2,300 lines
actual declarations	~4,900	132
@PlatformGap annotations	118	10, all single-threaded wasm or WebGL
Underlying bindings	upstream Java, hand-written C, upstream embind	one generated C API
C layer	~8,800 lines by hand	~14,000 generated + ~600 by hand

From the 0.6.0 tag to 0.7.0: 149 commits, 1,254 files, +47.7k / −48.7k lines.

Lessons for anyone wrapping a big C++ library in KMP

1. expect/actual is for the interop runtime, not the API. If every class has N actuals, you're
maintaining N libraries that happen to share an interface. Push the per-platform part down until it's only
"what is a pointer, how do bytes cross, how do callbacks come back." For us that's five declarations.

2. Pick one source of truth, and make it the real one. Another platform's binding (Android Java,
embind) is someone else's curated, lossy copy of the API. The headers are the API. Once everything was
generated from them, arguments about naming and shape mostly went away.

3. Design a C ABI that every Kotlin target can call as-is. With no per-platform glue, one Kotlin
signature has to match the C ABI everywhere. Each of these rules cost us a crash to learn:

• No size_t, long or ptrdiff_t: size_t is 64-bit on JVM, Android arm64 and iOS but 32-bit on
  wasm32. Use uint32_t for counts.
• No 8- or 16-bit integer parameters. Apple arm64 packs stack arguments by their natural size, so a
  Kotlin Int passed where C takes a uint8_t shifts every later stack argument. It only crashes on iOS,
  and only with more than 8 arguments.
• 64-bit results go through an out-pointer: a Kotlin/JS Long is an object, and a wasm i64 can't be
  turned back into one.
• No structs by value. Value structs are handles with accessors, which also removes per-ABI layout
  differences.
• On js, wasm bool results come back as 0/1 (and true == 1 is false in Kotlin/JS), and float
  results come back as doubles. A generated table tells the runtime which exports to wrap.

4. Generate, commit the output, review the diff. Committed generated code turns an upstream upgrade
into a regular code review, and a generator change into a visible diff.

5. Declare scope explicitly and make staleness fail. A skip list where each entry has a reason, and an
entry that matches nothing breaks the build, stays honest across upgrades. Inferring scope from symbol
visibility didn't.

6. Leave a hand-written escape hatch, and keep it small and visible. Some C++ will never map
mechanically (iterator ranges, std::variant, callbacks taking C++ types). Let the generator say exactly
where hand-written code stands in for it, and treat each one as debt.

7. Check coverage with a tool that doesn't trust the generator. apiGaps works from linker symbols,
not from the generator's model, so it catches what the generator silently drops.

8. Migrate incrementally. Web first, then Android, then one class body, then one record at a time,
with every target's tests green after each step. Five targets × four modules is too much surface to switch
in one jump.

Trade-offs we accepted

• The API broke. Following the headers meant renaming, reshaping and moving a lot of public API, with
  no compatibility shims. We think one big break toward upstream is better than many small ones.
• @SymbolName doesn't switch Kotlin/Native's thread state the way a cinterop call does, so a long C
  call (a blocking flushAndWait) holds up a stop-the-world GC on other threads until it returns. skiko
  makes the same trade-off.
• The web runtime ships as release assets (filament-kmp.js/.wasm), not inside the klibs, because
  webpack never sees klib resources. Web apps download them from the matching GitHub release.
• A few things are still unbound, mostly callbacks that take C++ types. They're tracked in
  c/api-coverage.txt.

What it means for you

• filament-compose only: follow the setup steps for your platforms. Raw-API code inside
  FilamentEffect { } needs the renames.
• Raw bindings: the compiler finds every rename. Start with the four project-wide replacements in
  section 2 of the migration guide.
• Web: replace filament.js/.wasm with filament-kmp.js/.wasm from the release.
• Desktop: JDK 17 is enough. New windows-arm64 runtime.
• Android: nothing to change in Gradle. Upstream's com.google.android.filament classes no longer
  interoperate: nativeObject is our C handle now.
• Filament is still 1.77.1, so your .filamat files keep working.

For contributors, The Generated C API
and Native Bindings cover
the whole pipeline. Adding API is now almost always a regenerate plus one Kotlin method.

What's next

• Shrink the hand-written remainder. Each case the generator learns is one fewer to maintain.
• Follow upstream's header annotations. Upstream is heading the same way for its own bindings:
  google/filament#10410 annotates the headers and
  #10426 generates the Android Java from them. We read
  the same headers, so where upstream's annotations say what is API, our skip list can follow them.
• Faster upgrades. A Filament bump should now be a regenerate, a reviewed diff and a coverage diff.
  1.77.2 will be the first real test.
• GPU-to-GPU frame sharing on Compose Desktop stays experimental while it depends on skiko internals.
  See the roadmap.

---

Questions, migration trouble, or your own KMP-wrapper war stories? Reply here. If you hit a rename the
migration guide misses, or an API that behaves differently on one platform, please open an issue.