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 des extensions et des versions

OpenXR 1.0

Date de dernière modification

2025-01-17

État de l'adresse IP

Aucune réclamation connue pour atteinte à la propriété intellectuelle.

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 la luminosité de l'environnement réel autour du casque. Ces informations peuvent être utilisées lors du rendu d'objets virtuels pour les éclairer dans les mêmes conditions que la scène dans laquelle ils sont placés.

Inspecter les capacités du système

Une application peut inspecter si le système prend en charge l'estimation de la luminosité en chaînant une structure XrSystemLightEstimationPropertiesANDROID à 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 dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.
  • supportsLightEstimation est un XrBool32 qui indique si le système actuel prend en charge l'estimation de la luminosité.

Une application peut inspecter si le système est capable de prendre en charge l'estimation de la luminosité en étendant XrSystemProperties avec la structure XrSystemLightEstimationPropertiesANDROID lors de l'appel de xrGetSystemProperties.

Si le système n'est pas en mesure de prendre en charge l'estimation de la luminosité, il renvoie XR_FALSE pour supportsLightEstimation et XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateLightEstimatorANDROID.

Utilisation valide (implicite)

Créer un handle d'estimateur de luminosité

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Le handle XrLightEstimatorANDROID représente un estimateur de lumière. Ce handle peut être utilisé pour accéder aux informations d'estimation de la luminosité à 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

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

  • xrCreateLightEstimatorANDROID renvoie XR_ERROR_FEATURE_UNSUPPORTED si le système ne prend pas en charge l'estimation de la luminosité.
  • xrCreateLightEstimatorANDROID renverra XR_ERROR_PERMISSION_INSUFFICIENT si les autorisations requises n'ont pas été accordées à l'application appelante.

Le handle d'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 luminosité, elle doit détruire le handle à l'aide de xrDestroyLightEstimatorANDROID.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • 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 handle 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 dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.

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 handles enfants doit être synchronisé en externe.

Codes de retour

Opération réussie

  • 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

Opération réussie

  • 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

XrLightEstimateGetInfoANDROID décrit les informations requises pour obtenir les données d'estimation de la luminosité. 

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 dans une chaîne de structures.
  • space est l'XrSpace qui définit l'espace de référence dans lequel sont exprimés la direction de la lumière renvoyée, les harmoniques sphériques et la rotation de la cubemap.
  • 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 sur l'estimation de la luminosité pour la cubemap d'éclairage de l'environnement, la lumière ambiante, les harmoniques sphériques et la lumière directionnelle principale, les applications peuvent chaî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 concernant 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 dans une chaîne de structures. Les structures valides sont XrSphericalHarmonicsANDROID, XrAmbientLightANDROID et XrDirectionalLightANDROID.
  • state est XrLightEstimateStateANDROID, qui représente l'état de l'estimation de la luminosité.
  • cubemapRightImage est un float* représentant le tampon R32G32B32_SFLOAT du côté droit de la cubemap. Notez qu'il s'agit d'une valeur HDR.Les valeurs flottantes peuvent donc être supérieures à 1.
  • cubemapLeftImage est un float* représentant le tampon R32G32B32_SFLOAT du côté gauche de la cubemap. Notez qu'il s'agit d'une valeur HDR.Les valeurs flottantes peuvent donc être supérieures à 1.
  • cubemapTopImage est un float* représentant le tampon R32G32B32_SFLOAT du côté supérieur de la cubemap. Notez qu'il s'agit d'une valeur HDR.Les valeurs flottantes peuvent donc être supérieures à 1.
  • cubemapBottomImage est un float* représentant le tampon R32G32B32_SFLOAT du côté inférieur de la cubemap. Notez qu'il s'agit d'une valeur HDR.Les valeurs flottantes peuvent donc être supérieures à 1.
  • cubemapFrontImage est un float* représentant le tampon R32G32B32_SFLOAT de la face avant de la cubemap. Notez qu'il s'agit d'une valeur HDR.Les valeurs flottantes peuvent donc être supérieures à 1.
  • resolution est un uint32_t représentant la largeur et la hauteur de l'image de chaque côté de la cubemap.
  • rotation est un XrQuaternionf représentant la rotation de la cubemap.
  • centerExposureTime est un XrTime représentant l'heure à laquelle la cubemap 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 dans une chaîne de structures.
  • state doit être une valeur XrLightEstimateStateANDROID valide.
  • cubemapRightImage doit être un pointeur vers une valeur float valide.
  • cubemapLeftImage doit être un pointeur vers une valeur float valide.
  • cubemapTopImage doit être un pointeur vers une valeur float valide.
  • cubemapBottomImage doit être un pointeur vers une valeur float valide.
  • cubemapFrontImage doit être un pointeur vers une valeur float valide.
  • cubemapBackImage doit être un pointeur vers une valeur float valide.

La structure XrAmbientLightANDROID contient des données d'estimation de la luminosité ambiante dans 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 dans une chaîne de structures. Les structures valides sont XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID et XrDirectionalLightANDROID.
  • state est XrLightEstimateStateANDROID, qui représente l'état de l'estimation de la luminosité.
  • 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 composant par composant la couleur de votre rendu corrigé par gamma avec 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 luminosité. 

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Les structures valides sont XrAmbientLightANDROID, XrSphericalHarmonicsANDROID et XrDirectionalLightANDROID.
  • state est XrLightEstimateStateANDROID, qui représente l'état de l'estimation de la luminosité.
  • intensity est une valeur XrVector3 représentant l'intensité de la lumière directionnelle. Chaque composant du vecteur correspond aux canaux rouge, vert et bleu.
  • direction est un XrVector3 représentant la direction de la lumière.

Utilisation valide (implicite)

L'énumération XrSphericalHarmonicsKindANDROID indique au runtime le type d'harmoniques sphériques demandé par l'application. 

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

Les énumérations ont les significations suivantes :

Enum

Description

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

L'énumération XrLightEstimateStateANDROID indique au moteur d'exécution le type d'harmoniques sphériques demandé par l'application. 

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

Les énumérations ont les significations suivantes :

Enum

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 luminosité possibles à partir du runtime.

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 les éléments suivants :

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

L'énumération XrStructureType est étendue avec les éléments suivants :

  • 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, 2025-01-17 (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

OpenXR™ et le logo OpenXR sont des marques déposées appartenant à The Khronos Group Inc. et sont enregistrées en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.