XR_ANDROID_light_estimation_cubemap

Name String

XR_ANDROID_light_estimation_cubemap

Type d'extension

Extension d'instance

Numéro d'extension enregistré

722

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_light_estimation

Date de dernière modification

2025-08-06

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google

Présentation

Cette extension s'appuie sur l'extension XR_ANDROID_light_estimation de base. Elle ajoute la prise en charge de l'obtention d'estimations de l'éclairage par cubemap, qui fournit des estimations plus détaillées de l'éclairage dans l'environnement physique.

Remarque

Le mécanisme d'obtention des données d'estimation de la lumière est le même que pour l'extension de base, sauf que XrCubemapLightEstimatorCreateInfoANDROID doit être associé à XrLightEstimatorCreateInfoANDROID lors de la création du handle de l'estimateur de lumière.

Inspecter les capacités du système

typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;

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 OpenXR de base ou dans cette extension.
  • supportsCubemapLightEstimation est un XrBool32 , qui indique si le système actuel est compatible avec l'estimation de la lumière par cubemap.

Une application peut vérifier si le système est capable de prendre en charge l'estimation de la lumière par cubemap en étendant XrSystemProperties avec la structure XrSystemCubemapLightEstimationPropertiesANDROID lors de l'appel de xrGetSystemProperties .

Si l'environnement d'exécution renvoie XR_FALSE pour supportsCubemapLightEstimation et que XrCubemapLightEstimatorCreateInfoANDROID a été associé à XrLightEstimatorCreateInfoANDROID , l'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateLightEstimatorANDROID .

Utilisation valide (implicite)

Obtenir les résolutions de cubemap compatibles

XrResult xrEnumerateCubemapLightingResolutionsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    uint32_t*                                   resolutions);

Description des paramètres

  • instance est une XrInstance créée précédemment.
  • systemId est le XrSystemId récupéré précédemment par xrGetSystem pour lequel obtenir les résolutions de cubemap compatibles.
  • resolutionCapacityInput est un uint32_t indiquant le nombre maximal d'éléments pouvant être stockés dans le tableau resolutions.
  • resolutionCountOutput est un pointeur vers un uint32_t défini par l'environnement d'exécution, qui indique le nombre d'éléments écrits dans le tableau resolutions par l'environnement d'exécution.
  • resolutions est un tableau de uint32_t qui est renseigné par l'environnement d'exécution avec les résolutions de cubemap compatibles.

La résolution d'une cubemap indique la largeur et la hauteur de chaque face de la cubemap en pixels. Idiome à deux appels : l'application peut ensuite choisir d'utiliser l'une des résolutions compatibles dans XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution lors de la création du handle de l'estimateur de lumière. L'application doit allouer la quantité de mémoire appropriée pour les membres du tampon d'image de XrCubemapLightingDataANDROID en fonction de la résolution choisie et du format de couleur.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_light_estimation_cubemap doit être activée avant d'appeler xrEnumerateCubemapLightingResolutionsANDROID.
  • instance doit être un handle XrInstance valide
  • resolutionCountOutput doit être un pointeur vers une valeur uint32_t
  • Si resolutionCapacityInput n'est pas 0 , resolutions doit être un pointeur vers un tableau de valeurs resolutionCapacityInput uint32_t.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Obtenir les formats de couleur de cubemap compatibles

L'énumération XrCubemapLightingColorFormatANDROID identifie pour l'environnement d'exécution le format de couleur de l'éclairage de la cubemap à utiliser.

typedef enum XrCubemapLightingColorFormatANDROID {
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID = 1,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID = 2,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID = 3,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrCubemapLightingColorFormatANDROID;

Les énumérations ont les significations suivantes :

Description de l'enum

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Format de couleur à trois canaux, où chaque canal est une valeur à virgule flottante 32 bits.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Format de couleur à quatre canaux, où chaque canal est une valeur à virgule flottante 32 bits.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Format de couleur à quatre canaux, où chaque canal est une valeur à virgule flottante de 16 bits.

XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    colorFormatCapacityInput,
    uint32_t*                                   colorFormatCountOutput,
    XrCubemapLightingColorFormatANDROID*        colorFormats);

Description des paramètres

  • instance est une XrInstance créée précédemment.
  • systemId est le XrSystemId récupéré précédemment par xrGetSystem pour lequel obtenir les résolutions de cubemap compatibles.
  • colorFormatCapacityInput est un uint32_t indiquant le nombre maximal d'éléments pouvant être stockés dans le tableau colorFormats.
  • colorFormatCountOutput est un pointeur vers un uint32_t défini par l'environnement d'exécution, qui indique le nombre d'éléments écrits dans le tableau colorFormats par l'environnement d'exécution.
  • colorFormats est un tableau de XrCubemapLightingColorFormatANDROID qui est renseigné par l'environnement d'exécution avec les formats de couleur de cubemap compatibles.

