FilamentSceneScope

Receiver for the content lambda of rememberFilamentScene. Scene-content composables (io.github.erkko68.filament.compose.scene.Light, GltfInstance, Group, primitives, FilamentEffect, …) are extensions on this scope, so they only compile inside a scene declaration.

Functions

Link copied to clipboard
fun FilamentSceneScope.CameraNode(cameraState: CameraState, eyeOffset: Position = Position(0f), targetOffset: Position = Position(0f, 0f, -1f), up: Direction = Direction(0f, 1f, 0f))

Attaches a CameraState to the surrounding Group so the camera follows that group's world transform every frame — a declarative chase / first-person / mounted camera.

Link copied to clipboard
fun FilamentSceneScope.Cube(material: MaterialInstance?, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), size: Float = 1.0f, visible: Boolean = true, castShadows: Boolean = true, receiveShadows: Boolean = true, onCreate: EntityScope.() -> Unit = {})

A unit cube centered on the origin (in mesh space). Six faces, 24 vertices (4 per face so normals and UVs are not shared across edges), 12 triangles.

Link copied to clipboard
fun FilamentSceneScope.Cylinder(material: MaterialInstance?, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), radius: Float = 0.5f, height: Float = 1.0f, segments: Int = 32, visible: Boolean = true, castShadows: Boolean = true, receiveShadows: Boolean = true, onCreate: EntityScope.() -> Unit = {})

A right circular cylinder aligned with the Y axis, centered on the origin (top at +height/2, bottom at -height/2). Side wall + two end caps. segments controls the radial subdivision.

Link copied to clipboard
fun FilamentSceneScope.DirectionalLight(direction: Direction = Direction(0.3f, -1f, -0.5f), color: LinearColor = LinearColor(1f, 1f, 1f), intensity: LightIntensity = LightIntensity.LuminousPower(100_000f), shadow: ShadowConfig? = null, castLight: Boolean = true, lightChannels: Set<Int> = setOf(0), followGroupRotation: Boolean = true)

A directional light — parallel rays from infinitely far (the classic "sun" for shading, without the visible disk; use SunLight for that). Only directional and spot lights can cast shadows.

Link copied to clipboard

Escape hatch for direct Filament API access inside rememberFilamentScene. Use it to add custom renderables to the scene or drive per-frame updates that the scene composables don't cover. For per-view, imperative access (picking, the raw View/Renderer), use FilamentViewState instead; for the camera, use io.github.erkko68.filament.compose.scene.CameraState.

Link copied to clipboard
fun FilamentSceneScope.FocusedSpotLight(position: Position = Position(0f, 2f, 0f), direction: Direction = Direction(0f, -1f, 0f), color: LinearColor = LinearColor(1f, 1f, 1f), intensity: LightIntensity = LightIntensity.LuminousPower(100_000f), falloff: Float = 10.0f, cone: SpotCone = SpotCone(), shadow: ShadowConfig? = null, castLight: Boolean = true, lightChannels: Set<Int> = setOf(0), followGroupRotation: Boolean = true)

A physically-correct spot light (LightManager.Type.FOCUSED_SPOT) — like SpotLight, but the outer cone angle affects total illumination (narrowing the cone concentrates the light). Can cast shadows. Parameters match SpotLight.

Link copied to clipboard
fun FilamentSceneScope.GltfInstance(asset: GltfAsset?, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), animationIndex: Int? = null, animationTime: Float = 0.0f, animationState: AnimationState? = null, morphWeights: FloatArray? = null, castShadows: Boolean? = null, receiveShadows: Boolean? = null, visible: Boolean = true, onCreate: GltfInstanceScope.() -> Unit = {}, onUpdate: GltfInstanceScope.() -> Unit = {})

Places one copy of a GltfAsset in the scene.

Link copied to clipboard
fun FilamentSceneScope.Group(position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), visible: Boolean = true, onCreate: EntityScope.() -> Unit = {}, content: @Composable FilamentSceneScope.() -> Unit)

