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

Package-level declarations

Types

data class AmbientOcclusion(val radius: Float = 0.3f, val bias: Float = 0.01f, val intensity: Float = 1.0f, val quality: View.Quality = View.Quality.LOW)

Screen-space ambient occlusion (SSAO).

AnimationState

class AnimationState

Hoisted, observable playback state for a single glTF Animator, created with rememberAnimationState and passed to GltfInstance. It auto-advances on every frame and cross-fades smoothly whenever animationIndex changes, covering the common "play idle, blend into walk" case without dropping to the onUpdate escape hatch.

AntiAliasing

data class AntiAliasing(val msaaEnabled: Boolean = false, val msaaSampleCount: Int = 4, val fxaaEnabled: Boolean = true, val taaEnabled: Boolean = false)

Anti-aliasing: MSAA (hardware), FXAA (post-process), and TAA (temporal).

Bloom

data class Bloom(val strength: Float = 0.1f, val threshold: Boolean = true, val quality: View.Quality = View.Quality.LOW, val resolution: Int = 0, val levels: Int = 6)

Bloom — "glow" around bright areas.

CameraState

class CameraState

Hoisted, observable camera state. Create with rememberCameraState and pass to io.github.erkko68.filament.compose.FilamentView for full control over the camera.

Color

data class Color(val r: Float, val g: Float, val b: Float)

An RGB color (linear or sRGB depending on the consuming API). Distinct from the spatial vectors so a Color can't be passed as a Position. Components are r/g/b.

ColorGrade

data class ColorGrade(val exposure: Float = 0.0f, val contrast: Float = 1.0f, val vibrance: Float = 1.0f, val saturation: Float = 1.0f, val whiteBalanceTemperature: Float = 0.0f, val whiteBalanceTint: Float = 0.0f, val toneMapper: ToneMapper = ToneMapper.ACES())

Color grading — exposure, white balance, contrast, tone mapping, etc.

DepthOfField

data class DepthOfField(val cocScale: Float = 1.0f, val maxApertureDiameter: Float = 0.01f, val filter: View.DepthOfFieldOptions.Filter = View.DepthOfFieldOptions.Filter.MEDIAN, val nativeResolution: Boolean = false)

Depth-of-field (bokeh). The camera's focus distance and aperture control the focal plane.

Direction

data class Direction(val x: Float, val y: Float, val z: Float)

A direction / displacement vector in 3-D space. See Position for the rationale behind the distinct type and the Float3 interop story.

Dithering

data class Dithering(val mode: View.Dithering = View.Dithering.TEMPORAL)

