Rozszerzenie OpenXR XR_ANDROID_performance_metrics

Nazwa ciągu znaków

XR_ANDROID_performance_metrics

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

466

Data ostatniej modyfikacji

2024-09-06

Stan adresu IP

Brak znanych roszczeń dotyczących adresu IP.

Zależności rozszerzenia i wersji

OpenXR 1.0

Twórcy

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Omówienie

To rozszerzenie udostępnia interfejsy API do wyliczania i wyszukiwania różnych liczników danych o wydajności urządzenia XR, kompozytora i aplikacji XR. Deweloperzy mogą przeprowadzić analizę skuteczności i wykonać ukierunkowaną optymalizację aplikacji XR, korzystając z zbieranych liczników danych o skuteczności. Aplikacja nie powinna zmieniać swojego działania na podstawie odczytów licznika.

Liczniki danych o skuteczności są uporządkowane według zdefiniowanych wstępnie wartości XrPath w ścieżce głównej /perfmetrics_android. Aplikacja może wysyłać zapytania do dostępnych liczników za pomocą funkcji xrEnumeratePerformanceMetricsCounterPathsANDROID. Oto lista ścieżek liczników danych o wydajności, które mogą być dostępne na urządzeniach z Androidem:

  • /perfmetrics_android/app/cpu_frametime(milisekundy, liczba zmiennoprzecinkowa) – czas, jaki klient poświęcił na przetworzenie ramki.
  • /perfmetrics_android/app/gpu_frametime (ms, liczba zmiennoprzecinkowa) – czas, jaki klient spędził na oczekiwaniu na zakończenie pracy GPU na każdą klatkę. Uwagi:
    • Długi czas oczekiwania może oznaczać, że GPU był zajęty innymi zadaniami, a niekoniecznie, że ten klient wykonywał zbyt dużo operacji na GPU.
    • Czas oczekiwania na GPU może wynosić 0, jeśli renderowanie zostało już ukończone, gdy kompozytor je sprawdzał.
  • /perfmetrics_android/app/cpu_utilization(wartość procentowa, liczba zmiennoprzecinkowa) – łączne wykorzystanie procesora przez aplikację w średniej na przestrzeni czasu.
    • W przypadku procesorów wielordzeniowych może ona przekraczać 100%.
  • /perfmetrics_android/app/gpu_utilization(procent) – średnia w czasie łączna wartość wykorzystania GPU przez aplikację.
  • /perfmetrics_android/app/motion_to_photon_latency (ms, liczba zmiennoprzecinkowa) – czas od zainicjowania przez użytkownika zdarzenia związanego z ruchu do odpowiedniej aktualizacji obrazu fizycznego na wyświetlaczu.
  • /perfmetrics_android/compositor/cpu_frametime(milisekundy, liczba zmiennoprzecinkowa) – czas, jaki zajęło procesorowi kompozytorskiemu przetworzenie klatki.
  • /perfmetrics_android/compositor/gpu_frametime (ms, liczba zmiennoprzecinkowa) – czas oczekiwania na zakończenie pracy przez procesor graficzny na każdą klatkę.
  • /perfmetrics_android/compositor/dropped_frame_count(liczba całkowita) – łączna liczba pominiętych klatek ze wszystkich aplikacji.
  • /perfmetrics_android/compositor/frames_per_second (float) – liczba klatek złożonego obrazu wyświetlanych na urządzeniu w ciągu sekundy.
  • /perfmetrics_android/device/cpu_utilization_average (wartość procentowa, typ float) – średnie wykorzystanie procesora urządzenia na wszystkich rdzeniach uśrednione w czasie.
  • /perfmetrics_android/device/cpu_utilization_worst (wartość procentowa, liczba zmiennoprzecinkowa) – średnie wykorzystanie procesora na urządzeniu w najsłabszym rdzeniu w ciągu czasu.
  • /perfmetrics_android/device/cpu0_utilization do /perfmetrics_android/device/cpuX_utilization (procent, liczba zmiennoprzecinkowa, X to liczba rdzeni procesora pomniejszona o 1) – średnie wykorzystanie procesora urządzenia na rdzeń procesora na przestrzeni czasu.
  • /perfmetrics_android/device/cpu_frequency (MHz, float) – średnia częstotliwość procesora urządzenia na wszystkich rdzeniach i średnia w czasie.
  • /perfmetrics_android/device/gpu_utilization (procent, liczba zmiennoprzecinkowa) – średnie wykorzystanie GPU urządzenia na przestrzeni czasu.

Po utworzeniu sesji aplikacja może użyć metody xrSetPerformanceMetricsStateANDROID, aby włączyć system danych o skuteczności na potrzeby tej sesji. Aplikacja może użyć metody xrQueryPerformanceMetricsCounterANDROID, aby zapytać licznik danych o skuteczności w sesji, w której włączono system danych o skuteczności, lub użyć metody xrGetPerformanceMetricsStateANDROID, aby sprawdzić, czy system danych o skuteczności jest włączony.

