filament-compose/io.github.erkko68.filament.compose/FilamentSceneScope

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

CameraNode

@Composable

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.

Cube

@Composable

fun FilamentSceneScope.Cube(material: MaterialInstance, position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), size: Float = 1.0f, onCreate: (Entity) -> 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.

Cylinder

@Composable

fun FilamentSceneScope.Cylinder(material: MaterialInstance, position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), radius: Float = 0.5f, height: Float = 1.0f, segments: Int = 32, onCreate: (Entity) -> 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.

FilamentEffect

@Composable

fun FilamentSceneScope.FilamentEffect(vararg keys: Any?, block: FilamentEffectScope.() -> Unit)

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.

GltfInstance

@Composable

fun FilamentSceneScope.GltfInstance(asset: GltfAsset?, position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), animationIndex: Int? = null, animationTime: Float = 0.0f, animationState: AnimationState? = null, morphWeights: FloatArray? = null, onCreate: GltfInstanceScope.() -> Unit = {}, onUpdate: GltfInstanceScope.() -> Unit = {})

Places one copy of a GltfAsset in the scene.

Group

@Composable

fun FilamentSceneScope.Group(position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), onCreate: (Entity) -> 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.

Light

@Composable

fun FilamentSceneScope.Light(type: LightManager.Type, color: Color = Color(1f, 1f, 1f), intensity: Float, intensityUnit: LightUnit = LightUnit.LUMINOUS_POWER, efficiency: Float = 1.0f, castShadows: Boolean = false, direction: Direction = Direction(0.3f, -1f, -0.5f), position: Position = Position(0f, 2f, 0f), falloff: Float = 10.0f, cone: SpotCone = SpotCone(), sun: SunParams = SunParams(), lightChannels: Set<Int> = setOf(0))

Adds a light to the scene. type is Filament's own LightManager.Type enum.

Mesh

@Composable

fun FilamentSceneScope.Mesh(material: MaterialInstance, positions: FloatArray, normals: FloatArray, uvs: FloatArray, indices: IntArray, position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), boundingBox: Box? = null, onCreate: (Entity) -> 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).

Plane

@Composable

fun FilamentSceneScope.Plane(material: MaterialInstance, position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), width: Float = 1.0f, depth: Float = 1.0f, doubleSided: Boolean = true, onCreate: (Entity) -> 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.

Sphere

@Composable

fun FilamentSceneScope.Sphere(material: MaterialInstance, position: Position = Position(0f), rotation: Quaternion = Quaternion(), scale: Scale = Scale(1f), pivot: Position = Position(0f), radius: Float = 0.5f, rings: Int = 16, segments: Int = 32, onCreate: (Entity) -> 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).