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
typeest le XrStructureType de cette structure.nextestNULLou 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.supportsCubemapLightEstimationest unXrBool32, 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)
- L'extension
XR_ANDROID_light_estimation_cubemapdoit être activée avant d'utiliser XrSystemCubemapLightEstimationPropertiesANDROID. -
typedoit êtreXR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures
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
instanceest une XrInstance créée précédemment.systemIdest leXrSystemIdrécupéré précédemment par xrGetSystem pour lequel obtenir les résolutions de cubemap compatibles.resolutionCapacityInputest unuint32_tindiquant le nombre maximal d'éléments pouvant être stockés dans le tableauresolutions.resolutionCountOutputest un pointeur vers unuint32_tdéfini par l'environnement d'exécution, qui indique le nombre d'éléments écrits dans le tableauresolutionspar l'environnement d'exécution.resolutionsest un tableau deuint32_tqui 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_cubemapdoit être activée avant d'appeler xrEnumerateCubemapLightingResolutionsANDROID. -
instancedoit être un handle XrInstance valide -
resolutionCountOutputdoit être un pointeur vers une valeuruint32_t - Si
resolutionCapacityInputn'est pas0,resolutionsdoit être un pointeur vers un tableau de valeursresolutionCapacityInputuint32_t.
Codes renvoyés
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_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
instanceest une XrInstance créée précédemment.systemIdest leXrSystemIdrécupéré précédemment par xrGetSystem pour lequel obtenir les résolutions de cubemap compatibles.colorFormatCapacityInputest unuint32_tindiquant le nombre maximal d'éléments pouvant être stockés dans le tableaucolorFormats.colorFormatCountOutputest un pointeur vers unuint32_tdéfini par l'environnement d'exécution, qui indique le nombre d'éléments écrits dans le tableaucolorFormatspar l'environnement d'exécution.colorFormatsest 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)
- L'extension
XR_ANDROID_light_estimation_cubemapdoit être activée avant d'appeler xrEnumerateCubemapLightingColorFormatsANDROID. -
instancedoit être un handle XrInstance valide -
colorFormatCountOutputdoit être un pointeur vers une valeuruint32_t - Si
colorFormatCapacityInputn'est pas0,colorFormatsdoit être un pointeur vers un tableau de valeurscolorFormatCapacityInputXrCubemapLightingColorFormatANDROID.
Codes renvoyés
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_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
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures.cubemapResolutionest unuint32_tindiquant la résolution de l'éclairage de la carte cubique à utiliser.colorFormatest un XrCubemapLightingColorFormatANDROID indiquant le format de couleur des données d'éclairage de la cubemap à utiliser.reprojectest unXrBool32indiquant 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)
- L'extension
XR_ANDROID_light_estimation_cubemapdoit être activée avant d'utiliser XrCubemapLightEstimatorCreateInfoANDROID. -
typedoit êtreXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures -
colorFormatdoit être une valeur XrCubemapLightingColorFormatANDROID valide
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
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Les structures valides sont XrAmbientLightANDROID, XrSphericalHarmonicsANDROID et XrDirectionalLightANDROID .stateest l'élément XrLightEstimateStateANDROID représentant l'état de l'estimation de la luminosité.imageBufferSizeest unuint32_tindiquant la taille en octets de chaque tampon d'image de visage dans la cubemap.imageBufferRightest un tamponuint8_tcontenant l'image de la face droite de la cubemap.imageBufferLeftest un tamponuint8_tcontenant l'image de la face gauche de la cubemap.imageBufferTopest un tamponuint8_tcontenant l'image de la face supérieure de la cubemap.imageBufferBottomest un tamponuint8_tcontenant l'image de la face inférieure de la cubemap.imageBufferFrontest un tamponuint8_tcontenant l'image de la face avant de la cubemap.imageBufferBackest un tamponuint8_tcontenant l'image de la face arrière de la cubemap.rotationest un XrQuaternionf indiquant la rotation de la cubemap.centerExposureTimeest unXrTimeindiquant 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.
Figure 31. Mise en page cubique.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_light_estimation_cubemapdoit être activée avant d'utiliser XrCubemapLightingDataANDROID. -
typedoit êtreXR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures -
statedoit être une valeur XrLightEstimateStateANDROID valide -
imageBufferRightdoit être un pointeur vers un tableau de valeursimageBufferSizeuint8_t -
imageBufferLeftdoit être un pointeur vers un tableau de valeursimageBufferSizeuint8_t -
imageBufferTopdoit être un pointeur vers un tableau de valeursimageBufferSizeuint8_t -
imageBufferBottomdoit être un pointeur vers un tableau de valeursimageBufferSizeuint8_t -
imageBufferFrontdoit être un pointeur vers un tableau de valeursimageBufferSizeuint8_t -
imageBufferBackdoit être un pointeur vers un tableau de valeursimageBufferSizeuint8_t - Le paramètre
imageBufferSizedoit ê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
Extension de XrLightEstimateANDROID :
Extension de XrLightEstimatorCreateInfoANDROID :
Extension de XrSystemProperties :
Nouvelles énumérations
Nouvelles constantes d'énumération
XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAMEXR_ANDROID_light_estimation_cubemap_SPEC_VERSIONExtension de XrStructureType :
XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROIDXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROIDXR_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