XR_ANDROID_performance_metrics OpenXR uzantısı

Ad dizesi

XR_ANDROID_performance_metrics

Uzantı Türü

Örnek uzatma

Kayıtlı Uzatma Numarası

466

Son Değiştirilme Tarihi

2024-09-06

IP Durumu

Bilinen IP hak talepleri yok.

Uzantı ve Sürüm Bağımlılıkları

OpenXR 1.0

Katkıda bulunanlar

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Genel Bakış

Bu uzantı, mevcut XR cihaz, derleyici ve XR uygulamasının çeşitli performans metriği sayıcılarını listelemek ve sorgulamak için API'ler sağlar. Geliştiriciler, toplanan performans metriği sayaçları ile performans analizi yapabilir ve XR uygulamasında hedeflenen optimizasyon yapabilir. Uygulama, sayaç okumalarına göre davranışını değiştirmemelidir.

Performans metriği sayaçları, /perfmetrics_android kök yolu altında önceden tanımlanmış XrPath değerlerine göre düzenlenir. Bir uygulama, xrEnumeratePerformanceMetricsCounterPathsANDROID aracılığıyla mevcut sayaçları sorgulayabilir. Android cihazlarda sağlanabilecek performans metriği sayıcı yollarının listesi aşağıda verilmiştir:

  • /perfmetrics_android/app/cpu_frametime (milisaniye, kayan nokta) - İstemcinin bir kareyi işlemek için harcadığı gerçek zaman.
  • /perfmetrics_android/app/gpu_frametime (milisaniye, kayan nokta) - istemcinin, GPU çalışmasının kare başına tamamlanmasını beklerken harcadığı gerçek zaman. Notlar:
    • Yüksek bekleme süresi, bu istemcinin çok fazla GPU çalışması yaptığı anlamına gelmez. GPU'nun diğer görevlerle meşgul olduğu anlamına da gelebilir.
    • Oluşturucu tarafından kontrol edildiğinde oluşturma işlemi zaten tamamlanmışsa GPU bekleme süresi sıfır olabilir.
  • /perfmetrics_android/app/cpu_utilization (yüzde, kayan nokta) - Zaman içinde ortalaması alınan toplam uygulama CPU kullanımı oranı.
    • Çok çekirdekli işlemcilerde% 100'den yüksek olabilir.
  • /perfmetrics_android/app/gpu_utilization (yüzde) - Uygulamanın zaman içinde ortalama GPU kullanım oranı.
  • /perfmetrics_android/app/motion_to_photon_latency (milisaniye, kayan nokta) - kullanıcı tarafından başlatılan hareket etkinliğinden ekrandaki ilgili fiziksel görüntü güncellemesine kadar geçen süre.
  • /perfmetrics_android/compositor/cpu_frametime (milisaniye, kayan nokta) - Bir kareyi işlemek için uyumlulaştırıcının harcadığı gerçek zaman.
  • /perfmetrics_android/compositor/gpu_frametime (milisaniye, kayan nokta) - GPU çalışmasının kare başına tamamlanmasını beklerken uyumlulayıcının gerçek zamanlı olarak harcadığı süre.
  • /perfmetrics_android/compositor/dropped_frame_count (tam sayı) - Tüm uygulamalardan atlanan karelerin toplam sayısı.
  • /perfmetrics_android/compositor/frames_per_second (kayan nokta) - Cihazda saniyede oluşturulan kompozitör karelerinin sayısı.
  • /perfmetrics_android/device/cpu_utilization_average (yüzde, kayan nokta) - Tüm çekirdekler ve zaman içinde ortalama olarak cihazın CPU kullanım oranı.
  • /perfmetrics_android/device/cpu_utilization_worst (yüzde, kayan nokta) - Zaman içinde ortalama olarak en kötü performans gösteren çekirdeğin cihaz CPU kullanımı oranı.
  • /perfmetrics_android/device/cpu0_utilization ile /perfmetrics_android/device/cpuX_utilization (yüzde, kayan nokta, X, CPU çekirdeklerinin sayısı eksi birdir) arasında: Zaman içinde ortalama CPU çekirdeği başına cihaz CPU kullanımı oranı.
  • /perfmetrics_android/device/cpu_frequency (MHz, kayan nokta) - Tüm çekirdekler ve zaman içindeki ortalama cihaz CPU frekansı.
  • /perfmetrics_android/device/gpu_utilization (yüzde, kayan nokta) - Zaman içinde ortalama cihaz GPU kullanımı oranı.

Bir oturum oluşturulduktan sonra uygulama, ilgili oturum için performans metrikleri sistemini etkinleştirmek üzere xrSetPerformanceMetricsStateANDROID işlevini kullanabilir. Uygulamalar, performans metrikleri sisteminin etkin olduğu bir oturumda performans metrikleri sayacını sorgulamak için xrQueryPerformanceMetricsCounterANDROID'ı veya performans metrikleri sisteminin etkin olup olmadığını sorgulamak için xrGetPerformanceMetricsStateANDROID'ı kullanabilir.

