Extension OpenXR XR_ANDROID_performance_metrics

Chaîne de nom

XR_ANDROID_performance_metrics

Type d'extension

Extension d'instance

Numéro d'extension enregistré

466

Date de dernière modification

2024-09-06

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Dépendances d'extension et de version

OpenXR 1.0

Contributeurs

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Présentation

Cette extension fournit des API permettant d'énumérer et d'interroger divers compteurs de métriques de performances de l'appareil XR, du compositeur et de l'application XR actuels. Les développeurs peuvent effectuer une analyse des performances et une optimisation ciblée de l'application XR à l'aide des compteurs de métriques de performances collectés. L'application ne doit pas modifier son comportement en fonction des lectures du compteur.

Les compteurs de métriques de performances sont organisés en valeurs XrPath prédéfinies, sous le chemin d'accès racine /perfmetrics_android. Une application peut interroger les compteurs disponibles via xrEnumeratePerformanceMetricsCounterPathsANDROID. Voici la liste des chemins de compteur de métriques de performances qui peuvent être fournis sur les appareils Android:

• /perfmetrics_android/app/cpu_frametime (millisecondes, float) : temps réel passé par le client pour traiter un frame.
• /perfmetrics_android/app/gpu_frametime (millisecondes, float) : temps réel passé par le client à attendre la fin du travail du GPU par frame. Remarques :
  • Un temps d'attente élevé peut signifier que le GPU était occupé par d'autres tâches, et non nécessairement que ce client effectue trop de tâches GPU.
  • Le temps d'attente du GPU peut être nul si le rendu était déjà terminé lors de la vérification par le compositeur.
• /perfmetrics_android/app/cpu_utilization (pourcentage, flottant) : taux d'utilisation total du processeur de l'application, calculé en moyenne sur la durée.
  • Il peut être supérieur à 100% sur les processeurs multicœurs.
• /perfmetrics_android/app/gpu_utilization (pourcentage) : taux d'utilisation total du GPU de l'application moyenné au fil du temps.
• /perfmetrics_android/app/motion_to_photon_latency (millisecondes, float) : temps écoulé entre l'événement de mouvement déclenché par l'utilisateur et la mise à jour de l'image physique correspondante à l'écran.
• /perfmetrics_android/compositor/cpu_frametime (millisecondes, float) : temps réel passé par le moteur de rendu pour traiter un frame.
• /perfmetrics_android/compositor/gpu_frametime (millisecondes, float) : temps réel passé par le moteur de rendu à attendre la fin du travail du GPU par frame.
• /perfmetrics_android/compositor/dropped_frame_count (entier) : nombre total d'images perdues de toutes les applications.
• /perfmetrics_android/compositor/frames_per_second (float) : nombre d'images du moteur de rendu dessinées sur l'appareil par seconde.
• /perfmetrics_android/device/cpu_utilization_average (pourcentage, flottant) : taux d'utilisation du processeur de l'appareil moyenné sur tous les cœurs et au fil du temps.
• /perfmetrics_android/device/cpu_utilization_worst (pourcentage, flottant) : taux d'utilisation du processeur de l'appareil du cœur le moins performant, calculé en moyenne sur la durée.
• /perfmetrics_android/device/cpu0_utilization à /perfmetrics_android/device/cpuX_utilization (pourcentage, flottant, X correspond au nombre de cœurs de processeur moins un) : taux d'utilisation du processeur de l'appareil par cœur de processeur moyenné au fil du temps.
• /perfmetrics_android/device/cpu_frequency (MHz, float) : fréquence du processeur de l'appareil calculée en moyenne sur tous les cœurs et au fil du temps.
• /perfmetrics_android/device/gpu_utilization (pourcentage, flottant) : taux d'utilisation du GPU de l'appareil moyenné au fil du temps.

Une fois une session créée, une application peut utiliser xrSetPerformanceMetricsStateANDROID pour activer le système de métriques de performances pour cette session. Une application peut utiliser xrQueryPerformanceMetricsCounterANDROID pour interroger un compteur de métriques de performances sur une session pour laquelle le système de métriques de performances est activé, ou utiliser xrGetPerformanceMetricsStateANDROID pour interroger si le système de métriques de performances est activé.

Remarque :Les intervalles de mesure des compteurs de métriques de performances individuels sont définis par l'environnement d'exécution OpenXR. L'application ne doit pas faire d'hypothèses ni modifier son comportement au moment de l'exécution en les mesurant.

Pour activer les fonctionnalités de cette extension, l'application doit transmettre le nom de l'extension à xrCreateInstance à l'aide du paramètre XrInstanceCreateInfo::enabledExtensionNames, comme indiqué dans la section Extensions.

Nouveaux types d'options

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;

Nouvelles constantes d'énumération

L'énumération XrStructureType est étendue avec:

• XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
• XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Nouveaux énumérations

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;

Nouvelles structures

La structure XrPerformanceMetricsStateANDROID est définie comme suit:

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
• enabled est défini sur XR_TRUE pour indiquer que le système de métriques de performances est activé, ou sur XR_FALSE dans le cas contraire, lors de l'obtention de l'état. Lorsque vous définissez l'état, définissez-le sur XR_TRUE pour activer le système de métriques de performances et sur XR_FALSE pour le désactiver.

