XR_ANDROID_light_estimation_cubemap
Name String
XR_ANDROID_light_estimation_cubemap
Tipo di estensione
Estensione dell'istanza
Numero di interno registrato
722
Revisione
1
Stato della ratifica
Non ratificato
Dipendenze di estensioni e versioni
XR_ANDROID_light_estimation
Data ultima modifica
2025-08-06
Stato IP
Nessuna rivendicazione di PI nota.
Collaboratori
Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google
Panoramica
Questa estensione si basa sull'estensione XR_ANDROID_light_estimation di base. Aggiunge il supporto per ottenere stime dell'illuminazione della mappa cubica, che fornisce stime più dettagliate sull'illuminazione nell'ambiente fisico.
Nota
Il meccanismo per ottenere i dati di stima della luce è lo stesso dell'estensione di base, ad eccezione del fatto che XrCubemapLightEstimatorCreateInfoANDROID deve essere concatenato a XrLightEstimatorCreateInfoANDROID durante la creazione dell'handle dello strumento di stima della luce.
Ispeziona la funzionalità del sistema
typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.supportsCubemapLightEstimationè unXrBool32che indica se il sistema attuale supporta la stima della luce della mappa cubica.
Un'applicazione può verificare se il sistema è in grado di supportare la stima della luce della mappa cubica estendendo XrSystemProperties con la struttura XrSystemCubemapLightEstimationPropertiesANDROID quando chiama xrGetSystemProperties .
Se il runtime restituisce XR_FALSE per supportsCubemapLightEstimation e XrCubemapLightEstimatorCreateInfoANDROID è stato concatenato a XrLightEstimatorCreateInfoANDROID , il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateLightEstimatorANDROID .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_light_estimation_cubemapdeve essere attivata prima di utilizzare XrSystemCubemapLightEstimationPropertiesANDROID -
typedeve essereXR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture
Ottenere le risoluzioni cubemap supportate
XrResult xrEnumerateCubemapLightingResolutionsANDROID(
XrInstance instance,
XrSystemId systemId,
uint32_t resolutionCapacityInput,
uint32_t* resolutionCountOutput,
uint32_t* resolutions);
Descrizioni dei parametri
instanceè un XrInstance creato in precedenza.systemIdè l'XrSystemIdrecuperato in precedenza da xrGetSystem per cui ottenere le risoluzioni cubemap supportate.resolutionCapacityInputè unuint32_tche indica il numero massimo di elementi che possono essere archiviati nell'arrayresolutions.resolutionCountOutputè un puntatore a unuint32_timpostato dal runtime che indica il numero di elementi scritti nell'arrayresolutionsdal runtime.resolutionsè un array diuint32_tche viene compilato dal runtime con le risoluzioni della mappa cubica supportate.
La risoluzione di una mappa cubica indica la larghezza e l'altezza di ogni faccia della mappa cubica in pixel. Idiom di chiamata 2 L'applicazione può quindi scegliere di utilizzare una delle risoluzioni supportate in XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution durante la creazione dell'handle dello strumento di stima della luce. L'applicazione deve allocare la quantità di memoria appropriata per i membri del buffer di immagini di XrCubemapLightingDataANDROID in base alla risoluzione scelta e al formato del colore.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_light_estimation_cubemapdeve essere abilitata prima di chiamare xrEnumerateCubemapLightingResolutionsANDROID -
instancedeve essere un handle XrInstance valido -
resolutionCountOutputdeve essere un puntatore a un valoreuint32_t - Se
resolutionCapacityInputnon è0,resolutionsdeve essere un puntatore a un array di valoriresolutionCapacityInputuint32_t
Codici di risposta
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
Recupero dei formati di colore della mappa cubica supportati
L'enumerazione XrCubemapLightingColorFormatANDROID identifica per il runtime il formato colore dell'illuminazione della cubemap da utilizzare.
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;
Gli enum hanno i seguenti significati:
Descrizione enum
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID
Un formato colore con 3 canali in cui ogni canale è un valore in virgola mobile a 32 bit.
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID
Un formato colore con 4 canali in cui ogni canale è un valore in virgola mobile a 32 bit.
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID
Un formato colore con 4 canali, in cui ogni canale è un valore in virgola mobile a 16 bit.
XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
XrInstance instance,
XrSystemId systemId,
uint32_t colorFormatCapacityInput,
uint32_t* colorFormatCountOutput,
XrCubemapLightingColorFormatANDROID* colorFormats);
Descrizioni dei parametri
instanceè un XrInstance creato in precedenza.systemIdè l'XrSystemIdrecuperato in precedenza da xrGetSystem per cui ottenere le risoluzioni cubemap supportate.colorFormatCapacityInputè unuint32_tche indica il numero massimo di elementi che possono essere archiviati nell'arraycolorFormats.colorFormatCountOutputè un puntatore a unuint32_timpostato dal runtime che indica il numero di elementi scritti nell'arraycolorFormatsdal runtime.colorFormatsè un array di XrCubemapLightingColorFormatANDROID che viene compilato dal runtime con i formati di colore della cubemap supportati.
Idiom a 2 chiamate L'applicazione può quindi scegliere di utilizzare uno dei formati di colore supportati in XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat durante la creazione dell'handle dello strumento di stima della luce. L'applicazione deve allocare la quantità di memoria appropriata per i membri del buffer di immagini di XrCubemapLightingDataANDROID in base al formato colore scelto.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_light_estimation_cubemapdeve essere attivata prima di chiamare xrEnumerateCubemapLightingColorFormatsANDROID -
instancedeve essere un handle XrInstance valido -
colorFormatCountOutputdeve essere un puntatore a un valoreuint32_t - Se
colorFormatCapacityInputnon è0,colorFormatsdeve essere un puntatore a un array di valoricolorFormatCapacityInputXrCubemapLightingColorFormatANDROID
Codici di risposta
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
Crea un handle per lo strumento di stima della luce della mappa cubica
typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t cubemapResolution;
XrCubemapLightingColorFormatANDROID colorFormat;
XrBool32 reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture.cubemapResolutionè unuint32_tche indica la risoluzione dell'illuminazione della mappa cubica da utilizzare.colorFormatè un XrCubemapLightingColorFormatANDROID che indica il formato colore dei dati di illuminazione della cubemap da utilizzare.reprojectè unXrBool32che indica se l'illuminazione della cubemap deve essere riproiettata nello spazio di base dell'applicazione.
La struttura XrCubemapLightEstimatorCreateInfoANDROID descrive le informazioni per creare un handle XrLightEstimatorANDROID in grado di fornire stime di illuminazione della mappa cubica. Il membro cubemapResolution di XrCubemapLightEstimatorCreateInfoANDROID deve essere impostato su una delle risoluzioni restituite da xrEnumerateCubemapLightingResolutionsANDROID . Il membro XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat deve essere impostato su uno dei formati di colore restituiti da xrEnumerateCubemapLightingColorFormatsANDROID . Se l'applicazione non imposta la risoluzione su una delle risoluzioni supportate o il formato colore su uno dei formati colore supportati, il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateLightEstimatorANDROID .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_light_estimation_cubemapdeve essere attivata prima di utilizzare XrCubemapLightEstimatorCreateInfoANDROID -
typedeve essereXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
colorFormatdeve essere un valore XrCubemapLightingColorFormatANDROID valido
Stime della luce della mappa cubica
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;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Le strutture valide sono XrAmbientLightANDROID , XrSphericalHarmonicsANDROID , XrDirectionalLightANDROID .stateè l'oggetto XrLightEstimateStateANDROID che rappresenta lo stato della stima della luce.imageBufferSizeè unuint32_tche indica la dimensione in byte di ogni buffer di immagini delle facce nella mappa cubica.imageBufferRightè un bufferuint8_tcontenente l'immagine della faccia destra della mappa cubica.imageBufferLeftè un bufferuint8_tcontenente l'immagine della faccia sinistra della mappa cubica.imageBufferTopè un bufferuint8_tcontenente l'immagine della faccia superiore della mappa cubica.imageBufferBottomè un bufferuint8_tcontenente l'immagine della faccia inferiore della mappa cubica.imageBufferFrontè un bufferuint8_tcontenente l'immagine della faccia anteriore della mappa cubica.imageBufferBackè un bufferuint8_tcontenente l'immagine della faccia posteriore della mappa cubica.rotationè un XrQuaternionf che indica la rotazione della mappa cubica.centerExposureTimeè unXrTimeche indica l'ora in cui è stata acquisita la mappa cubica.
Questa struttura può essere concatenata a XrLightEstimateANDROID . Il runtime deve compilare questa struttura in xrGetLightEstimateANDROID solo se XrCubemapLightEstimatorCreateInfoANDROID è stato utilizzato per creare l'handle dello strumento di stima della luce. L'applicazione deve allocare la quantità di memoria appropriata per i buffer di immagini, che dipende dai valori impostati in XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution e XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat durante la creazione dell'handle dello strumento di stima della luce. L'applicazione deve impostare XrCubemapLightingDataANDROID :: imageBufferSize sulla capacità di ogni buffer di immagini delle facce in byte. Se l'applicazione non utilizza la stima della luce della cubemap o se XrCubemapLightingDataANDROID :: imageBufferSize non è abbastanza grande per consentire al runtime di compilare i buffer delle immagini, il runtime deve impostare XrCubemapLightingDataANDROID :: state su XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .
Se l'applicazione ha impostato XrCubemapLightEstimatorCreateInfoANDROID :: reproject su XR_TRUE durante la creazione dell'handle dello strumento di stima della luce, il runtime deve impostare XrCubemapLightingDataANDROID :: rotation sulla rotazione dell'identità e assicurarsi che la mappa cubica ruotata interna venga riproiettata sulle facce di una mappa cubica dell'identità nello spazio di base dell'applicazione.
Il layout della mappa cubica di illuminazione è lo stesso del layout della mappa cubica OpenGL, come mostrato nell'immagine seguente.
Figura 31. Layout della mappa cubica.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_light_estimation_cubemapdeve essere attivata prima di utilizzare XrCubemapLightingDataANDROID -
typedeve essereXR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
statedeve essere un valore XrLightEstimateStateANDROID valido -
imageBufferRightdeve essere un puntatore a un array di valoriimageBufferSizeuint8_t -
imageBufferLeftdeve essere un puntatore a un array di valoriimageBufferSizeuint8_t -
imageBufferTopdeve essere un puntatore a un array di valoriimageBufferSizeuint8_t -
imageBufferBottomdeve essere un puntatore a un array di valoriimageBufferSizeuint8_t -
imageBufferFrontdeve essere un puntatore a un array di valoriimageBufferSizeuint8_t -
imageBufferBackdeve essere un puntatore a un array di valoriimageBufferSizeuint8_t - Il parametro
imageBufferSizedeve essere maggiore di0
Codice di esempio per la stima della luce
Il seguente codice di esempio mostra come ottenere tutte le possibili quantità di stima della luce dal runtime
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));
Nuovi comandi
Nuove strutture
Estensione di XrLightEstimateANDROID :
Estensione di XrLightEstimatorCreateInfoANDROID :
Estensione di XrSystemProperties :
Nuovi enum
Nuove costanti enum
XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAMEXR_ANDROID_light_estimation_cubemap_SPEC_VERSIONEstensione di XrStructureType :
XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROIDXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID
Problemi
Cronologia delle versioni
Revisione 1, 5 dicembre 2025 (Salar Khan)
- Descrizione iniziale dell'estensione