Groups child scene composables under a single transform. Everything declared inside content is parented to a hidden transform entity, so moving/rotating/scaling the Group moves the whole assembly as a unit. Children's own position/rotation/scale become local to the group, and groups themselves nest cleanly inside other groups.

Link copied to clipboard

Low-level escape hatch: adds a light configured directly through the raw LightManager.Builder, for cases the typed composables (DirectionalLight, SpotLight, …) don't cover. You own the full builder; this composable only manages the entity, scene membership, and (when inside a Group) the transform so the light follows the group.

Link copied to clipboard
fun FilamentSceneScope.Mesh(material: MaterialInstance?, positions: FloatArray, normals: FloatArray, uvs: FloatArray, indices: IntArray, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), boundingBox: Box? = null, visible: Boolean = true, castShadows: Boolean = true, receiveShadows: Boolean = true, onCreate: EntityScope.() -> Unit = {})

Renders a custom triangle mesh from raw vertex data — the escape hatch for geometry the built-in primitives (Cube, Sphere, Plane, Cylinder) don't cover (procedural terrain, generated meshes, imported non-glTF geometry).

Link copied to clipboard
fun FilamentSceneScope.Plane(material: MaterialInstance?, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), width: Float = 1.0f, depth: Float = 1.0f, doubleSided: Boolean = true, visible: Boolean = true, castShadows: Boolean = true, receiveShadows: Boolean = true, onCreate: EntityScope.() -> Unit = {})

A flat quad lying in the XZ plane centered on the origin. The mesh is two-sided by default: we emit a full set of vertices/triangles for both the +Y face and the -Y face with correctly oriented normals, so lighting works from above and below without disabling face culling or requiring a doubleSided material.

Link copied to clipboard
fun FilamentSceneScope.PointLight(position: Position = Position(0f, 2f, 0f), color: LinearColor = LinearColor(1f, 1f, 1f), intensity: LightIntensity = LightIntensity.LuminousPower(100_000f), falloff: Float = 10.0f, castLight: Boolean = true, lightChannels: Set<Int> = setOf(0))

A point light — emits from position in all directions, intensity diminishing with the inverse square law out to falloff.

Link copied to clipboard
fun FilamentSceneScope.Sphere(material: MaterialInstance?, position: Position = Position(0f), rotation: Rotation = Rotation.Identity, scale: Scale = Scale(1f), pivot: Position = Position(0f), radius: Float = 0.5f, rings: Int = 16, segments: Int = 32, visible: Boolean = true, castShadows: Boolean = true, receiveShadows: Boolean = true, onCreate: EntityScope.() -> Unit = {})

A UV sphere centered on the origin. rings is the latitudinal count (from pole to pole), segments is the longitudinal count. Higher counts → smoother sphere, more triangles (rings * segments * 2 triangles total).

Link copied to clipboard
fun FilamentSceneScope.SpotLight(position: Position = Position(0f, 2f, 0f), direction: Direction = Direction(0f, -1f, 0f), color: LinearColor = LinearColor(1f, 1f, 1f), intensity: LightIntensity = LightIntensity.LuminousPower(100_000f), falloff: Float = 10.0f, cone: SpotCone = SpotCone(), shadow: ShadowConfig? = null, castLight: Boolean = true, lightChannels: Set<Int> = setOf(0), followGroupRotation: Boolean = true)

A spot light — emits from position along direction within a cone, decoupling the outer cone from total illumination (easier to tweak than FocusedSpotLight). Can cast shadows.

Link copied to clipboard
fun FilamentSceneScope.SunLight(direction: Direction = Direction(0.3f, -1f, -0.5f), color: LinearColor = LinearColor(1f, 1f, 1f), intensity: LightIntensity = LightIntensity.LuminousPower(100_000f), sun: SunParams = SunParams(), shadow: ShadowConfig? = null, castLight: Boolean = true, lightChannels: Set<Int> = setOf(0), followGroupRotation: Boolean = true)

A directional light that also draws a sun disk and halo in the sky (LightManager.Type.SUN). Same shading as DirectionalLight plus the visible disk configured by sun.