Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

@amazon-devices/kepler-graphics

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

Kepler图形API提供允许应用查询已连接显示器功能的功能。这些功能包括屏幕分辨率、刷新率、色深和格式，以及HDR支持。API还会考虑设备支持，并根据设备限制返回功能信息。

开始使用

先决条件

Kepler应用可以通过Kepler SDK使用此程序包。

有关如何安装Kepler SDK的说明，请参阅Kepler SDK设置。

设置

Kepler图形Turbo模块由kepler-graphics npm程序包提供。将以下库依赖项添加到package.json文件的dependencies部分。

已复制到剪贴板。

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

权限

显示API由get方法和set方法组成。通过DisplayManager类使用set方法的应用需要安全权限com.amazon.graphics.privilege.display.manager，该权限位于其manifest.toml文件的 [needs] 部分下，如下所示。

已复制到剪贴板。

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

get方法不需要任何权限。

通过纳入com.amazon.graphics.privilege.display.manager可进行以下一系列操作：

将当前屏幕分辨率和刷新率更改为支持的值之一。
更改其他显示器属性，如色深、颜色格式、HDR模式和ALLM。

用法

以下是支持的用例列表：

侦听显示器热插拔事件。
查询支持的屏幕分辨率（宽x高）和显示器的刷新率。
查询支持的HDR类型/传输函数、最高HDCP级别、显示器的屏幕像素密度 (DPI)。
查询显示器的当前有效屏幕分辨率、刷新率、色深、颜色格式、HDR模式、低延迟模式 (ALLM)。
侦听显示器属性的更改事件。

以下部分提供了一些用例的示例代码。

导入所需的组件

要使用Kepler图形API，请从@amazon-devices/kepler-graphics导入所需的组件。

在源代码文件中，应从kepler-graphics程序包导入接口和类型，如下所示：

已复制到剪贴板。

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

前面的导入显示了所有潜在可用的组件。您只需为应用使用的方法导入相应的组件。

检查显示器状态

要检查显示器是否已连接到设备，请使用以下方法。

已复制到剪贴板。

const displayConnected = DisplayController.isPrimaryDisplayConnected();
if (displayConnected) {
    // 在显示器上执行操作。
} else {
    // 显示器未连接，请勿使用“Display”和“DisplayManager”方法。
    // 此时，可以通过使用热插拔事件的回调函数来知道
    // 何时连接了新显示器。
}

显示热插拔事件

在显示面板连接或断开连接时获取回调事件。IDisplayControllerListener.onAddDisplay() 和IDisplayControllerListener.onRemoveDisplay() 回调方法提供这些事件，如下所示。

已复制到剪贴板。

const displayControllerListener: IDisplayControllerListener = {

    onAddDisplay: (id: Int32) => {
      console.log("IDisplayControllerListener::onAddDisplay - ", id);
      // 连接新显示器时的任何初始化。
    },
    onRemoveDisplay: (id: Int32) => {
      console.log("IDisplayControllerListener::onRemoveDisplay - ", id);
      // 所需的任何清理。
      // 请注意当显示器断开连接时，“Display”和“DisplayManager”
      // 方法不起作用。
    },
  };

// 注册侦听器回调对象以接收事件。
const subscription: ISubscription = DisplayController.addListener(displayControllerListener);

获取当前屏幕分辨率和刷新率

Display.getCurrentConfig() 方法将当前有效的配置作为IDisplayConfig对象返回。IDisplayConfig对象的成员提供屏幕分辨率（宽x高）、屏幕像素密度、支持的刷新率等。

已复制到剪贴板。

// 获取当前有效的显示器配置。
const displayConfig = Display.getCurrentConfig();
// 以像素为单位的当前宽度。
const width = displayConfig.widthInPixels;
// 以像素为单位的当前高度。
const height = displayConfig.heightInPixels;
// 以DPI（每英寸点数）为单位的屏幕像素密度。
const dpi = displayConfig.screenDensityInDpi;

// 以毫赫兹为单位的当前刷新率（例如： 60000 = 60赫兹）。
const currentRefreshRate = Display.getCurrentRefreshRateInMillihertz();

检查HDR支持

以下示例代码显示如何检查显示器和设备是否支持HDR。

已复制到剪贴板。