Idiome à deux appels : l'application peut ensuite choisir d'utiliser l'un des formats de couleur compatibles dans XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat lors de la création du handle de l'estimateur de lumière. L'application doit allouer la quantité de mémoire appropriée pour les membres du tampon d'image de XrCubemapLightingDataANDROID en fonction du format de couleur choisi.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Créer un handle d'estimateur de lumière cubemap

typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
    XrStructureType                        type;
    const void*                            next;
    uint32_t                               cubemapResolution;
    XrCubemapLightingColorFormatANDROID    colorFormat;
    XrBool32                               reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;

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.
  • cubemapResolution est un uint32_t indiquant la résolution de l'éclairage de la carte cubique à utiliser.
  • colorFormat est un XrCubemapLightingColorFormatANDROID indiquant le format de couleur des données d'éclairage de la cubemap à utiliser.
  • reproject est un XrBool32 indiquant si l'éclairage de la cubemap doit être reprojeté dans l'espace de base de l'application.

La structure XrCubemapLightEstimatorCreateInfoANDROID décrit les informations permettant de créer un handle XrLightEstimatorANDROID capable de fournir des estimations d'éclairage de cubemap. Le membre cubemapResolution de XrCubemapLightEstimatorCreateInfoANDROID doit être défini sur l'une des résolutions renvoyées par xrEnumerateCubemapLightingResolutionsANDROID . Le membre colorFormat de XrCubemapLightEstimatorCreateInfoANDROID doit être défini sur l'un des formats de couleur renvoyés par xrEnumerateCubemapLightingColorFormatsANDROID . Si l'application ne définit pas la résolution sur l'une des résolutions compatibles ou le format de couleur sur l'un des formats de couleur compatibles, l'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateLightEstimatorANDROID .

Utilisation valide (implicite)

Estimations de la lumière de la carte cubique

typedef struct XrCubemapLightingDataANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    uint32_t                       imageBufferSize;
    uint8_t*                       imageBufferRight;
    uint8_t*                       imageBufferLeft;
    uint8_t*                       imageBufferTop;
    uint8_t*                       imageBufferBottom;
    uint8_t*                       imageBufferFront;
    uint8_t*                       imageBufferBack;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrCubemapLightingDataANDROID;

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 l'élément XrLightEstimateStateANDROID représentant l'état de l'estimation de la luminosité.
  • imageBufferSize est un uint32_t indiquant la taille en octets de chaque tampon d'image de visage dans la cubemap.
  • imageBufferRight est un tampon uint8_t contenant l'image de la face droite de la cubemap.
  • imageBufferLeft est un tampon uint8_t contenant l'image de la face gauche de la cubemap.
  • imageBufferTop est un tampon uint8_t contenant l'image de la face supérieure de la cubemap.
  • imageBufferBottom est un tampon uint8_t contenant l'image de la face inférieure de la cubemap.
  • imageBufferFront est un tampon uint8_t contenant l'image de la face avant de la cubemap.
  • imageBufferBack est un tampon uint8_t contenant l'image de la face arrière de la cubemap.
  • rotation est un XrQuaternionf indiquant la rotation de la cubemap.
  • centerExposureTime est un XrTime indiquant l'heure à laquelle la cubemap a été capturée.

Cette structure peut être associée à XrLightEstimateANDROID . L'environnement d'exécution doit renseigner cette structure dans xrGetLightEstimateANDROID uniquement si XrCubemapLightEstimatorCreateInfoANDROID a été utilisé pour créer le handle de l'estimateur de lumière. L'application doit allouer la quantité de mémoire appropriée pour les tampons d'image, qui dépend des valeurs définies dans XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution et XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat lors de la création du handle de l'estimateur de lumière. L'application doit définir XrCubemapLightingDataANDROID :: imageBufferSize sur la capacité de chaque tampon d'image de face en octets. Si l'application n'utilise pas l'estimation de l'éclairage par cubemap ou si XrCubemapLightingDataANDROID :: imageBufferSize n'est pas assez grand pour que l'environnement d'exécution remplisse les tampons d'image, l'environnement d'exécution doit définir XrCubemapLightingDataANDROID :: state sur XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .

Si l'application a défini XrCubemapLightEstimatorCreateInfoANDROID :: reproject sur XR_TRUE lors de la création du handle de l'estimateur de lumière, l'environnement d'exécution doit définir XrCubemapLightingDataANDROID :: rotation sur la rotation d'identité et s'assurer que la cubemap pivotée interne est reprojetée sur les faces d'une cubemap d'identité dans l'espace de base de l'application.

La mise en page de la cubemap d'éclairage est identique à celle de la cubemap OpenGL, comme illustré dans l'image suivante.

Disposition de la cubemap d'estimation de la luminosité XR ANDROID

Figure 31. Mise en page cubique.

