filament-utils/io.github.erkko68.filament.utils/Manipulator

Manipulator

class Manipulator(nativeHandle: NativePointer) : AutoCloseable

Helper that enables camera interaction similar to sketchfab or Google Maps.

Clients notify the manipulator of various mouse or touch events, then periodically call getLookAt so that they can adjust their camera. Three modes are supported: Mode.ORBIT, Mode.MAP, and Mode.FREE_FLIGHT. To construct a manipulator, use Builder and pass the desired mode to Builder.build.

Usage example:

val manip = Manipulator.Builder()
    .viewport(1024, 768)
    .build(Mode.ORBIT)

// In mouse-down handler:
manip.grabBegin(x, y, false)

// In mouse-move handler:
manip.grabUpdate(x, y)

// In mouse-up handler:
manip.grabEnd()

// Each frame:
val eye = FloatArray(3); val target = FloatArray(3); val up = FloatArray(3)
manip.getLookAt(eye, target, up)
camera.lookAt(eye[0], eye[1], eye[2], target[0], target[1], target[2], up[0], up[1], up[2])

See also

Constructors

constructor(nativeHandle: NativePointer)

Types

Builder for Manipulator instances.

enum Key : Enum<Manipulator.Key>

Keys used to translate the camera in Mode.FREE_FLIGHT mode.

Properties

currentBookmark

val currentBookmark: Bookmark

A new Bookmark of the current position, for jumpToBookmark.

val homeBookmark: Bookmark

A new Bookmark of the home position, for jumpToBookmark.

The immutable mode of the manipulator.

val nativeObject: NativePointer

The native object, for interop with code calling the Fila* C API directly. Read-only: this wrapper owns it.

Functions

open override fun close()

Same as destroy; lets this be used with use { } and try-with-resources.

Destroys the manipulator and releases all resources.

fun getLookAt(eyePosition: FloatArray, targetPosition: FloatArray, upward: FloatArray)

Gets the current orthonormal basis; this is usually called once per frame. Each array (size ≥ 3) receives a world-space position or direction.

fun getRay(x: Int, y: Int, origin: FloatArray, dir: FloatArray)

Given a viewport coordinate, computes a picking ray: its origin and direction dir (each size ≥ 3).

fun grabBegin(x: Int, y: Int, strafe: Boolean)

Starts a grabbing session (i.e. the user begins dragging in the viewport).

Ends a grabbing session.

fun grabUpdate(x: Int, y: Int)

Updates a grabbing session. Must be called at least once between grabBegin and grabEnd to dirty the camera.

fun jumpToBookmark(bookmark: Bookmark)

Sets the manipulator position and orientation back to a stashed state.

fun keyDown(key: Manipulator.Key)

Signals that a key is now in the down state.

fun keyUp(key: Manipulator.Key)

Signals that a key is now in the up state.

fun raycast(x: Int, y: Int, result: FloatArray): Boolean

Given a viewport coordinate, picks a point in the ground plane into result (size ≥ 3).

fun scroll(x: Int, y: Int, scrolldelta: Float)

In Mode.MAP and Mode.ORBIT modes, dollys the camera along the viewing direction. In Mode.FREE_FLIGHT mode, adjusts the move speed of the camera.

fun setViewport(width: Int, height: Int)

Sets the viewport dimensions. The manipulator uses this to process grab events and raycasts.

fun update(deltaTime: Float)

Processes input and updates internal state. Must be called once every frame before getLookAt is valid.