rememberGltfAsset
Asynchronously loads a glTF/glb asset and keeps it alive as long as the calling composable is in the composition.
Returns null while the bytes load and on failure; the asset it returns then keeps uploading to the GPU until GltfAsset.isReady. It never throws inside composition, so a bad model can't crash the app. Pass onError to react to failures (show a placeholder, log, retry). Every failure mode is reported: the load lambda throwing (missing file, network error), the bytes failing to parse as glb/glTF, and a resource they reference being missing (only self-contained bytes load: a .glb, or a .gltf with embedded data).
Can be called either inside rememberFilamentScene { } (engine is picked up from LocalFilamentEngine) or outside it by hoisting the engine via rememberFilamentEngine:
// Inside rememberFilamentScene — engine implicit
GltfInstance(asset = rememberGltfAsset { Res.readBytes("Duck.glb") }, ...)
// Outside a scene — engine hoisted, asset can outlive any single scene
val engine = rememberFilamentEngine()
val duck = rememberGltfAsset(engine = engine) { Res.readBytes("Duck.glb") }
val scene = rememberFilamentScene(engine = engine) { GltfInstance(asset = duck, ...) }
// Telling loading from failure: a captured error, and isReady (the GPU upload runs after parsing)
var error by remember { mutableStateOf<Throwable?>(null) }
val model = rememberGltfAsset(engine = engine, onError = { error = it }) { loadFromNetwork() }
FilamentSceneView(engine = engine) { GltfInstance(asset = model) }
when {
error != null -> ErrorPlaceholder() // failed
model?.isReady != true -> LoadingIndicator(model?.progress) // reading, parsing or uploading
}Each GltfInstance created from the returned asset lives until the asset is destroyed (when this call leaves composition) — see GltfAsset.
Parameters
Reloads the asset when this value changes. Defaults to Unit for static assets.
Invoked once if load throws, the bytes don't parse, or their resources can't be loaded. The asset stays null.
The Filament engine that owns the asset's GPU resources. Defaults to the engine in the current composition scope.
Suspend function that produces the raw glb/glTF bytes.