Estensione OpenXR XR_ANDROID_performance_metrics

Stringa del nome

XR_ANDROID_performance_metrics

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

466

Data ultima modifica

2024-09-06

Stato IP

Nessuna rivendicazione IP nota.

Dipendenze di estensioni e versioni

OpenXR 1.0

Collaboratori

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Panoramica

Questa estensione fornisce API per enumerare e eseguire query su vari contatori delle metriche sul rendimento del dispositivo XR, del compositore e dell'applicazione XR corrente. Gli sviluppatori possono eseguire analisi del rendimento e ottimizzazione mirata dell'applicazione VR/AR utilizzando i contatori delle metriche sul rendimento raccolti. L'applicazione non deve modificare il proprio comportamento in base alle letture del contatore.

I contatori delle metriche sul rendimento sono organizzati in valori predefiniti XrPath, nel percorso principale /perfmetrics_android. Un'applicazione può eseguire query sui contatori disponibili tramite xrEnumeratePerformanceMetricsCounterPathsANDROID. Ecco un elenco dei percorsi dei contatori delle metriche sul rendimento che possono essere forniti sui dispositivi Android:

• /perfmetrics_android/app/cpu_frametime (millisecondi, numero in virgola mobile) - tempo del sistema del client impiegato per elaborare un frame.
• /perfmetrics_android/app/gpu_frametime (millisecondi, float) - tempo del sistema del client impiegato in attesa del completamento del lavoro della GPU per frame. Note:
  • Un tempo di attesa elevato può indicare che la GPU era occupata con altre attività, non necessariamente che questo client stia eseguendo troppe attività GPU.
  • Il tempo di attesa della GPU può essere pari a zero se il rendering è già stato completato al momento del controllo da parte del compositore.
• /perfmetrics_android/app/cpu_utilization (percentuale, numero in virgola mobile) - tasso di utilizzo totale della CPU dell'app calcolato in media nel tempo.
  • Può essere superiore al 100% sui processori multi-core.
• /perfmetrics_android/app/gpu_utilization (percentuale) - il tasso di utilizzo totale della GPU dell'app calcolato in media nel tempo.
• /perfmetrics_android/app/motion_to_photon_latency (millisecondi, float) - tempo trascorso dall'evento di movimento avviato dall'utente all'aggiornamento corrispondente dell'immagine fisica sul display.
• /perfmetrics_android/compositor/cpu_frametime (millisecondi, float) - tempo reale impiegato dal compositor per elaborare un frame.
• /perfmetrics_android/compositor/gpu_frametime (millisecondi, float) - tempo del sistema operativo impiegato dal compositore in attesa del completamento del lavoro della GPU per frame.
• /perfmetrics_android/compositor/dropped_frame_count (intero) - numero totale di frame persi da tutte le app.
• /perfmetrics_android/compositor/frames_per_second (float) - numero di frame del compositore disegnati sul dispositivo al secondo.
• /perfmetrics_android/device/cpu_utilization_average (percentuale, numero in virgola mobile) - il tasso di utilizzo della CPU del dispositivo calcolato in media su tutti i core e in media nel tempo.
• /perfmetrics_android/device/cpu_utilization_worst (percentuale, numero in virgola mobile) - tasso di utilizzo della CPU del dispositivo del core con il rendimento peggiore medie nel tempo.
• /perfmetrics_android/device/cpu0_utilization fino a /perfmetrics_android/device/cpuX_utilization (percentuale, numero in virgola mobile, X è il numero di core della CPU meno uno) - tasso di utilizzo della CPU del dispositivo per core della CPU calcolato in media nel tempo.
• /perfmetrics_android/device/cpu_frequency (MHz, float) - frequenza della CPU del dispositivo media su tutti i core e mediata nel tempo.
• /perfmetrics_android/device/gpu_utilization (percentuale, numero in virgola mobile) - il tasso di utilizzo della GPU del dispositivo calcolato in media nel tempo.

Dopo aver creato una sessione, un'applicazione può utilizzare xrSetPerformanceMetricsStateANDROID per attivare il sistema di misurazione delle prestazioni per quella sessione. Un'applicazione può utilizzare xrQueryPerformanceMetricsCounterANDROID per eseguire query su un contatore delle metriche sul rendimento in una sessione in cui è abilitato il sistema di metriche sul rendimento oppure utilizzare xrGetPerformanceMetricsStateANDROID per eseguire query sull'eventuale attivazione del sistema di metriche sul rendimento.

Nota: gli intervalli di misurazione dei singoli contatori delle metriche sul rendimento sono definiti dal runtime OpenXR. L'applicazione non deve fare supposizioni o modificare il proprio comportamento in fase di esecuzione misurandoli.

Per attivare la funzionalità di questa estensione, l'applicazione deve passare il nome dell'estensione a xrCreateInstance utilizzando il parametro XrInstanceCreateInfo::enabledExtensionNames come indicato nella sezione Estensioni.

Nuovi tipi di 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;

Nuove costanti enum

L'enumerazione XrStructureType è stata estesa con:

• XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
• XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Nuovi 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;

Nuove strutture

La struttura XrPerformanceMetricsStateANDROID è definita come segue:

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

Descrizioni dei membri

• type è il XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
• enabled è impostato su XR_TRUE per indicare che il sistema delle metriche sul rendimento è attivo, XR_FALSE in caso contrario, quando si ottiene lo stato. Quando imposti lo stato, imposta XR_TRUE per attivare il sistema di metriche sul rendimento e XR_FALSE per disattivarlo.