XrPerformanceMetricsStateANDROID est fourni en entrée lors de l'appel de xrSetPerformanceMetricsStateANDROID pour activer ou désactiver le système de métriques de performances. XrPerformanceMetricsStateANDROID est renseigné en tant que paramètre de sortie lors de l'appel de xrGetPerformanceMetricsStateANDROID pour interroger si le système de métriques de performances est activé.

Utilisation valide (implicite)

• L'extension XR_ANDROID_performance_metrics doit être activée avant d'utiliser XrPerformanceMetricsStateANDROID.
• type doit être XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.

La structure XrPerformanceMetricsCounterANDROID est définie comme suit:

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
• counterFlags est un masque de bits de XrPerformanceMetricsCounterFlagsANDROID décrivant la validité des membres de valeur.
• counterUnit est une énumération de XrPerformanceMetricsCounterUnitANDROID décrivant l'unité de mesure.
• uintValue est la valeur du compteur au format uint32_t. Il est valide si counterFlags contient XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
• floatValue est la valeur du compteur au format float. Il est valide si counterFlags contient XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

XrPerformanceMetricsCounterANDROID est renseigné en appelant xrQueryPerformanceMetricsCounterANDROID pour interroger les informations du compteur de métriques de performances en temps réel.

Utilisation valide (implicite)

• L'extension XR_ANDROID_performance_metrics doit être activée avant d'utiliser XrPerformanceMetricsCounterANDROID.
• type doit être XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
• counterFlags doit être égal à 0 ou à une combinaison valide de valeurs XrPerformanceMetricsCounterFlagsANDROID.
• counterUnit doit être une valeur XrPerformanceMetricsCounterUnitANDROID valide.

Nouvelles fonctions

La fonction xrEnumeratePerformanceMetricsCounterPathsANDROID énumère tous les chemins de compteur de métriques de performances compatibles avec l'environnement d'exécution. Elle est définie comme suit:

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

Descriptions des paramètres

• instance est un gestionnaire XrInstance précédemment créé avec xrCreateInstance.
• counterPathCapacityInput correspond à la capacité du tableau counterPaths, ou à 0 pour indiquer une requête visant à récupérer la capacité requise.
• counterPathCountOutput est renseigné par l'environnement d'exécution avec le nombre d'counterPaths écrites ou la capacité requise si counterPathCapacityInput est insuffisant.
• counterPaths est un tableau de XrPath renseigné par l'environnement d'exécution, qui contient tous les compteurs de métriques de performances disponibles, mais peut être NULL si counterPathCapacityInput est égal à 0.
• Pour obtenir une description détaillée de la récupération de la taille counterPaths requise, consultez la section Paramètres de taille de la mémoire tampon.

Utilisation valide (implicite)

• L'extension XR_ANDROID_performance_metrics doit être activée avant d'appeler xrEnumeratePerformanceMetricsCounterPathsANDROID.
• instance doit être un identifiant XrInstance valide.
• counterPathCountOutput doit être un pointeur vers une valeur uint32_t.
• Si counterPathCapacityInput n'est pas égal à 0, counterPaths doit être un pointeur vers un tableau de valeurs counterPathCapacityInput XrPath.

Codes de retour

Réussite

• XR_SUCCESS

Échec

• 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 fonction xrSetPerformanceMetricsStateANDROID est définie comme suit:

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

Descriptions des paramètres

• session est un gestionnaire XrSession précédemment créé avec xrCreateSession.
• state est un pointeur vers une structure XrPerformanceMetricsStateANDROID.

La fonction xrSetPerformanceMetricsStateANDROID active ou désactive le système de métriques de performances.

Utilisation valide (implicite)

• L'extension XR_ANDROID_performance_metrics doit être activée avant d'appeler xrSetPerformanceMetricsStateANDROID.
• session doit être un identifiant XrSession valide.
• state doit être un pointeur vers une structure XrPerformanceMetricsStateANDROID valide.

Codes de retour

Réussite

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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 fonction xrGetPerformanceMetricsStateANDROID est définie comme suit:

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Descriptions des paramètres

• session est un gestionnaire XrSession précédemment créé avec xrCreateSession.
• state est un pointeur vers une structure XrPerformanceMetricsStateANDROID.

La fonction xrGetPerformanceMetricsStateANDROID récupère l'état actuel du système de métriques de performances.

Utilisation valide (implicite)

• L'extension XR_ANDROID_performance_metrics doit être activée avant d'appeler xrGetPerformanceMetricsStateANDROID.
• session doit être un identifiant XrSession valide.
• state doit être un pointeur vers une structure XrPerformanceMetricsStateANDROID.

Codes de retour

Réussite

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST

La fonction xrQueryPerformanceMetricsCounterANDROID est définie comme suit:

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

Descriptions des paramètres

• session est un gestionnaire XrSession précédemment créé avec xrCreateSession.
• counterPath est un chemin de compteur de métriques de performances valide.
• counter est un pointeur vers une structure XrPerformanceMetricsCounterANDROID.

La fonction xrQueryPerformanceMetricsCounterANDROID interroge un compteur de métriques de performances.

L'application doit activer le système de métriques de performances en appelant xrSetPerformanceMetricsStateANDROID avant d'interroger les métriques à l'aide de xrQueryPerformanceMetricsCounterANDROID.

Utilisation valide (implicite)

• L'extension XR_ANDROID_performance_metrics doit être activée avant d'appeler xrQueryPerformanceMetricsCounterANDROID.
• session doit être un identifiant XrSession valide.
• counter doit être un pointeur vers une structure XrPerformanceMetricsCounterANDROID.

Codes de retour

Réussite

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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