@amazon-devices/kepler-graphics 2.3.3

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Amazon.com, Inc. or its affiliates.  All rights reserved.
+
+These materials are licensed as "Program Materials" under the Program Materials License Agreement (the "Agreement").  The Agreement is available at https://developer.amazon.com/support/legal/pml.  See the Agreement for the specific terms and conditions of the Agreement.  Capitalized terms not defined in this file have the meanings given to them in the Agreement.  
+
+If you do not agree to the above terms and conditions, you may not use any file in this package. 
+
+YOUR USE OF THE PROGRAM MATERIALS IN OR ASSOCIATED WITH THIS PACKAGE IS AT YOUR SOLE RISK.  IN NO EVENT WILL AMAZON BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, CONSEQUENTIAL, SPECIAL, INCIDENTAL, OR PUNITIVE DAMAGES (INCLUDING FOR ANY LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, OR COMPUTER FAILURE OR MALFUNCTION) ARISING FROM OR RELATING TO SUCH PROGRAM MATERIALS, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, EVEN IF AMAZON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS AND DISCLAIMERS APPLY EXCEPT TO THE EXTENT PROHIBITED BY APPLICABLE LAW.

package/README.md

@@ -0,0 +1,272 @@
+
+# KeplerGraphics Display JS APIs
+
+## Overview
+
+The **Kepler Graphics Turbo Module** API provides functionality for applications to query the display capabilities such as screen resolution, refresh rate, color depth/format, and HDR support for the connected display from the platform. The API also considers the device's support and returns the capabilities according to the device's limitations. This Turbo Module internally uses the display APIs from the Kepler Graphics Interface (IDL interface). Most of the APIs are 1:1 mapped against the IDL interfaces.
+
+## Authentication
+
+The display APIs consists of both get methods and set methods. Applications that are using the set methods via `DisplayManager` class requires
+the security privilege **`com.amazon.graphics.privilege.display.manager`** in their Application's manifest.toml file under "[needs]" section as shown below.
+```
+[[needs.privilege]]
+id = "com.amazon.graphics.privilege.display.manager"
+```
+Please note the get methods do not require any privilege.
+
+## Getting Started
+
+### Prerequisites
+
+Kepler Applications can consume this package through the Kepler SDK.
+
+For instructions on how to install the Kepler SDK, see [Kepler SDK Setup](https://developer.amazon.com/docs/kepler/install-kepler-sdk.html).
+
+### Setup
+
+The Kepler Graphics Turbo Module is provided by the `kepler-graphics` npm package. This npm package must be added to the application's `package.json` as dependency.
+
+```
+"dependencies": {
+     ...
+     "@amazon-devices/kepler-graphics": "^2.3.0",
+}
+```
+
+### Import interfaces/types from the package
+
+The interfaces and types should be imported from 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';
+```
+Based on the consumed APIs, only the needed types in the above import listing can be retained.
+
+## Common Use Cases
+
+Use this package APIs to query the connected display properties and get hotplug events.
+The following is a list of supported use cases:
+
+1. Listening to display hotplug events.
+2. Querying supported *Screen Resolutions (width x heigh)* and *Refresh rates* of the display.
+3. Querying supported *HDR* types/*Transfer Functions*, maximum *HDCP level*, *Screen Density (DPI)* of the display.
+5. Querying currently active *Screen Resolution*, *Refresh Rate*, *Color Depth*, *Color Format*, *HDR Mode*, *Low Latency Mode (ALLM)* for the display.
+6. Listening to change events for the above mentioned display properties.
+
+If application gets the system privilege mentioned in the **Authentication** section above, then the following set of operations are allowed.
+
+7. Changing current *Screen Resolution* and *Refresh Rate* to one of the supported values.
+8. Changing other display properties like *Color Depth*, *Color Format*, *HDR Mode* and *ALLM*.
+
+
+The following sections provide sample code for some of the use cases.
+
+### 1. Check Display Status
+To check if a display is already connected or not 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.
+}
+```
+
+### 2. Display Hotplug Events
+Get callback events when display panels are connected or disconnected. 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);
+```
+
+### 3. Current Screen Resolution and Refresh Rate
+
+`Display.getCurrentConfig()` returns the currently active configuration as `IDisplayConfig` object. The members of the `IDisplayConfig` object provides the screen resolution (width x height), screen density, supported refresh rates, and more. Below is the sample code.
+
+```
+// 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();
+```
+
+### 4. Check HDR Support
+
+To check if HDR is supported by the display and also by the device, the following example code can be used.
+
+```
+// 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 shown above is from the current active display configuration (resolution) only. Other display configuration obtained through `Display.getAllSupportedConfigs()` might list certain HDR types. Those HDR types are usable only when the current active configuration is changed to that particular display configuration through `DisplayManager.requestConfigChange()` method.
+
+### 5. 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.
+}
+```
+
+### 6. Listen for Change Events
+
+Applications can listen for changes to the display properties like screen resolution, refresh rate, color depth/space, HDCP level, HDR mode, and Low Latency Mode through the `IDisplayListener` callback interface. See the following code example:
+
+```
+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 display supported HDR type is not listed in the `IDisplayConfig.supportedHdrType` array?
+In addition to the display properties, the method implementation considers the device capabilities too
+for 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()` returns a `ISubscription` object.
+This object is used 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 are correlated 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`.