Skip to content

ArScreen

Overview

M2ArScreen is the recommended entry point for LOS-driven experiences. It extends M2FullScreen (which fills the full 640x400 display) and adds automatic inertial sensor subscription with a quaternion callback.

Inheritance

M2Screen (abstract - manages HUD + AR root trees)
 └── M2FullScreen (fills 640x400, zero offset)
      └── M2ArScreen (adds sensor subscription + onQuaternion callback)

Creating an AR Screen

class MyArScreen : M2ArScreen(SensorsRate.Fast) {

    private val infoPanel = M2ArPanel(east = 0f, north = 3f, up = 1f)
    private val label = M2Text()

    override fun onCreate() {
        // HUD content (fixed to display)
        val hudTitle = M2Text()
        hudTitle.setResource(M2FontResource.fontSmall)
            .setText("AR Mode Active")
            .setX(10f).setY(10f)
        add(hudTitle) // automatically goes to HUD root

        // AR content (anchored in world space)
        infoPanel.setWidthHeight(200f, 50f)
        label.setResource(M2FontResource.fontMedium)
            .setText("Look here!")
            .setTextAlign(Align.CenterHorizontal)
            .setX(100f).setY(25f)
        infoPanel.add(label)
        add(infoPanel) // automatically goes to AR root
    }

    override fun onQuaternion(
        timestampMs: Long,
        quaternion: M2Quaternion,
        calibrationState: M2ImuCalibrationState
    ) {
        // Called every sensor update with the user's head orientation
        // Use quaternion for eye-relative positioning
    }
}

Lifecycle

Method Behavior
Constructor Calls requireSensors(rate) to enable IMU at the specified SensorsRate
onCreate() Registers an IM2SensorsEvents listener on Evs.sensorsService
onQuaternion(...) Protected open callback - override to receive real-time orientation updates
onRelease() Unregisters the sensor listener

Sensor Rate

The sensor rate is set in the constructor and can be changed at runtime:

// Set initial rate in constructor
class MyArScreen : M2ArScreen(SensorsRate.VeryFast)

// Change rate at runtime
setSensorsRate(SensorsRate.Fast)
Rate Hz Use Case
SensorsRate.Slow 1 Low-power, infrequent updates
SensorsRate.Normal 2 Basic orientation tracking
SensorsRate.Medium 4 Moderate AR experiences
SensorsRate.Fast 33 Responsive AR content
SensorsRate.VeryFast 66 Full display-rate LOS tracking

Accessing the Last Quaternion

if (hasM2Quaternion) {
    val qtrn = lastM2Quaternion
    // use for positioning or calculations
}

Mixed HUD and AR Content

A single M2ArScreen can contain both HUD and AR elements. The SDK routes them automatically:

// HUD drawables → screen's HUD root tree
add(M2Text())        // isArDrawable() == false → HUD
add(M2RectFilled())  // HUD

// AR drawables → screen's AR root tree
add(M2ArPanel(...))  // isArDrawable() == true → AR
add(M2ArMesh(...))   // AR

Use getDrawables() to access HUD elements and getArDrawables() to access AR elements.

See Also