Dithering applied at tonemap time. View.Dithering.TEMPORAL (Filament's native default) hides 8-bit banding in dark gradients and bloom halos.

DynamicResolution

data class DynamicResolution(val minScale: Float = 0.5f, val maxScale: Float = 1.0f, val sharpness: Float = 0.9f, val quality: View.Quality = View.Quality.LOW, val homogeneousScaling: Boolean = false)

Dynamic resolution scaling — lowers internal resolution under GPU load and upscales.

Environment

class Environment

A loaded image-based-lighting environment: the indirectLightState that lights the scene and an optional skyboxState background. Obtain via rememberKTXEnvironment (pre-baked KTX) or rememberHDREnvironment (raw .hdr) and feed the two states straight into io.github.erkko68.filament.compose.rememberFilamentScene:

Exposure

data class Exposure(val aperture: Float = 16.0f, val shutterSpeed: Float = 1f / 125f, val sensitivity: Float = 100.0f)

Photographic exposure (aperture / shutter-speed / ISO triangle).

Fog

data class Fog(val distance: Float = 0.0f, val density: Float = 0.1f, val height: Float = 0.0f, val heightFalloff: Float = 1.0f, val color: Color = Color(0f, 0f, 0f))

Height-based and volumetric fog.

GltfAsset

class GltfAsset

A loaded glTF asset whose GPU resources are ready. Obtain via rememberGltfAsset.

GltfInstanceScope

interface GltfInstanceScope

Scope for interacting with a specific glTF instance via low-level Filament APIs.

IndirectLightState

class IndirectLightState

Hoisted, observable Image-Based Lighting (IBL) state. Pass to io.github.erkko68.filament.compose.rememberFilamentScene via indirectLightState = ....

LightUnit

enum LightUnit : Enum<LightUnit>

How the Light's intensity value is interpreted, mirroring the three intensity setters on the core LightManager.Builder.

Position

data class Position(val x: Float, val y: Float, val z: Float)

A point in 3-D space.

PostProcessing

data class PostProcessing(val enabled: Boolean = true, val bloom: Bloom? = null, val vignette: Vignette? = null, val fog: Fog? = null, val ambientOcclusion: AmbientOcclusion? = null, val antiAliasing: AntiAliasing? = null, val screenSpaceReflections: ScreenSpaceReflections? = null, val colorGrade: ColorGrade? = null, val depthOfField: DepthOfField? = null, val shadows: Shadows? = null, val dynamicResolution: DynamicResolution? = null, val dithering: Dithering? = null, val renderQuality: RenderQuality? = null)

Per-view visual configuration: post-processing effects plus render-quality options. Pass to io.github.erkko68.filament.compose.FilamentView via postProcessing = ....

Projection

sealed class Projection

Camera projection. Pass an instance as the Camera.projection argument.

RenderQuality

data class RenderQuality(val hdrColorBuffer: View.Quality = View.Quality.HIGH)

Precision of the view's HDR color buffer. View.Quality.HIGH (the native default) is RGBA16F where supported — needed for emissive values above 1.0 to survive into bloom.

Scale

data class Scale(val x: Float, val y: Float, val z: Float)

A per-axis scale factor. See Position for the rationale behind the distinct type.

ScreenSpaceReflections

data class ScreenSpaceReflections(val thickness: Float = 0.1f, val bias: Float = 0.01f, val maxDistance: Float = 3.0f)

Screen-space reflections (SSR).

Shadows

data class Shadows(val type: View.ShadowType = View.ShadowType.PCF, val vsmAnisotropy: Int = 1, val vsmMipmapping: Boolean = false, val vsmMsaaSamples: Int = 1, val vsmHighPrecision: Boolean = false, val vsmLightBleedReduction: Float = 0.0f, val penumbraScale: Float = 1.0f, val penumbraRatioScale: Float = 1.0f)

Shadow rendering. type selects the algorithm; VSM/soft-shadow params apply only to their respective types (Filament ignores irrelevant options).

SkyboxSource

sealed class SkyboxSource

Source for a SkyboxState: either a solid color or a cubemap texture.

SkyboxState

class SkyboxState

Hoisted, observable skybox state. Pass to io.github.erkko68.filament.compose.rememberFilamentScene via skyboxState = .... A null source removes the skybox entirely.

SphericalHarmonics

data class SphericalHarmonics(val bands: Int, val coefficients: FloatArray)

Spherical harmonics coefficients for diffuse irradiance.

SpotCone

data class SpotCone(val innerAngle: Float = 0.5f, val outerAngle: Float = 0.6f)

Spot / focused-spot cone angles (half-angles in radians). innerAngle must be ≤ outerAngle.

SunParams

data class SunParams(val angularRadius: Float = 1.9f, val haloSize: Float = 10.0f, val haloFalloff: Float = 80.0f)

Sun-disk appearance parameters for LightManager.Type.SUN lights.

Vignette

data class Vignette(val midPoint: Float = 0.5f, val roundness: Float = 0.5f, val feather: Float = 0.5f, val color: Color = Color(0f, 0f, 0f))

Vignette — darkens the corners of the viewport.

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.

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.

rememberAnimationState

@Composable

fun rememberAnimationState(animationIndex: Int? = 0, speed: Float = 1.0f, crossFadeDuration: Float = 0.3f, loop: Boolean = true): AnimationState

Creates and remembers an AnimationState. Initial values seed the state on first composition; afterwards mutate the returned object's fields to drive playback.

rememberCameraState

@Composable

fun rememberCameraState(eye: Position = Position(0f, 1f, 10f), target: Position = Position(0f, 0f, 0f), up: Direction = Direction(0f, 1f, 0f), projection: Projection = Projection.Perspective(), exposure: Exposure = Exposure(), shift: Float2 = Float2(0f, 0f), scaling: Float2 = Float2(1f, 1f)): CameraState

Creates and remembers a CameraState.

rememberGltfAsset

@Composable

fun rememberGltfAsset(engine: Engine = LocalFilamentEngine.current, key: Any = Unit, onError: (Throwable) -> Unit? = null, load: suspend () -> ByteArray): GltfAsset?

Asynchronously loads a glTF/glb asset and keeps it alive as long as the calling composable is in the composition.

rememberHDREnvironment

@Composable

fun rememberHDREnvironment(engine: Engine, intensity: Float, showSkybox: Boolean = true, format: Texture.InternalFormat = Texture.InternalFormat.R11F_G11F_B10F, key: Any = Unit, onError: (Throwable) -> Unit? = null, hdr: suspend () -> ByteArray): Environment

Builds an Environment from an equirectangular HDR image instead of pre-baked KTX — no cmgen step, just ship the .hdr. The reflection cubemap and skybox are prefiltered on the GPU at load via IBLPrefilterContext/EquirectangularToCubemap/SpecularFilter.

rememberIndirectLightState

@Composable

fun rememberIndirectLightState(reflections: Texture? = null, irradianceCubemap: Texture? = null, irradianceSh: SphericalHarmonics? = null, intensity: Float, rotation: FloatArray? = null): IndirectLightState

Creates and remembers an IndirectLightState.

rememberKTXEnvironment

@Composable

fun rememberKTXEnvironment(engine: Engine, intensity: Float, key: Any = Unit, onError: (Throwable) -> Unit? = null, skybox: suspend () -> ByteArray? = null, ibl: suspend () -> ByteArray): Environment

Loads an IBL environment (and optional skybox) from KTX1 data and wires it into the scene's indirect-light/skybox state. This is the convenience path over hand-wiring KTX1Loader, texture lifetimes, and IndirectLightState/SkyboxState.

rememberMaterial

@Composable

fun rememberMaterial(engine: Engine = LocalFilamentEngine.current, key: Any = Unit, onError: (Throwable) -> Unit? = null, load: suspend () -> ByteArray): Material?

Asynchronously loads a Filament Material and keeps it alive as long as the calling composable is in the composition. Returns null while loading and on failure — it never throws inside composition. Pass onError to react when load throws (missing file, network error).

rememberMaterialInstance

@Composable

fun rememberMaterialInstance(material: Material, engine: Engine = LocalFilamentEngine.current): MaterialInstance

Creates and manages a MaterialInstance from a Material. The instance is destroyed when this leaves the composition.

rememberSkyboxState

@Composable

fun rememberSkyboxState(source: SkyboxSource? = null, showSun: Boolean = false, intensity: Float = 1.0f, priority: Int = 0): SkyboxState

Creates and remembers a SkyboxState.

rememberTexture

@Composable

fun rememberTexture(engine: Engine = LocalFilamentEngine.current, type: TextureLoader.TextureType = TextureLoader.TextureType.COLOR, key: Any = Unit, onError: (Throwable) -> Unit? = null, load: suspend () -> ByteArray): Texture?

Asynchronously loads and manages a Filament Texture. Returns null while loading and on failure — it never throws inside composition. Pass onError to react when load throws (missing file, network error) or the bytes can't be decoded on this platform. See rememberMaterial for the engine-hoisting pattern when calling outside rememberFilamentScene { }.

toColor

fun Float3.toColor(): Color

Reinterpret a Float3 as a Color (x→r, y→g, z→b).

toDirection

fun Float3.toDirection(): Direction

Reinterpret a Float3 as a Direction.

toPosition

fun Float3.toPosition(): Position

Reinterpret a Float3 as a Position.

toScale

fun Float3.toScale(): Scale

Reinterpret a Float3 as a Scale.