Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
AWS
ドキュメント
Support
Contact Us
My Cases

Console

as

開発
設計と開発
公開
リファレンス
サポート

@amazon-devices/kepler-graphics

@amazon-devices/kepler-graphics

KeplerグラフィックスAPIは、接続されたディスプレイの機能をアプリが照会できるようにする機能を提供します。照会できる機能は、画面解像度、リフレッシュレート、色深度、色形式、HDRサポートなどです。APIはデバイスによるサポートも考慮し、デバイスの制限に応じて機能を返します。

開始の手順

前提条件

Keplerアプリは、Kepler SDKを通じてこのパッケージを使用できます。

Kepler SDKのインストール方法については、Kepler SDKのセットアップを参照してください。

セットアップ

Keplerグラフィックスターボモジュールは、kepler-graphics npmパッケージによって提供されます。package.jsonファイルのdependenciesセクションに、以下のライブラリ依存関係を追加します。

クリップボードにコピーしました。

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

パーミッション

ディスプレイAPIは、get系メソッドとset系メソッドの両方で構成されています。DisplayManagerクラスを通じてset系メソッドを使用するアプリの場合、以下に示すように、アプリのmanifest.tomlファイルの [needs] セクションで、セキュリティ権限com.amazon.graphics.privilege.display.managerを指定する必要があります。

クリップボードにコピーしました。

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

get系メソッドには、権限は必要ありません。

使用方法

以下は、サポート対象のユースケースのリストです。

  • ディスプレイのホットプラグイベントをリッスンする。
  • ディスプレイのサポートされている画面解像度（幅×高さ）とリフレッシュレートを照会する。
  • ディスプレイのサポートされているHDRタイプ／伝達関数、最大HDCPレベル、画面密度（DPI）を照会する。
  • ディスプレイの現在アクティブな画面解像度、リフレッシュレート、色深度、色形式、HDRモード、低遅延モード（ALLM）を照会する。
  • 上記のディスプレイプロパティの変更イベントをリッスンする。

パーミッションセクションに記載されているシステム権限をアプリがリクエストして取得すると、以下の一連の操作ができるようになります。

  • 現在の画面解像度とリフレッシュレートを、サポートされているいずれかの値に変更する。
  • 色深度、色形式、HDRモード、ALLMなど、ほかのディスプレイプロパティを変更する。

以降のセクションでは、いくつかのユースケースのサンプルコードを示します。

必要なコンポーネントのインポート

KeplerグラフィックスAPIを使用するには、@amazon-devices/kepler-aps-clientから必要なコンポーネントをインポートします。

インターフェイスとタイプは、以下に示すように、ソースコードファイルで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オブジェクトのメンバーは、画面解像度（幅×高さ）、画面密度、サポートされるリフレッシュレートなどの情報を持ちます。

クリップボードにコピーしました。

// 現在アクティブなディスプレイ構成を取得します。
const displayConfig = Display.getCurrentConfig();
// 現在の幅（ピクセル単位）。
const width = displayConfig.widthInPixels;
// 現在の高さ（ピクセル単位）。
const height = displayConfig.heightInPixels;
// 画面密度（DPI（1インチあたりのドット数）単位）。
const dpi = displayConfig.screenDensityInDpi;

// 現在のリフレッシュレート（ミリHz単位。例： 60000 = 60Hz)。
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) {
            // ドルビービジョンがサポートされています。
        }
    }
} else {
    // HDRはサポートされていないか、ユーザーが無効にしています。
}

注： サンプルコードで取得した、サポートされているHDRタイプは、現在のアクティブなディスプレイ構成（解像度）のみを表しています。Display.getAllSupportedConfigs()を使用して取得されるほかのディスプレイ構成には、特定のHDRタイプがリストされている場合があります。それらのHDRタイプを使用できるのは、現在のアクティブな構成を特定のHDRタイプ用のディスプレイ構成に変更した場合のみです。変更にはDisplayManager.requestConfigChange()メソッドを使用します。

ほかのディスプレイプロパティの照会

クリップボードにコピーしました。

// ディスプレイコネクタ名を照会します。
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);

よくある質問（FAQ）

Q1： ディスプレイでサポートされているHDRタイプがIDisplayConfig.supportedHdrType配列に含まれていないのはなぜですか？

メソッドの実装では、サポートされているタイプを報告する際に、ディスプレイプロパティだけでなく、デバイスの機能も考慮されます。デバイスが「ドルビービジョン」などの特定のHDRタイプをサポートしていない場合、IDisplayConfig.supportedHdrTypeによって報告されるリストにはそのタイプが含まれません。

Q2： リスナーコールバックの登録を解除するにはどうすればよいですか？

Display.addDisplayListener()メソッドとDisplayController.addListener()メソッドは、ISubscriptionオブジェクトを返します。リスナーの登録を解除するには、unsubscribe()メソッドの呼び出しで、このオブジェクトを使用します。以下のコード例を参照してください。

クリップボードにコピーしました。

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

Q3： 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年10月2日

フォローする

サポート対象デバイス

amazon_developer_logo

© 2010-2025, Amazon.com, Inc. or its affiliates. All Rights Reserved. 無断複写·転載を禁じます。

利用規約

Amazon開発者ブログ

お問い合わせ