Aby włączyć funkcję tego rozszerzenia, aplikacja powinna przekazać nazwę rozszerzenia do funkcji xrCreateInstance, używając parametru XrInstanceCreateInfo::enabledExtensionNames zgodnie z informacjami podanymi w sekcji Rozszerzenia.

Nowe typy flag

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;

Nowe stałe typu wyliczeniowego

Wyliczenie XrStructureType zostało rozszerzone o:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Nowe wartości w polu enum

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;

Nowe struktury

Struktura XrPerformanceMetricsStateANDROID jest zdefiniowana jako: 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • Wartość enabled jest ustawiona na XR_TRUE, aby wskazać, że system danych o wydajności jest włączony, a w przeciwnym razie – na XR_FALSE. Podczas ustawiania stanu wybierz XR_TRUE, aby włączyć system danych o skuteczności, lub XR_FALSE, aby go wyłączyć.

XrPerformanceMetricsStateANDROID jest przekazywany jako dane wejściowe podczas wywoływania funkcji xrSetPerformanceMetricsStateANDROID w celu włączenia lub wyłączenia systemu pomiarów wydajności. Parametr XrPerformanceMetricsStateANDROID jest wypełniany jako parametr wyjściowy podczas wywoływania funkcji xrGetPerformanceMetricsStateANDROID, aby sprawdzić, czy system danych o wydajności jest włączony.

Prawidłowe użycie (domyślne)

  • Przed użyciem XrPerformanceMetricsStateANDROID należy włączyć rozszerzenie XR_ANDROID_performance_metrics.
  • type musi być XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.

Struktura XrPerformanceMetricsCounterANDROID jest zdefiniowana w ten sposób: 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • counterFlags to maska bitowa XrPerformanceMetricsCounterFlagsANDROID, która opisuje poprawność wartości elementów.
  • counterUnit to enumeracja XrPerformanceMetricsCounterUnitANDROID, która opisuje jednostkę miary.
  • uintValue to wartość licznika w formacie uint32_t. Jest on prawidłowy, jeśli counterFlags zawiera XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
  • floatValue to wartość licznika w formacie float. Jest on prawidłowy, jeśli counterFlags zawiera XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

Wartość XrPerformanceMetricsCounterANDROID jest wypełniana przez wywołanie funkcji xrQueryPerformanceMetricsCounterANDROID, aby zapytać o informacje o liczniku danych o skuteczności w czasie rzeczywistym.

Prawidłowe użycie (domyślne)

Nowe funkcje

Funkcja xrEnumeratePerformanceMetricsCounterPathsANDROID wylicza wszystkie ścieżki liczników danych o skuteczności, które są obsługiwane przez środowisko uruchomieniowe. Jest ona zdefiniowana jako: 

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

Opisy parametrów

  • instance to obiekt XrInstance utworzony wcześniej za pomocą funkcji xrCreateInstance.
  • counterPathCapacityInput to pojemność tablicy counterPaths lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • counterPathCountOutput jest wypełniane przez środowisko uruchomieniowe liczbą zapisaną w counterPaths lub wymaganą pojemnością w przypadku, gdy counterPathCapacityInput jest niewystarczająca.
  • counterPaths to tablica XrPath wypełniana przez środowisko uruchomieniowe, która zawiera wszystkie dostępne liczniki danych o skuteczności, ale może być NULL, jeśli counterPathCapacityInput = 0.
  • Szczegółowe informacje o pobieraniu wymaganego rozmiaru counterPaths znajdziesz w sekcji Parametry rozmiaru bufora.

Prawidłowe użycie (domyślne)

  • Przed wywołaniem metody xrEnumeratePerformanceMetricsCounterPathsANDROID należy włączyć rozszerzenie XR_ANDROID_performance_metrics.
  • instance musi być prawidłowym identyfikatorem XrInstance
  • counterPathCountOutput musi być wskaźnikiem na wartość uint32_t
  • Jeśli counterPathCapacityInput nie jest równe 0, counterPaths musi być wskaźnikiem do tablicy wartości counterPathCapacityInput XrPath.

Kody zwrotu

Gotowe

  • XR_SUCCESS

Błąd

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

Funkcja xrSetPerformanceMetricsStateANDROID jest zdefiniowana w ten sposób: 

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

Opisy parametrów

Funkcja xrSetPerformanceMetricsStateANDROID włącza lub wyłącza system pomiarów wydajności.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

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

Funkcja xrGetPerformanceMetricsStateANDROID jest zdefiniowana w ten sposób: 

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Opisy parametrów

Funkcja xrGetPerformanceMetricsStateANDROID zwraca bieżący stan systemu danych o skuteczności.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

Funkcja xrQueryPerformanceMetricsCounterANDROID jest zdefiniowana jako: 

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

Opisy parametrów

Funkcja xrQueryPerformanceMetricsCounterANDROID wysyła zapytanie do licznika danych o skuteczności.

Aplikacja powinna włączyć system danych o wydajności, wywołując xrSetPerformanceMetricsStateANDROID przed wysłaniem zapytania o dane za pomocą xrQueryPerformanceMetricsCounterANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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