@amazon-devices/kepler-graphics

The Vega Graphics API provides functionality that allows apps to query the capabilities of the connected display. These capabilities include screen resolution, refresh rate, color depth and format, and HDR support. The API also considers the device’s support and returns the capabilities according to the device’s limitations.

Get started

Prerequisites

Vega apps can consume this package through the Vega SDK. For instructions on how to install the Vega SDK, see Vega SDK Setup.

Setup

The Vega Graphics Turbo Module is provided by the kepler-graphics npm package. Add the following library dependency to the dependencies section of your package.json file.

"@amazon-devices/kepler-graphics": "~2.4.0",

Permissions

The display API consists of both get methods and set methods. Apps that use the set methods via DisplayManager class require the security privilege com.amazon.graphics.privilege.display.manager it their app’s manifest.toml file under [needs] section as shown below.

[[needs.privilege]]
id = "com.amazon.graphics.privilege.display.manager"

The get methods do not require any privilege. Including com.amazon.graphics.privilege.display.manager allows the following set of operations:

Changing current screen resolution and refresh rate to one of the supported values.
Changing other display properties like color depth, color format, HDR mode, and ALLM.

Usage

The following is a list of supported use cases:

Listening to display hotplug events.
Querying supported screen resolutions (width x height) and refresh rates of the display.
Querying supported HDR types/Transfer Functions, maximum HDCP level, ccreen density (DPI) of the display.
Querying currently active screen resolution, refresh rate, color depth, color rormat, HDR mode, Low Latency Mode (ALLM) for the display.
Listening to change events for the display properties.

The following sections provide sample code for some of the use cases.

Import the required components

To use the Vega Graphics API, import the required components from @amazon-devices/kepler-graphics. Import the interfaces and types should the kepler-graphics package in a source code file as shown below:

import {
    Display,
    DisplayManager,
    DisplayController,
    ColorDepth,
    ColorSpace,
    HdcpLevel,
    HdrType,
    LlmState,
    HdrMode,
    IDisplayConfig,
    IDisplayListener,
    IDisplayControllerListener,
    ISubscription
} from '@amazon-devices/kepler-graphics';

The preceeding import shows all of the potential components. You need only import the components for the methods that your app consumes.

Check display status

To check if a display is connected to the device, use the following method.

const displayConnected = DisplayController.isPrimaryDisplayConnected();
if (displayConnected) {
    // Perform operations on the display.
} else {
    // Display is not connected, Do NOT use the `Display` and `DisplayManager` methods.
    // In this case, the hotplug event callbacks can be used to know
    // when a new display is connected.
}

Display hotplug events

Get callback events when display panels connect or disconnect. The IDisplayControllerListener.onAddDisplay() and IDisplayControllerListener.onRemoveDisplay() callback methods provide those events as shown below.

const displayControllerListener: IDisplayControllerListener = {

    onAddDisplay: (id: Int32) => {
      console.log("IDisplayControllerListener::onAddDisplay - ", id);
      // Any initialization when new display is connected.
    },
    onRemoveDisplay: (id: Int32) => {
      console.log("IDisplayControllerListener::onRemoveDisplay - ", id);
      // Any cleanup required.
      // Please note the `Display` and `DisplayManager` methods do not work
      // when the display is disconnected.
    },
  };

// Register the listener callback object to receive events.
const subscription: ISubscription = DisplayController.addListener(displayControllerListener);

Get the current screen resolution and refresh rate

The Display.getCurrentConfig() method returns the currently active configuration as an IDisplayConfig object. The members of the IDisplayConfig object provide the screen resolution (width x height), screen density, supported refresh rates, and more.

// Get currently active display config.
const displayConfig = Display.getCurrentConfig();
// Current width in pixels.
const width = displayConfig.widthInPixels;
// Current height in pixels.
const height = displayConfig.heightInPixels;
// Screen Density in DPI (dots-per-inch).
const dpi = displayConfig.screenDensityInDpi;

// Current refresh rate in milli hz (eg: 60000 = 60Hz).
const currentRefreshRate = Display.getCurrentRefreshRateInMillihertz();

Check HDR support

The following example code shows how to check whether the display and the device suport HDR.

// Checks if the display along with device supports any of the HDR formats.
const hdrSupport = Display.isHDRSupported();

// Get the current user selected HDR mode - possible values are in 'enum HdrMode'.
const hdrMode = Display.getHdrMode();

if (hdrSupport && (hdrMode !== HdrMode.DISABLED)) {
    // HDR is supported.
    // Now get the current configuration to check if required HDR format is supported.
    const displayConfig = Display.getCurrentConfig();
    for (const hdrType of displayConfig.supportedHdrType) {
        if (hdrType === HdrType.HDR10) {
            // HDR10 supported.
        } else if (hdrType === HdrType.HDR10_PLUS) {
            // HDR10+ supported.
        } else if (hdrType === HdrType.HLG) {
            // HLG supported.
        } else if (hdrType == HdrType.DOLBY_VISION) {
            // Dolby Vision supported.
        }
    }
} else {
    // HDR is not supported or disabled by user.
}

NOTE: The supported HDR types retrieved in the example code represent the current active display configuration (resolution) only. Other display configurations obtained through Display.getAllSupportedConfigs() might list other HDR types. You can only use those HDR types when the current active configuration changes to that particular display configuration through DisplayManager.requestConfigChange() method.

Query other display properties

// Query the display connector name.
const name = Display.getName();

// Get current HDCP level - possible values are in 'enum HdcpLevel'.
const hdcpLevel = Display.getCurrentHdcpLevel();

