Controlling the Backlight

Toggle the backlight to switch between 4V and 2D

Leia Lightfield devices allow you to view content in 4V as well as regular 2D. You can instantaneously switch between the two modes. You might want to turn off the backlight on parts of your Android application where there is no media, to achieve full resolution.

The Leia Media SDK offers APIs to turn on and turn off the backlight instantaneously, by calling just one line of code. You can do so by using the Leia Display Manager.

Using Leia Display Manager

You can get an instance of the LeiaDisplayManager in your Android application using the following line of code

Kotlin

val displayManager = LeiaSDK.getDisplayManager(context)

Java

LeiaDisplayManager displayManager = LeiaSDK.getDisplayManager(context);

Toggling the Backlight

After you retrieve an instance of the LeiaDisplayManager, you can toggle the backlight by requesting the desired mode.

You can turn on the backlight using the requestBacklightMode() by passing in MODE_3D

Kotlin

val displayManager = LeiaSDK.getDisplayManager(applicationContext)
displayManager?.requestBacklightMode(LeiaDisplayManager.BacklightMode.MODE_3D)

Java

LeiaDisplayManager displayManager = LeiaSDK.getDisplayManager(context);
displayManager.requestBacklightMode(LeiaDisplayManager.BacklightMode.MODE_3D);

To turn off the backlight, you can request it using MODE_2D

Kotlin

displayManager?.requestBacklightMode(LeiaDisplayManager.BacklightMode.MODE_2D)

Java

displayManager.requestBacklightMode(LeiaDisplayManager.BacklightMode.MODE_2D);

Get Current Mode

You can check the currently active backlight mode in code by using getBacklightMode()

Kotlin

val currentBacklightMode = displayManager.getBacklightMode()

Java

LeiaDisplayManager.BacklightMode currentBacklightMode = displayManager.getBacklightMode();

UI Conveniences

The LeiaDisplayManager provides the ability to switch to 2D when UI elements that provide a poor 3D experience, such as the notification shade or keyboard, are shown. To take advantage of this behavior, your activities should forward the onWindowFocusChanged(boolean hasFocus) callback into the SDK.

Kotlin

override fun onWindowFocusChanged(hasFocus: Boolean) {
    super.onWindowFocusChanged(hasFocus)
    displayManager?.onWindowFocusedChanged(hasFocus)
}

Java

@Override
public void onWindowFocusChanged(boolean hasFocus) {
		super.onWindowFocusChanged(hasFocus);
		if (displayManager != null) {
				displayManager.onWindowFocusedChanged(hasFocus);
		}
}

Handling Backlight Mode Changes

You should not assume that the backlight will change modes immediately when you call requestBacklightMode(). You should also keep in mind that the backlight may change modes without you requesting it.

For example, if the device overheats, the backlight will automatically switch to 2D mode. Your application should respond to this event, and render content in 2D. In the event that 3D is disabled for a reason outside of your app's control, your app will be provided with the list of reasons why this happened.

Kotlin

displayManager.registerBacklightEventListener(object : BacklightEventListener {
    /**
     * This callback is invoked when the backlight mode changes, and your app is in the foreground.
     */
    override fun onBacklightModeChanged(backlightMode: LeiaDisplayManager.BacklightMode?) {
        // TODO: Change your application's rendering mode to 2D or 3D.
    }

    /**
     * This callback is called when the list of reasons why 3D may be disabled changes.
     */
    override fun onBacklightDisableReasonChanged(disableReasons: Set<BacklightDisableReason?>?) {
        // TODO: Optionally perform some reason-specific action.
    }
})

Java

mDisplayManager.registerBacklightEventListener(new BacklightEventListener() {

    /**
     * This callback is invoked when the backlight mode changes, and your app is in the foreground.
     */
    @Override
    public void onBacklightModeChanged(LeiaDisplayManager.BacklightMode backlightMode) {
        // TODO: Change your application's rendering mode to 2D or 3D.
    }

    /**
     * This callback is called when the list of reasons why 3D may be disabled changes.
     */
    @Override
    public void onBacklightDisableReasonChanged(Set<BacklightDisableReason> disableReasons) {
        // TODO: Optionally perform some reason-specific action.
    }
});

To test your application's responsiveness to these event changes, you may use the following ADB commands. Before sending any of them, run adb root to acquire the necessary permissions.

This command simulates an overheat condition: adb shell am broadcast -a com.leia.broadcast.3DMODE_DISABLED --esa "com.android.server.lights.DisableReasons" "OVERHEAT"

This command simulates returning to 3D because of normal temperature: adb shell am broadcast -a com.leia.broadcast.3DMODE_ENABLED

This command simulates switching to 2D because of bright sunlight: adb shell am broadcast -a com.leia.broadcast.3DMODE_DISABLED --esa "com.android.server.lights.DisableReasons" "OVERBRIGHT"

This command simulates returning to 3D because of returning to a darker environment: adb shell am broadcast -a com.leia.broadcast.3DMODE_ENABLED

Note that you must be running a recent version of firmware (>=V5 platform) for the thermal callback to work. (On earlier versions, you will still receive the callback when you request backlight changes, but the 3D backlight may not turn off due to overheat)

In order to avoid resource leaks and reduce memory pressure, your activities should deregister their event listeners in their onDestroy() methods.

Kotlin

override fun onDestroy() {
    super.onDestroy()
    displayManager?.deregisterBacklightEventListener(mBacklightEventListener)
}

Java

@Override
protected void onDestroy() {
    super.onDestroy();
    if (displayManager != null) {
        displayManager.deregisterBacklightEventListener(mBacklightEventListener);
    }
}