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

2025-01-17

É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

Salar Khan, Google

Scott Chung, 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 la poignée à 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 la luminosité

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'espace Xr qui définit l'espace de référence dans lequel la direction de la lumière renvoyée, les harmoniques sphériques et la rotation de la carte cube sont exprimés.
  • 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 le cubemap d'éclairage de l'environnement, la lumière ambiante, les harmoniques sphériques et la lumière directionnelle principale, les applications peuvent enchaîner des instances des structures suivantes : XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID et XrDirectionalLightANDROID respectivement sur XrLightEstimateANDROID::next.

Utilisation valide (implicite)

La structure XrEnvironmentLightingCubemapANDROID contient des données d'estimation de la lumière au format cubemap sur l'éclairage de l'environnement de la scène. 

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

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, XrAmbientLightANDROID et XrDirectionalLightANDROID.
  • state est l'XrLightEstimateStateANDROID représentant l'état de l'estimation de la lumière.
  • cubemapRightImage est un float* représentant le tampon R32G32B32_SFLOAT du côté droit de la carte cube. Notez qu'il s'agit d'un contenu HDR.Par conséquent, les valeurs flottantes peuvent être supérieures à 1,0.
  • cubemapLeftImage est un float* représentant le tampon R32G32B32_SFLOAT du côté gauche de la carte cube. Notez qu'il s'agit d'un contenu HDR.Par conséquent, les valeurs flottantes peuvent être supérieures à 1,0.
  • cubemapTopImage est un float* représentant le tampon R32G32B32_SFLOAT de la face supérieure de la carte cube. Notez qu'il s'agit d'un contenu HDR.Par conséquent, les valeurs flottantes peuvent être supérieures à 1,0.
  • cubemapBottomImage est un float* représentant le tampon R32G32B32_SFLOAT de la face inférieure de la carte cube. Notez qu'il s'agit d'un contenu HDR.Par conséquent, les valeurs flottantes peuvent être supérieures à 1,0.
  • cubemapFrontImage est un float* représentant le tampon R32G32B32_SFLOAT de la face avant de la carte cube. Notez qu'il s'agit d'un contenu HDR.Les valeurs flottantes peuvent donc être supérieures à 1,0.
  • resolution est un uint32_t représentant la largeur et la hauteur de l'image de chaque côté de la carte cubique. Notez qu'il s'agit d'un contenu HDR.Les valeurs flottantes peuvent donc être supérieures à 1,0.
  • rotation est un XrQuaternionf représentant la rotation de la carte cube.
  • centerExposureTime est un XrTime représentant l'heure à laquelle la carte cube a été capturée. Utile pour l'interpolation entre les cubemaps.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_light_estimation doit être activée avant d'utiliser XrEnvironmentLightingCubemapANDROID.
  • type doit être XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID.
  • next doit être NULL ou un pointeur valide vers la structure suivante d'une chaîne de structures.
  • state doit être une valeur XrLightEstimateStateANDROID valide
  • cubemapRightImage doit être un pointeur vers une valeur à virgule flottante valide.
  • cubemapLeftImage doit être un pointeur vers une valeur à virgule flottante valide.
  • cubemapTopImage doit être un pointeur vers une valeur à virgule flottante valide.
  • cubemapBottomImage doit être un pointeur vers une valeur à virgule flottante valide.
  • cubemapFrontImage doit être un pointeur vers une valeur à virgule flottante valide.
  • cubemapBackImage doit être un pointeur vers une valeur à virgule flottante valide.

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, XrEnvironmentLightingCubemapANDROID 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

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,
};


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, 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
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 2, 17/01/2025 (Salar Khan)
    • Ajout de la compatibilité avec les cubemaps d'éclairage de l'environnement
  • Révision 1, 16/09/2024 (Cairn Overturf)
    • Description initiale de l'extension