OpenXR-Erweiterung „XR_ANDROID_performance_metrics“

Namensstring

XR_ANDROID_performance_metrics

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

466

Datum der letzten Änderung

2024-09-06

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Mitwirkende

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Übersicht

Diese Erweiterung bietet APIs zum Auflisten und Abfragen verschiedener Leistungsmesswerte des aktuellen XR-Geräts, ‑Compositors und ‑Anwendungs. Entwickler können anhand der erfassten Leistungsmesswerte eine Leistungsanalyse durchführen und die XR-Anwendung gezielt optimieren. Das Verhalten der Anwendung darf nicht auf Grundlage der Zählerablesungen geändert werden.

Die Zähler für Leistungsmesswerte sind unter dem Stammpfad /perfmetrics_android in vordefinierte XrPath-Werte unterteilt. Eine Anwendung kann die verfügbaren Zähler über xrEnumeratePerformanceMetricsCounterPathsANDROID abfragen. Hier finden Sie eine Liste der Zählerpfade für Leistungsmesswerte, die möglicherweise auf Android-Geräten verfügbar sind:

  • /perfmetrics_android/app/cpu_frametime (Millisekunden, float): Die tatsächliche Zeit, die der Client für die Verarbeitung eines Frames benötigt hat.
  • /perfmetrics_android/app/gpu_frametime (Millisekunden, float): Die Zeit in Echtzeit, die der Client pro Frame auf die Fertigstellung der GPU-Arbeit gewartet hat. Hinweise:
    • Eine lange Wartezeit kann bedeuten, dass die GPU mit anderen Aufgaben beschäftigt war, nicht unbedingt, dass dieser Client zu viel GPU-Arbeit ausführt.
    • Die GPU-Wartezeit kann null sein, wenn das Rendering bereits abgeschlossen war, als es vom Compositor geprüft wurde.
  • /perfmetrics_android/app/cpu_utilization (Prozentsatz, Float): Die durchschnittliche CPU-Auslastung der App im Zeitverlauf.
    • Bei Mehrkernprozessoren kann der Wert über 100% liegen.
  • /perfmetrics_android/app/gpu_utilization (Prozentsatz): Die durchschnittliche GPU-Auslastung der App im Zeitverlauf.
  • /perfmetrics_android/app/motion_to_photon_latency (Millisekunden, float): Zeitspanne zwischen dem vom Nutzer initiierten Bewegungsereignis und der entsprechenden Aktualisierung des physischen Bildes auf dem Display.
  • /perfmetrics_android/compositor/cpu_frametime (Millisekunden, float): Die Zeit in Echtzeit, die der Compositor für die Verarbeitung eines Frames benötigt hat.
  • /perfmetrics_android/compositor/gpu_frametime (Millisekunden, float): Die Zeit in Echtzeit, die der Compositor pro Frame auf die Fertigstellung der GPU-Arbeit gewartet hat.
  • /perfmetrics_android/compositor/dropped_frame_count (ganzzahl): Gesamtzahl der verworfenen Frames aller Apps.
  • /perfmetrics_android/compositor/frames_per_second (float): Anzahl der Compositor-Frames, die pro Sekunde auf dem Gerät gerendert werden.
  • /perfmetrics_android/device/cpu_utilization_average (Prozentsatz, Float): Die CPU-Auslastung des Geräts wird über alle Kerne und im Zeitverlauf gemittelt.
  • /perfmetrics_android/device/cpu_utilization_worst (Prozentsatz, Float): Die CPU-Auslastung des Geräts des schlechtesten Kerns im Zeitverlauf.
  • /perfmetrics_android/device/cpu0_utilization bis /perfmetrics_android/device/cpuX_utilization (Prozentsatz, Float, X ist die Anzahl der CPU-Kerne minus eins): Die durchschnittliche CPU-Auslastung des Geräts pro CPU-Kern im Zeitverlauf.
  • /perfmetrics_android/device/cpu_frequency (MHz, float): Die CPU-Taktfrequenz des Geräts, durchschnittlich über alle Kerne und über einen bestimmten Zeitraum.
  • /perfmetrics_android/device/gpu_utilization (Prozentsatz, Float): Die GPU-Auslastung des Geräts im Zeitverlauf als Mittelwert.

Nachdem eine Sitzung erstellt wurde, kann eine Anwendung xrSetPerformanceMetricsStateANDROID verwenden, um das System für Leistungsmesswerte für diese Sitzung zu aktivieren. Eine Anwendung kann mit xrQueryPerformanceMetricsCounterANDROID einen Leistungsmesswertzähler für eine Sitzung abfragen, in der das System für Leistungsmesswerte aktiviert ist, oder mit xrGetPerformanceMetricsStateANDROID prüfen, ob das System für Leistungsmesswerte aktiviert ist.

Um die Funktionen dieser Erweiterung zu aktivieren, muss die Anwendung den Namen der Erweiterung mit dem Parameter XrInstanceCreateInfo::enabledExtensionNames an xrCreateInstance übergeben, wie im Abschnitt Erweiterungen beschrieben.

Neue Flaggentypen

typedef XrFlags64 XrPerformanceMetricsCounterFlagsANDROID;

// Flag bits for XrPerformanceMetricsCounterFlagsANDROID
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_ANY_VALUE_VALID_BIT_ANDROID = 0x00000001;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID = 0x00000002;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID = 0x00000004;

Neue Enum-Konstanten

Die Aufzählung XrStructureType wurde um folgende Elemente erweitert:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Neue Enums