// 检查显示器和设备是否支持任何HDR格式。
const hdrSupport = Display.isHDRSupported();

// 获取当前用户选择的HDR模式 - 可能的值位于“enum HdrMode”中。
const hdrMode = Display.getHdrMode();

if (hdrSupport && (hdrMode !== HdrMode.DISABLED)) {
    // 支持HDR。
    // 现在获取当前配置以检查是否支持所需的HDR格式。
    const displayConfig = Display.getCurrentConfig();
    for (const hdrType of displayConfig.supportedHdrType) {
        if (hdrType === HdrType.HDR10) {
            // 支持HDR10。
        } else if (hdrType === HdrType.HDR10_PLUS) {
            // 支持HDR10+。
        } else if (hdrType === HdrType.HLG) {
            // 支持HLG。
        } else if (hdrType == HdrType.DOLBY_VISION) {
            // 支持Dolby Vision。
        }
    }
} else {
    // HDR不受支持或已由用户禁用。
}

注意： 示例代码中检索到的受支持HDR类型仅针对当前使用的显示器配置（分辨率）有效。通过Display.getAllSupportedConfigs() 获得的其他显示器配置可能会列出其他HDR类型。只有当通过DisplayManager.requestConfigChange() 方法将当前有效的配置更改为该特定的显示配置时，您才能使用这些HDR类型。

查询其他显示器属性

已复制到剪贴板。

// 查询显示器连接器的名称。
const name = Display.getName();

// 获取当前HDCP级别 - 可能的值在“enum HdcpLevel”中。
const hdcpLevel = Display.getCurrentHdcpLevel();

// 获取当前色深 - 可能的值在“enum ColorDepth”中。
const colorDepth = Display.getColorDepth();

// 获取当前颜色空间 - 可能的值在“enum ColorSpace”中。
const colorSpace = Display.getColorSpace();

// 检查设备是否支持低延迟模式。
llmSupported = Display.isLowLatencyModeSupported();
if (llmSupported) {
    // 显示器支持低延迟模式。
}

侦听更改事件

以下代码示例显示应用可以使用IDisplayListener回调接口来侦听对以下项的更改：

显示屏属性（例如屏幕分辨率）
刷新率、色深/色彩空间
HDCP级别
HDR模式
低延迟模式

已复制到剪贴板。

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);
    }
};

// 注册侦听器对象以接收回调。
const subscription: ISubscription = Display.addDisplayListener(displayListener);

常见问题解答

问1：为什么`IDisplayConfig.supportedHdrType`数组中没有列出显示器支持的HDR类型？

在报告支持的类型时，该方法实现除了考虑显示器属性外，还会考虑设备功能。如果设备不支持特定HDR类型，例如“Dolby Vision”，则IDisplayConfig.supportedHdrType报告的列表不会包含该类型。

问2：如何取消订阅侦听器回调？

Display.addDisplayListener() 和DisplayController.addListener() 方法返回ISubscription对象。您可使用此对象来取消订阅侦听器，方法是调用unsubscribe() 方法。查看以下代码示例。

已复制到剪贴板。

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

问3：为什么`supportedHdrType`会返回多个重复的值，比如

已复制到剪贴板。

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

HDR类型与刷新率相关。在这种情况下，有5种不同的刷新率，每种刷新率都有相应HDR类型支持信息。例如，在60毫赫兹 (MHz) 的刷新率下，HDR支持类型为1，对应于HdrType.NONE。

模块

Last updated: 2025年11月11日

@amazon-devices/kepler-graphics

开始使用

先决条件

设置

权限

用法

导入所需的组件

检查显示器状态

显示热插拔事件

获取当前屏幕分辨率和刷新率

检查HDR支持

查询其他显示器属性

侦听更改事件

常见问题解答

问1： 为什么IDisplayConfig.supportedHdrType数组中没有列出显示器支持的HDR类型？

问2： 如何取消订阅侦听器回调？

问3： 为什么supportedHdrType会返回多个重复的值，比如

模块

问1：为什么`IDisplayConfig.supportedHdrType`数组中没有列出显示器支持的HDR类型？

问2：如何取消订阅侦听器回调？

问3：为什么`supportedHdrType`会返回多个重复的值，比如