Bu uzantının işlevini etkinleştirmek için uygulama, Uzantılar bölümünde belirtildiği gibi XrInstanceCreateInfo::enabledExtensionNames parametresini kullanarak uzantının adını xrCreateInstance'e iletmelidir.

Yeni İşaret Türleri

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;

Yeni Enum Sabitleri

XrStructureType dizini aşağıdakilerle genişletildi:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Yeni Sıralamalar

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;

Yeni Yapılar

XrPerformanceMetricsStateANDROID yapısı şu şekilde tanımlanır: 

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • Durum alınırken enabled, performans metrikleri sisteminin etkin olduğunu belirtmek için XR_TRUE olarak ayarlanır. Aksi takdirde XR_FALSE olarak ayarlanır. Durumu ayarlarken performans metrikleri sistemini etkinleştirmek için XR_TRUE, devre dışı bırakmak için XR_FALSE değerini ayarlayın.

Performans metrikleri sistemini etkinleştirmek veya devre dışı bırakmak için xrSetPerformanceMetricsStateANDROID çağrılırken XrPerformanceMetricsStateANDROID giriş olarak sağlanır. Performans metrikleri sisteminin etkin olup olmadığını sorgulamak için xrGetPerformanceMetricsStateANDROID çağrılırken XrPerformanceMetricsStateANDROID çıkış parametresi olarak doldurulur.

Geçerli Kullanım (Dolayı)

  • XrPerformanceMetricsStateANDROID kullanılmadan önce XR_ANDROID_performance_metrics uzantısı etkinleştirilmelidir.
  • type XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID olmalıdır
  • next NULL veya yapı zincirindeki bir sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.

XrPerformanceMetricsCounterANDROID yapısı şu şekilde tanımlanır: 

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • counterFlags, değer üyelerinin geçerliliğini açıklayan XrPerformanceMetricsCounterFlagsANDROID bit maskesi.
  • counterUnit, ölçüm birimini açıklayan XrPerformanceMetricsCounterUnitANDROID enum'udur.
  • uintValue, uint32_t biçimindeki sayaç değeridir. counterFlags, XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID içeriyorsa geçerlidir.
  • floatValue, float biçimindeki sayaç değeridir. counterFlags, XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID içeriyorsa geçerlidir.

XrPerformanceMetricsCounterANDROID, gerçek zamanlı performans metrikleri sayıcı bilgilerini sorgulamak için xrQueryPerformanceMetricsCounterANDROID çağrılarak doldurulur.

Geçerli Kullanım (Dolayı)

Yeni İşlevler

xrEnumeratePerformanceMetricsCounterPathsANDROID işlevi, çalışma zamanı tarafından desteklenen tüm performans metriği sayıcı yollarını listeler ve şu şekilde tanımlanır: 

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

Parametre Açıklamaları

  • instance, daha önce xrCreateInstance ile oluşturulmuş bir XrInstance işleyicisidir.
  • counterPathCapacityInput, counterPaths dizisinin kapasitesidir veya gerekli kapasiteyi alma isteğini belirtmek için 0 değerini alır.
  • counterPathCountOutput, çalışma zamanında yazılan counterPaths sayısıyla veya counterPathCapacityInput yetersiz olduğunda gereken kapasiteyle doldurulur.
  • counterPaths, çalışma zamanında doldurulan ve mevcut tüm performans metriği sayıcılarını içeren bir XrPath dizisidir ancak counterPathCapacityInput 0 ise NULL olabilir.
  • Gerekli counterPaths boyutunu almayla ilgili ayrıntılı açıklama için Arabellek Boyutu Parametreleri bölümüne bakın.

Geçerli Kullanım (Dolayı)

  • xrEnumeratePerformanceMetricsCounterPathsANDROID çağrılmadan önce XR_ANDROID_performance_metrics uzantısı etkinleştirilmelidir.
  • instance geçerli bir XrInstance herkese açık kullanıcı adı olmalıdır.
  • counterPathCountOutput, uint32_t değerine işaret eden bir işaretçi olmalıdır.
  • counterPathCapacityInput 0 değilse counterPaths, counterPathCapacityInput XrPath değer dizisine işaretçi olmalıdır.

İade Kodları

Başarılı

  • XR_SUCCESS

Hata

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

xrSetPerformanceMetricsStateANDROID işlevi şu şekilde tanımlanır: 

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

Parametre Açıklamaları

xrSetPerformanceMetricsStateANDROID işlevi, performans metrikleri sistemini etkinleştirir veya devre dışı bırakır.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

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

xrGetPerformanceMetricsStateANDROID işlevi şu şekilde tanımlanır: 

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Parametre Açıklamaları

xrGetPerformanceMetricsStateANDROID işlevi, performans metrikleri sisteminin mevcut durumunu alır.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

xrQueryPerformanceMetricsCounterANDROID işlevi şu şekilde tanımlanır: 

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

Parametre Açıklamaları

xrQueryPerformanceMetricsCounterANDROID işlevi, performans metrikleri sayacını sorgular.

Uygulama, xrQueryPerformanceMetricsCounterANDROID kullanarak metrikleri sorgulamadan önce xrSetPerformanceMetricsStateANDROID çağrısını yaparak performans metrikleri sistemini etkinleştirmelidir.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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