XrPerformanceMetricsStateANDROID viene fornito come input quando viene chiamata xrSetPerformanceMetricsStateANDROID per attivare o disattivare il sistema di misurazione delle prestazioni. XrPerformanceMetricsStateANDROID viene compilato come parametro di output quando viene chiamata la funzione xrGetPerformanceMetricsStateANDROID per eseguire una query per verificare se il sistema delle metriche sul rendimento è abilitato.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_performance_metrics deve essere attivata prima di utilizzare XrPerformanceMetricsStateANDROID
• type deve essere XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

La struttura XrPerformanceMetricsCounterANDROID è definita come segue:

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

Descrizioni dei membri

• type è il XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
• counterFlags è una maschera di bit di XrPerformanceMetricsCounterFlagsANDROID che descrive la validità dei membri di valore.
• counterUnit è un enum di XrPerformanceMetricsCounterUnitANDROID che descrive l'unità di misura.
• uintValue è il valore del contatore in formato uint32_t. È valido se counterFlags contiene XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
• floatValue è il valore del contatore in formato float. È valido se counterFlags contiene XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

XrPerformanceMetricsCounterANDROID viene compilato chiamando xrQueryPerformanceMetricsCounterANDROID per eseguire query sulle informazioni del contatore delle metriche sul rendimento in tempo reale.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_performance_metrics deve essere attivata prima di utilizzare XrPerformanceMetricsCounterANDROID
• type deve essere XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• counterFlags deve essere 0 o una combinazione valida di valori XrPerformanceMetricsCounterFlagsANDROID
• counterUnit deve essere un valore valido di XrPerformanceMetricsCounterUnitANDROID

Nuove funzioni

La funzione xrEnumeratePerformanceMetricsCounterPathsANDROID enumera tutti i percorsi degli indicatori delle metriche sul rendimento supportati dal runtime ed è definita come:

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

Descrizioni dei parametri

• instance è un handle XrInstance creato in precedenza con xrCreateInstance.
• counterPathCapacityInput è la capacità dell'array counterPaths o 0 per indicare una richiesta di recupero della capacità richiesta.
• counterPathCountOutput viene compilato dal runtime con il conteggio di counterPaths scritto o con la capacità richiesta nel caso in cui counterPathCapacityInput non sia sufficiente.
• counterPaths è un array di XrPath compilato dal runtime che contiene tutti i contatori delle metriche sul rendimento disponibili, ma può essere NULL se counterPathCapacityInput è 0.
• Per una descrizione dettagliata del recupero della dimensione counterPaths richiesta, consulta la sezione Parametri di dimensione del buffer.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_performance_metrics deve essere attivata prima di chiamare xrEnumeratePerformanceMetricsCounterPathsANDROID
• instance deve essere un handle XrInstance valido
• counterPathCountOutput deve essere un puntatore a un valore uint32_t
• Se counterPathCapacityInput non è 0, counterPaths deve essere un puntatore a un array di valori counterPathCapacityInput XrPath

Codici di ritorno

Operazione riuscita

• XR_SUCCESS

Errore

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

La funzione xrSetPerformanceMetricsStateANDROID è definita come segue:

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

Descrizioni dei parametri

• session è un handle XrSession creato in precedenza con xrCreateSession.
• state è un puntatore a una struttura XrPerformanceMetricsStateANDROID.

La funzione xrSetPerformanceMetricsStateANDROID attiva o disattiva il sistema di misurazione delle prestazioni.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_performance_metrics deve essere attivata prima di chiamare xrSetPerformanceMetricsStateANDROID
• session deve essere un handle XrSession valido
• state deve essere un puntatore a una struttura XrPerformanceMetricsStateANDROID valida

Codici di ritorno

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

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

La funzione xrGetPerformanceMetricsStateANDROID è definita come segue:

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Descrizioni dei parametri

• session è un handle XrSession creato in precedenza con xrCreateSession.
• state è un puntatore a una struttura XrPerformanceMetricsStateANDROID.

La funzione xrGetPerformanceMetricsStateANDROID recupera lo stato corrente del sistema di metriche sul rendimento.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_performance_metrics deve essere attivata prima di chiamare xrGetPerformanceMetricsStateANDROID
• session deve essere un handle XrSession valido
• state deve essere un puntatore a una struttura XrPerformanceMetricsStateANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST

La funzione xrQueryPerformanceMetricsCounterANDROID è definita come:

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

Descrizioni dei parametri

• session è un handle XrSession creato in precedenza con xrCreateSession.
• counterPath è un percorso del contatore delle metriche sul rendimento valido.
• counter è un puntatore a una struttura XrPerformanceMetricsCounterANDROID.

La funzione xrQueryPerformanceMetricsCounterANDROID esegue una query su un contatore delle metriche sul rendimento.

L'applicazione deve attivare il sistema di metriche sul rendimento chiamando xrSetPerformanceMetricsStateANDROID prima di eseguire query sulle metriche utilizzando xrQueryPerformanceMetricsCounterANDROID.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_performance_metrics deve essere attivata prima di chiamare xrQueryPerformanceMetricsCounterANDROID
• session deve essere un handle XrSession valido
• counter deve essere un puntatore a una struttura XrPerformanceMetricsCounterANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

• 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