Extension OpenXR XR_ANDROID_light_estimation

Chaîne de nom

XR_ANDROID_light_estimation

Type d'extension

Extension d'instance

Numéro d'extension enregistré

701

Révision

1

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2024-09-18

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Présentation

Cette extension permet à l'application de demander des données représentant l'éclairage de l'environnement réel autour du casque. Ces informations peuvent être utilisées lors de l'affichage d'objets virtuels pour les éclairer dans les mêmes conditions que la scène dans laquelle ils sont placés.

Inspecter les fonctionnalités du système

Une application peut vérifier si le système est compatible avec l'estimation de la lumière en enchaînant une structure XrSystemLightEstimationPropertiesANDROID à la XrSystemProperties lors de l'appel de xrGetSystemProperties. 

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

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.
  • supportsLightEstimation est un XrBool32, qui indique si le système actuel est compatible avec l'estimation de la luminosité.

Une application peut vérifier si le système est compatible avec l'estimation de la lumière en étendant XrSystemProperties avec la structure XrSystemLightEstimationPropertiesANDROID lors de l'appel de xrGetSystemProperties.

Si le système n'est pas compatible avec l'estimation de la lumière, il renvoie XR_FALSE pour supportsLightEstimation et XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateLightEstimatorANDROID.

Utilisation valide (implicite)

Créer un identifiant d'estimateur léger

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

La poignée XrLightEstimatorANDROID représente un estimateur de lumière. Ce gestionnaire peut être utilisé pour accéder aux informations d'estimation de la lumière à l'aide d'autres fonctions de cette extension.

La fonction xrCreateLightEstimatorANDROID est définie comme suit: 

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Descriptions des paramètres

  • session est l'XrSession qui crée l'outil d'estimation de la lumière.
  • createInfo est un pointeur vers une structure XrLightEstimatorCreateInfoANDROID contenant les paramètres à utiliser pour créer l'estimateur de lumière.
  • outHandle est un pointeur vers un handle dans lequel le XrLightEstimatorANDROID créé est renvoyé.

L'application peut utiliser la fonction xrCreateLightEstimatorANDROID pour créer un estimateur de luminosité.

  • xrCreateLightEstimatorANDROID renvoie XR_ERROR_FEATURE_UNSUPPORTED si le système n'est pas compatible avec l'estimation de la lumière.
  • xrCreateLightEstimatorANDROID renvoie XR_ERROR_PERMISSION_INSUFFICIENT si les autorisations requises n'ont pas été accordées à l'application appelante.

Le conteneur de l'estimateur de luminosité renvoyé peut être utilisé ultérieurement dans les appels d'API. Si une application souhaite indiquer au runtime qu'elle a terminé d'accéder aux données d'estimation de la lumière, elle doit détruire le handle à l'aide de xrDestroyLightEstimatorANDROID.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

La structure XrLightEstimatorCreateInfoANDROID décrit les informations permettant de créer un gestionnaire XrLightEstimatorANDROID. 

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

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.

Utilisation valide (implicite)

La fonction xrDestroyLightEstimatorANDROID libère estimator et toutes les ressources sous-jacentes. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descriptions des paramètres

Utilisation valide (implicite)

Sécurité des threads

  • L'accès à estimator et à tous les gestionnaires enfants doit être synchronisé en externe.

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Accéder aux données d'estimation de l'éclairage

La fonction xrGetLightEstimateANDROID est définie comme suit: 

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Descriptions des paramètres

Utilisation valide (implicite)

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_OUT_OF_MEMORY
  • XR_ERROR_TIME_INVALID

Un XrLightEstimateGetInfoANDROID décrit les informations requises pour obtenir des données d'estimation de la lumière. 

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

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.
  • space est l'XrSpace qui définit l'espace de référence dans lequel la direction de la lumière renvoyée et les harmoniques sphériques sont exprimées.
  • time est le XrTime qui décrit l'heure à laquelle l'application souhaite interroger l'estimation de la luminosité.

Utilisation valide (implicite)

La structure XrLightEstimateANDROID contient des données d'estimation de la luminosité. 

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

Descriptions des membres

Pour obtenir des informations d'estimation de la lumière pour la lumière ambiante, les harmoniques sphériques et la lumière directionnelle principale, les applications peuvent enchaîner des instances des structures suivantes, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID et XrDirectionalLightANDROID respectivement sur XrLightEstimateANDROID::next.

Utilisation valide (implicite)

La structure XrAmbientLightANDROID contient des données d'estimation de la lumière sur la lumière ambiante de la scène. 

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

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. Les structures valides sont XrSphericalHarmonicsANDROID et XrDirectionalLightANDROID.
  • state est l'XrLightEstimateStateANDROID représentant l'état de l'estimation de la lumière.
  • intensity est un XrVector3 représentant l'intensité de la lumière ambiante. Chaque composant du vecteur correspond aux canaux rouge, vert et bleu.
  • colorCorrection est un XrVector3 avec des valeurs dans l'espace gamma. Multipliez la couleur de votre rendu corrigé par gamma par ces valeurs.

Utilisation valide (implicite)

La structure XrSphericalHarmonicsANDROID contient des harmoniques sphériques représentant l'éclairage de la scène. 

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

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. Les structures valides sont XrAmbientLightANDROID et XrDirectionalLightANDROID.
  • state est l'XrLightEstimateStateANDROID représentant l'état de l'estimation de la lumière.
  • kind est le XrSphericalHarmonicsKindANDROID demandé par l'application.
  • coefficients est un tableau float bidimensionnel de 9 lignes et 3 colonnes. Les trois colonnes correspondant aux canaux de couleur rouge, vert et bleu, respectivement. Chaque canal comporte neuf coefficients harmoniques sphériques.

Utilisation valide (implicite)

La structure XrDirectionalLightANDROID contient des données d'estimation de la lumière. 

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

Descriptions des membres

Utilisation valide (implicite)

L'énumération XrSphericalHarmonicsKindANDROID indique au runtime le type de fonctions sphériques que l'application demande. 

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

Les énumérations ont la signification suivante:

Énumération

Description

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Les coefficients des harmoniques sphériques représentent la fonction de rayonnement de la lumière ambiante, à l'exclusion de la contribution de la lumière principale.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Les coefficients des harmoniques sphériques représentent la fonction de rayonnement de la lumière ambiante, y compris la contribution de la lumière principale.

L'énumération XrLightEstimateStateANDROID indique au runtime le type d'harmoniques sphériques que l'application demande. 

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;

Les énumérations ont la signification suivante:

Énumération

Description

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

L'estimation de la luminosité est valide

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

L'estimation de la luminosité n'est pas valide

Exemple de code pour l'estimation de la luminosité

L'exemple de code suivant montre comment obtenir toutes les quantités d'estimation de la lumière possibles à partir de l'environnement d'exécution.

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
    .next = &totalSh,
};

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &ambientSh,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight if each
  // struct has a valid state field
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

Nouveaux types d'objets

  • XrLightEstimator

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

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

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

  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_AMBIENT_LIGHT_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 1, 16/09/2024 (Cairn Overturf)
    • Description initiale de l'extension