Utilisation valide (implicite)

  •  L'extension XR_ANDROID_light_estimation_cubemap doit être activée avant d'utiliser XrCubemapLightingDataANDROID.
  • type doit être XR_TYPE_CUBEMAP_LIGHTING_DATA_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
  • imageBufferRight doit être un pointeur vers un tableau de valeurs imageBufferSize uint8_t
  • imageBufferLeft doit être un pointeur vers un tableau de valeurs imageBufferSize uint8_t
  • imageBufferTop doit être un pointeur vers un tableau de valeurs imageBufferSize uint8_t
  • imageBufferBottom doit être un pointeur vers un tableau de valeurs imageBufferSize uint8_t
  • imageBufferFront doit être un pointeur vers un tableau de valeurs imageBufferSize uint8_t
  • imageBufferBack doit être un pointeur vers un tableau de valeurs imageBufferSize uint8_t
  • Le paramètre imageBufferSize doit être supérieur à 0.

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 de l'environnement d'exécution.

XrSession session;  // Created at app startup
XrInstance instance; // Created at app startup
XrSpace appSpace;   // Created previously.
XrSystemId systemId; // Retrieved previously by xrGetSystem
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingResolutionsANDROID xrEnumerateCubemapLightingResolutionsANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingColorFormatsANDROID xrEnumerateCubemapLightingColorFormatsANDROID; // Created previously.

XrSystemCubemapLightEstimationPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID};
XrSystemProperties base = {.type = XR_TYPE_SYSTEM_PROPERTIES,
                           .next = &props};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));
if (!props.supportsCubemapLightEstimation) {
   // Cubemap light estimation is not supported
}

uint32_t cubemapResolution = 0;
std::vector<uint32_t> supportedCubemapResolutions;
uint32_t resolutionCount;
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
  instance, systemId, 0, &resolutionCount, nullptr));
supportedCubemapResolutions.resize(resolutionCount);
if (resolutionCount == 0) {
  // No cubemap lighting supported
} else {
  CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
    instance, systemId, 0, &resolutionCount, supportedCubemapResolutions.data()));
  cubemapResolution = supportedCubemapResolutions[0];
}

uint32_t pixelCount = cubemapResolution * cubemapResolution;

XrCubemapLightingColorFormatANDROID colorFormat;
std::vector<XrCubemapLightingColorFormatANDROID> supportedColorFormats;
uint32_t colorFormatCount;
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
  instance, systemId, 0, &colorFormatCount, nullptr));
supportedColorFormats.resize(colorFormatCount);
if (colorFormatCount == 0) {
  // No supported color formats for cubemap lighting. Cannot use cubemap
  // light estimation.
} else {
  CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
    instance, systemId, 0, &colorFormatCount, supportedColorFormats.data()));
  colorFormat = supportedColorFormats[0];
}

uint32_t pixelSize = 0;
switch (colorFormat) {
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID:
    pixelSize = 3 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(uint16_t);
    break;
  default:
    // Should not happen since the color format was validated previously.
    break;
}

uint32_t perFaceImageBufferSize = pixelCount * pixelSize;

XrLightEstimatorANDROID estimator;
XrCubemapLightEstimatorCreateInfoANDROID cubemapCreateInfo = {
    .type = XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .cubemapResolution = cubemapResolution,
    .colorFormat = colorFormat,
    .reproject = XR_TRUE
};
XrLightEstimatorCreateInfoANDROID basicCreateInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .next = &cubemapCreateInfo};
CHK_XR(xrCreateLightEstimatorANDROID(session, &basicCreateInfo, &estimator));

std::vector<uint8_t> cubemapBuffer(perFaceImageBufferSize * 6); // 6 faces * perFaceImageBufferSize

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

XrCubemapLightingDataANDROID cubemap = {
    .type = XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID,
    .next = nullptr,
    .imageBufferSize = perFaceImageBufferSize,
    .imageBufferRight = cubemapBuffer.data() + 0 * perFaceImageBufferSize,
    .imageBufferLeft = cubemapBuffer.data() + 1 * perFaceImageBufferSize,
    .imageBufferTop = cubemapBuffer.data() + 2 * perFaceImageBufferSize,
    .imageBufferBottom = cubemapBuffer.data() + 3 * perFaceImageBufferSize,
    .imageBufferFront = cubemapBuffer.data() + 4 * perFaceImageBufferSize,
    .imageBufferBack = cubemapBuffer.data() + 5 * perFaceImageBufferSize,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
    .next = &cubemap,
};

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

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

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 cubemap, directionalLight, totalSh, ambientSh, and
  // ambientLight if each struct has a valid state field

  if (cubemap.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
    // use cubemap
    if (cubemapCreateInfo.reproject == XR_TRUE) {
      XrQuaternionf identityQuaternion = {0.0f, 0.0f, 0.0f, 1.0f};
      assert(memcmp(&cubemap.rotation, &identityQuaternion, sizeof(XrQuaternionf)) == 0);
    }
  }
}

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

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
  • XR_ANDROID_light_estimation_cubemap_SPEC_VERSION
  • Extension de XrStructureType :

    • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
    • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problèmes

L'historique des versions

  • Révision 1, 05/12/2025 (Salar Khan)

    • Description initiale de l'extension