// Get current color depth - possible values are in 'enum ColorDepth'.
const colorDepth = Display.getColorDepth();

// Get current color space - possible values are in 'enum ColorSpace'.
const colorSpace = Display.getColorSpace();

// Check if low latency mode is supported in the device.
llmSupported = Display.isLowLatencyModeSupported();
if (llmSupported) {
    // Low Latency Mode is supported in the display.
}

Listen for change events

The following code example shows apps can use IDisplayListener callback interface to listen for changes to the following:

Display properties like screen resolution
Refresh rate, color depth/space
HDCP level
HDR mode
Low Latency Mode

const displayListener: IDisplayListener = {

    onConfigChange: (config: IDisplayConfig) => {
      console.log("IDisplayListener onConfigChange  ==  ", config);
    },
    onRefreshRateChange: (refreshRateInrMillihertz: Int32) => {
      console.log("IDisplayListener onRefreshRateChange  ==  ", refreshRateInrMillihertz);
    },
    onColorDepthChange: (colorDepth: ColorDepth) => {
      Alert.alert("IDisplayListener onConfigChange  == ");
      console.log("IDisplayListener onColorDepthChange  ==  ", colorDepth);
    },
    onColorSpaceChange: (colorSpace: ColorSpace) => {
      console.log("IDisplayListener onColorSpaceChange  ==  ", colorSpace);
    },
    onHdcpLevelChange: (level: HdcpLevel) => {
      console.log("IDisplayListener onHdcpLevelChange  ==  ", level);
    },
    onAutoConfigSwitchStateChange: (state: boolean) => {
      console.log("IDisplayListener onAutoConfigSwitchStateChange  ==  ", state);
    },
    onMultipleRefreshRateStateChange: (state: boolean) => {
      console.log("IDisplayListener onMultipleRefreshRateStateChange  ==  ", state);
    },
    onLowLatencyModeStateChange: (state: LlmState) => {
      console.log("IDisplayListener onLowLatencyModeStateChange  ==  ", state);
    },
    onHdrModeChange: (hdr_mode: HdrMode) => {
      console.log("IDisplayListener onHdrModeChange  ==  ", hdr_mode);
    },
    onSinkStateChange: (active: boolean) => {
      console.log("IDisplayListener onSinkStateChange  ==  ", active);
    }
};

// Register the listener object to receive the callbacks.
const subscription: ISubscription = Display.addDisplayListener(displayListener);

FAQs

Q1: Why is a display supported HDR type not listed in the `IDisplayConfig.supportedHdrType` array?

In addition to the display properties, the method implementation considers the device capabilities when reporting the supported types. If the device does not support certain HDR type, for example “Dolby Vision”, then the list reported by IDisplayConfig.supportedHdrType does not contain it.

Q2: How to unsubscribe for the listener callbacks?

The methods Display.addDisplayListener() and DisplayController.addListener() return a ISubscription object. You use the object to unsubscribe the listener by calling the unsubscribe() method. See the following code example.

  useEffect(() => {
    const subscription: ISubscription = DisplayController.addListener(displayControllerListener);
    return () => {
      subscription.unsubscribe();
    };
  }, []);

Q3: Why does `supportedHdrType` return multiple duplicated values like

  {
      "heightInPixels": 1080,
      "maxHdcpLevel": 7,
      "screenDensityInDpi": 81,
      "supportedHdrType": [
          1,
          1,
          1,
          1,
          1
      ],
      "supportedRefreshRatesInMillihertz": [
          60000,
          50000,
          30000,
          25000,
          24000
      ],
      "widthInPixels": 1920
  }

HDR types correlate with refresh rates. In this scenario, there are five different refresh rates, each with its corresponding HDR type support information. For instance, at a refresh rate of 60 millihertz (mHz), the HDR support type is 1, which corresponds to HdrType.NONE.

API Reference

Classes

Display — Class that retrieves properties of the primary display.
DisplayController — DisplayController specific operations are done through this
DisplayManager — DisplayManager provides APIs to change the display configuration/settings.

Interfaces

IDisplayConfig
IDisplayControllerListener — Listener interface for DisplayController events.
IDisplayListener — Listener interface for different display events
IDisplayManagerListener — Listener interface for DisplayManager events.
IOverscanBorder — Interface that handles the overscan border data.
ISubscription — Interface for unsubscribing listener.

Enumerations

AisrState — Defines values for AI Super Resolution state for display.
BufferPixelFormat — Buffer Pixel Format specifies the memory layout and bits used to store the
ColorDepth — Defines all possible color depths in a display.
ColorGamut — Defines list of Color gamut types.
ColorSpace — Defines Different color space types in a display.
HdcpLevel — Defines all possible HDCP levels that could be supported by a display.
HdrMode — Defines values for High dynamic range mode for display
HdrType — Defines list of supported underlying HDR technologies
LlmState — Defines all possible low latency mode (LLM) states that could be supported by a display.
TransferFunction — Defines list of display Transfer Functions

​Get started

​Prerequisites

​Setup

​Permissions

​Usage

​Import the required components

​Check display status

​Display hotplug events

​Get the current screen resolution and refresh rate

​Check HDR support

​Query other display properties

​Listen for change events

​FAQs

​Q1: Why is a display supported HDR type not listed in the IDisplayConfig.supportedHdrType array?

​Q2: How to unsubscribe for the listener callbacks?

​Q3: Why does supportedHdrType return multiple duplicated values like

​API Reference

​Classes

​Interfaces

​Enumerations