CameraState

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

All fields are observable androidx.compose.runtime.MutableState — read them inside a composable to subscribe to changes, or write them from anywhere on the main thread to drive the camera imperatively.

Read-only matrices (viewMatrix, projectionMatrix) reflect the underlying Filament camera and are valid only while the state is attached to a FilamentView.

val cameraState = rememberCameraState(initialEye = Position(0f, 2f, 5f))
FilamentView(scene = scene, cameraState = cameraState)

// Read the view matrix from anywhere
LaunchedEffect(cameraState.eye) {
val v = cameraState.viewMatrix // may be null until attached
}

Properties

Link copied to clipboard
Link copied to clipboard

Where the camera is. Setting it stops a running animateTo.

Link copied to clipboard

Distance from the camera to the plane of focus in world units, used by PostProcessing(depthOfField = …) to place the focal plane. Ignored without DoF.

Link copied to clipboard
Link copied to clipboard

Projection matrix (view→clip) computed by Filament. Null until this state is attached to a io.github.erkko68.filament.compose.FilamentView.

Link copied to clipboard

Per-axis projection scaling; LensScaling.Identity leaves the frustum as computed.

Link copied to clipboard

Off-axis lens shift; LensShift.None leaves the projection centred.

Link copied to clipboard

The point the camera looks at. Setting it stops a running animateTo.

Link copied to clipboard

The camera's up direction. Setting it stops a running animateTo.

Link copied to clipboard

View matrix (world→view) computed by Filament. Null until this state is attached to a io.github.erkko68.filament.compose.FilamentView.

Link copied to clipboard

eye, target and up together. Setting it puts the camera there at once and stops a running animateTo.

Functions

Link copied to clipboard
suspend fun animateTo(viewpoint: Viewpoint, animationSpec: AnimationSpec<Float> = CameraTransitions.Smooth, path: CameraPath = CameraPath.Orbit)

Moves the camera to viewpoint over animationSpec (see CameraTransitions), along path. A gesture on the view, another animateTo or setting viewpoint, eye, target or up stops it where it is, and it then throws a CancellationException, as cancelling the calling coroutine does.

Link copied to clipboard
fun fitting(center: Position, radius: Float, from: Direction? = null): Viewpoint

The viewpoint that frames a sphere of radius around center, seen from that direction (from center towards the eye; the camera's current one when null), just far enough to fit the view's current shape. An orthographic projection keeps its extents, so the eye sits at twice the radius. Before the view first lays out, the shape is taken as square.

Link copied to clipboard
fun worldToScreen(position: Position): Offset?

Where position (world space) appears in the attached view, in pixels from its top-left corner, or null when it is behind the camera or this state isn't attached to a view yet. Reads the camera's state, so a caller in composition, layout or drawing re-runs when the camera moves or the view resizes. To pin an element there, use anchorTo.