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

État de ratification

Non ratifié

Dépendances des extensions et des versions

OpenXR 1.0

Date de dernière modification

2025-03-13

É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 l'éclairage de l'environnement réel autour du casque. L'application peut utiliser ces informations pour éclairer les objets virtuels dans les mêmes conditions que la scène du monde réel dans laquelle ils sont placés.

Autorisations

Les applications Android doivent inclure l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE dans leur fichier manifeste, car cette extension expose des informations sur l'éclairage de l'environnement. L'autorisation android.permission.SCENE_UNDERSTANDING_COARSE est considérée comme dangereuse. L'application doit demander l'autorisation au moment de l'exécution pour utiliser ces fonctions :

(niveau de protection : dangereux)

Inspecter les capacités du système

La structure XrSystemLightEstimationPropertiesANDROID est définie comme suit :

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 une XrBool32 qui indique si le système actuel est compatible avec 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 et seulement si un moteur d'exécution renvoie XR_FALSE pour supportsLightEstimation , le moteur d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateLightEstimatorANDROID .

Utilisation valide (implicite)

Créer un handle d'estimateur de luminosité

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Les données d'estimation de la luminosité sont générées par le runtime et partagées avec l'application à l'aide du handle XrLightEstimatorANDROID.

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

  • session est la 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 luminosité.
  • outHandle est un pointeur vers un handle dans lequel l'XrLightEstimatorANDROID créé est renvoyé.

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

  • Le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED si le système ne prend pas en charge l'estimation de la luminosité.
  • L'exécution doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT si les autorisations requises n'ont pas été accordées à l'application appelante.

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 via xrDestroyLightEstimatorANDROID .

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

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

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

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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 est définie comme suit :

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descriptions des paramètres

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

Utilisation valide (implicite)

Sécurité des threads

  • L'accès à estimator et à tous les identifiants 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrLightEstimateGetInfoANDROID est définie comme suit :

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 la direction de la lumière et les harmoniques sphériques renvoyées 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 chaque struct d'estimation de luminosité, si state est XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, tous les autres champs du struct sont arbitraires, ce qui signifie que leurs valeurs ne sont pas définies.

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

Utilisation valide (implicite)

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 incluent XrSphericalHarmonicsANDROID et XrDirectionalLightANDROID .
  • state est XrLightEstimateStateANDROID, qui représente l'état de l'estimation de la luminosité.
  • intensity est un XrVector3f représentant l'intensité de la lumière ambiante. Chaque composant du vecteur correspond respectivement aux canaux rouge, vert et bleu.

  • colorCorrection est un XrVector3f avec des valeurs dans l'espace gamma. Si le rendu est effectué dans l'espace colorimétrique gamma, multipliez-les composant par composant par la couleur finale calculée après le rendu. Si le rendu est effectué dans un espace linéaire, commencez par convertir les valeurs dans un espace linéaire en les élevant à la puissance 2,2, puis multipliez les composants par la couleur finale calculée après le rendu.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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 dans une chaîne de structures. Les structures valides incluent XrAmbientLightANDROID et XrDirectionalLightANDROID .
  • state est XrLightEstimateStateANDROID, qui représente l'état de l'estimation de la luminosité.
  • kind est le XrSphericalHarmonicsKindANDROID demandé par l'application.
  • coefficients est un tableau float bidimensionnel comportant neuf lignes et trois colonnes. Les trois colonnes correspondant respectivement aux canaux de couleur rouge, vert et bleu. Chaque canal comporte neuf coefficients harmoniques sphériques.

Les coefficients doivent être utilisés dans une fonction spéciale qui prend une direction en entrée et renvoie la couleur de la lumière provenant de cette direction. Pour en savoir plus, consultez cet article .

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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

Les valeurs d'énumération ont les significations suivantes :

Description de l'enum

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.

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

Utilisation valide (implicite)

L'énumération XrLightEstimateStateANDROID indique l'état de l'estimation de la luminosité renvoyée par le runtime.

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

Les valeurs d'énumération ont les significations suivantes :

Description de l'enum

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.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

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

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

Nouvelles commandes

Nouvelles structures

Nouveaux enums

Nouvelles constantes d'énumération

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Extension de XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Extension de XrStructureType :

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

Problèmes

Historique des versions

  • Révision 1, 16/09/2024 (Cairn Overturf)

    • Description initiale de l'extension