typedef enum XrPerformanceMetricsCounterUnitANDROID {
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_GENERIC_ANDROID = 0,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_PERCENTAGE_ANDROID = 1,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_MILLISECONDS_ANDROID = 2,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_BYTES_ANDROID = 3,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_HERTZ_ANDROID = 4
} XrPerformanceMetricsCounterUnitANDROID;

Neue Gebäude

Die Struktur XrPerformanceMetricsStateANDROID ist so definiert: 

typedef struct XrPerformanceMetricsStateANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           enabled;
} XrPerformanceMetricsStateANDROID;

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • Wenn enabled auf XR_TRUE gesetzt ist, ist das System für Leistungsmesswerte aktiviert. Andernfalls ist es deaktiviert.XR_FALSE Legen Sie den Status auf XR_TRUE fest, um das System für Leistungsmesswerte zu aktivieren, und auf XR_FALSE, um es zu deaktivieren.

XrPerformanceMetricsStateANDROID wird als Eingabe beim Aufruf von xrSetPerformanceMetricsStateANDROID angegeben, um das System für Leistungsmesswerte zu aktivieren oder zu deaktivieren. XrPerformanceMetricsStateANDROID wird als Ausgabeparameter ausgefüllt, wenn xrGetPerformanceMetricsStateANDROID aufgerufen wird, um zu prüfen, ob das System für Leistungsmesswerte aktiviert ist.

Gültige Verwendung (implizit)

  • Die XR_ANDROID_performance_metrics-Erweiterung muss aktiviert sein, bevor XrPerformanceMetricsStateANDROID verwendet werden kann.
  • type muss XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID sein.
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein

Die Struktur XrPerformanceMetricsCounterANDROID ist so definiert: 

typedef struct XrPerformanceMetricsCounterANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrPerformanceMetricsCounterFlagsANDROID    counterFlags;
    XrPerformanceMetricsCounterUnitANDROID     counterUnit;
    uint32_t                                   uintValue;
    float                                      floatValue;
} XrPerformanceMetricsCounterANDROID;

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • counterFlags ist eine Bitmaske von XrPerformanceMetricsCounterFlagsANDROID, die die Gültigkeit von Wertelementen beschreibt.
  • counterUnit ist ein Enum von XrPerformanceMetricsCounterUnitANDROID, das die Maßeinheit beschreibt.
  • uintValue ist der Zählerwert im Format uint32_t. Sie ist gültig, wenn counterFlags XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID enthält.
  • floatValue ist der Zählerwert im Format float. Sie ist gültig, wenn counterFlags XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID enthält.

XrPerformanceMetricsCounterANDROID wird durch Aufrufen von xrQueryPerformanceMetricsCounterANDROID mit Informationen zu Echtzeit-Leistungsmesswertzählern ausgefüllt.

Gültige Verwendung (implizit)

Neue Funktionen

Die Funktion xrEnumeratePerformanceMetricsCounterPathsANDROID zählt alle Leistungsmesswert-Zählerpfade auf, die von der Laufzeit unterstützt werden. Sie ist so definiert: 

XrResult xrEnumeratePerformanceMetricsCounterPathsANDROID(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

Parameterbeschreibungen

  • instance ist ein XrInstance-Handle, der zuvor mit xrCreateInstance erstellt wurde.
  • counterPathCapacityInput ist die Kapazität des counterPaths-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
  • counterPathCountOutput wird von der Laufzeit mit der Anzahl der geschriebenen counterPaths oder der erforderlichen Kapazität ausgefüllt, falls counterPathCapacityInput nicht ausreicht.
  • counterPaths ist ein Array von XrPath, das von der Laufzeit ausgefüllt wird und alle verfügbaren Zähler für Leistungsmesswerte enthält. Es kann auch NULL sein, wenn counterPathCapacityInput = 0 ist.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen counterPaths-Größe findest du im Abschnitt Parameter für die Puffergröße.

Gültige Verwendung (implizit)

  • Die XR_ANDROID_performance_metrics-Erweiterung muss aktiviert sein, bevor xrEnumeratePerformanceMetricsCounterPathsANDROID aufgerufen wird.
  • instance muss ein gültiger XrInstance-Alias sein
  • counterPathCountOutput muss ein Verweis auf einen uint32_t-Wert sein
  • Wenn counterPathCapacityInput nicht 0 ist, muss counterPaths ein Verweis auf ein Array von counterPathCapacityInput XrPath-Werten sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT

Die Funktion xrSetPerformanceMetricsStateANDROID ist so definiert: 

XrResult xrSetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    const XrPerformanceMetricsStateANDROID*     state);

Parameterbeschreibungen

Mit der Funktion xrSetPerformanceMetricsStateANDROID wird das System für Leistungsmesswerte aktiviert oder deaktiviert.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

Die Funktion xrGetPerformanceMetricsStateANDROID ist so definiert: 

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Parameterbeschreibungen

Die Funktion xrGetPerformanceMetricsStateANDROID ruft den aktuellen Status des Systems für Leistungsmesswerte ab.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

Die Funktion xrQueryPerformanceMetricsCounterANDROID ist so definiert: 

XrResult xrQueryPerformanceMetricsCounterANDROID(
    XrSession                                   session,
    XrPath                                      counterPath,
    XrPerformanceMetricsCounterANDROID*         counter);

Parameterbeschreibungen

Mit der Funktion xrQueryPerformanceMetricsCounterANDROID wird ein Leistungsmesswert-Zähler abgefragt.

Die Anwendung sollte das System für Leistungsmesswerte aktivieren, indem xrSetPerformanceMetricsStateANDROID aufgerufen wird, bevor Messwerte mit xrQueryPerformanceMetricsCounterANDROID abgefragt werden.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_PATH_UNSUPPORTED
  • XR_ERROR_PATH_INVALID