XR_ANDROID_light_estimation_cubemap

Stringa del nome

XR_ANDROID_light_estimation_cubemap

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

722

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

XR_ANDROID_light_estimation

Data ultima modifica

2025-08-06

Stato IP

Nessuna rivendicazione di proprietà intellettuale 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 cubemap, 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, tranne per il fatto che XrCubemapLightEstimatorCreateInfoANDROID deve essere concatenato a XrLightEstimatorCreateInfoANDROID durante la creazione dell'handle dell'estimator della luce.

Ispezionare la funzionalità del sistema

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

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
• supportsCubemapLightEstimation è un XrBool32 che indica se il sistema attuale supporta la stima della luce cubemap.

Un'applicazione può verificare se il sistema è in grado di supportare la stima della luce cubemap 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_cubemap deve essere attivata prima di utilizzare XrSystemCubemapLightEstimationPropertiesANDROID
• type deve essere XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

Recupero delle 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 è il XrSystemId recuperato in precedenza da xrGetSystem per cui ottenere le risoluzioni cubemap supportate.
• resolutionCapacityInput è un uint32_t che indica il numero massimo di elementi che possono essere archiviati nell'array resolutions.
• resolutionCountOutput è un puntatore a un uint32_t impostato dal runtime che indica il numero di elementi scritti nell'array resolutions dal runtime.
• resolutions è un array di uint32_t che viene compilato dal runtime con le risoluzioni cubemap supportate.

La risoluzione di una cubemap indica la larghezza e l'altezza di ogni faccia della cubemap in pixel. Idioma a due chiamate L'applicazione può quindi scegliere di utilizzare una delle risoluzioni supportate in XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution durante la creazione dell'handle dell'estimator di luce. L'applicazione deve allocare la quantità appropriata di memoria per i membri del buffer delle immagini di XrCubemapLightingDataANDROID in base alla risoluzione scelta e al formato del colore.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_light_estimation_cubemap deve essere attivata prima di chiamare xrEnumerateCubemapLightingResolutionsANDROID
• instance deve essere un handle XrInstance valido
• resolutionCountOutput deve essere un puntatore a un valore uint32_t
• Se resolutionCapacityInput non è 0 , resolutions deve essere un puntatore a un array di valori resolutionCapacityInput uint32_t

Codici di ritorno

Operazione riuscita

• XR_SUCCESS

Errore

• 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

Ottenere i formati di colore cubemap supportati

L'enumerazione XrCubemapLightingColorFormatANDROID identifica per il runtime il formato del colore dell'illuminazione 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 di 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 di 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 di colore con 4 canali in cui ogni canale è un valore a 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 è il XrSystemId recuperato in precedenza da xrGetSystem per cui ottenere le risoluzioni cubemap supportate.
• colorFormatCapacityInput è un uint32_t che indica il numero massimo di elementi che possono essere archiviati nell'array colorFormats.
• colorFormatCountOutput è un puntatore a un uint32_t impostato dal runtime che indica il numero di elementi scritti nell'array colorFormats dal runtime.
• colorFormats è un array di XrCubemapLightingColorFormatANDROID che viene compilato dal runtime con i formati di colore cubemap supportati.

Idioma a due chiamate L'applicazione può quindi scegliere di utilizzare uno dei formati di colore supportati in XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat durante la creazione dell'handle dell'estimator della luce. L'applicazione deve allocare la quantità appropriata di memoria per i membri del buffer delle immagini di XrCubemapLightingDataANDROID in base al formato colore scelto.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_light_estimation_cubemap deve essere attivata prima di chiamare xrEnumerateCubemapLightingColorFormatsANDROID
• instance deve essere un handle XrInstance valido
• colorFormatCountOutput deve essere un puntatore a un valore uint32_t
• Se colorFormatCapacityInput non è 0 , colorFormats deve essere un puntatore a un array di valori colorFormatCapacityInput XrCubemapLightingColorFormatANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS

Errore

• 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

Crea un handle per lo strumento di stima della luce cubemap

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 è NULL o un puntatore alla struttura successiva in una catena di strutture.
• cubemapResolution è un uint32_t che indica la risoluzione dell'illuminazione cubemap da utilizzare.
• colorFormat è un XrCubemapLightingColorFormatANDROID che indica il formato del colore dei dati di illuminazione della cubemap da utilizzare.
• reproject è un XrBool32 che indica se l'illuminazione 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 cubemap. Il membro XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution 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_cubemap deve essere attivata prima di utilizzare XrCubemapLightEstimatorCreateInfoANDROID
• type deve essere XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• colorFormat deve essere un valore XrCubemapLightingColorFormatANDROID valido

Stime della luce cubemap

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 è NULL o un puntatore alla struttura successiva in una catena di strutture. Le strutture valide sono XrAmbientLightANDROID , XrSphericalHarmonicsANDROID , XrDirectionalLightANDROID .
• state è XrLightEstimateStateANDROID che rappresenta lo stato della stima della luce.
• imageBufferSize è un uint32_t che indica la dimensione in byte di ogni buffer di immagine del volto nel cubemap.
• imageBufferRight è un buffer uint8_t contenente l'immagine della faccia destra della cubemap.
• imageBufferLeft è un buffer uint8_t contenente l'immagine della faccia sinistra della cubemap.
• imageBufferTop è un buffer uint8_t contenente l'immagine della faccia superiore della cubemap.
• imageBufferBottom è un buffer uint8_t contenente l'immagine della faccia inferiore della cubemap.
• imageBufferFront è un buffer uint8_t contenente l'immagine della faccia anteriore della cubemap.
• imageBufferBack è un buffer uint8_t contenente l'immagine della faccia posteriore della cubemap.
• rotation è un XrQuaternionf che indica la rotazione della cubemap.
• centerExposureTime è un XrTime che indica l'ora in cui è stata acquisita la cubemap.

Questa struttura può essere concatenata a XrLightEstimateANDROID . Il runtime deve compilare questa struttura in xrGetLightEstimateANDROID solo se è stato utilizzato XrCubemapLightEstimatorCreateInfoANDROID per creare l'handle dell'estimator di luce. L'applicazione deve allocare la quantità di memoria appropriata per i buffer delle immagini, che dipende dai valori impostati in XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution e XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat durante la creazione dell'handle dell'estimator della luce. L'applicazione deve impostare XrCubemapLightingDataANDROID :: imageBufferSize sulla capacità di ogni buffer di immagini del volto in byte. Se l'applicazione non utilizza la stima della luce cubemap o se XrCubemapLightingDataANDROID :: imageBufferSize non è sufficientemente 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 il set di applicazioni XrCubemapLightEstimatorCreateInfoANDROID :: reproject è impostato su XR_TRUE durante la creazione dell'handle dell'estimator della luce, il runtime deve impostare XrCubemapLightingDataANDROID :: rotation sulla rotazione dell'identità e assicurarsi che la cubemap ruotata interna venga riproiettata sulle facce di una cubemap dell'identità nello spazio di base dell'applicazione.

Il layout della cubemap di illuminazione è lo stesso del layout della cubemap OpenGL, come mostrato nella seguente immagine.

Figura 24. Layout della mappa cubica.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_light_estimation_cubemap deve essere attivata prima di utilizzare XrCubemapLightingDataANDROID
• type deve essere XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• state deve essere un valore XrLightEstimateStateANDROID valido
• imageBufferRight deve essere un puntatore a un array di valori imageBufferSize uint8_t
• imageBufferLeft deve essere un puntatore a un array di valori imageBufferSize uint8_t
• imageBufferTop deve essere un puntatore a un array di valori imageBufferSize uint8_t
• imageBufferBottom deve essere un puntatore a un array di valori imageBufferSize uint8_t
• imageBufferFront deve essere un puntatore a un array di valori imageBufferSize uint8_t
• imageBufferBack deve essere un puntatore a un array di valori imageBufferSize uint8_t
• Il parametro imageBufferSize deve essere maggiore di 0

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

• xrEnumerateCubemapLightingColorFormatsANDROID
• xrEnumerateCubemapLightingResolutionsANDROID

Nuove strutture

• Estensione di XrLightEstimateANDROID :

  • XrCubemapLightingDataANDROID

• Estensione di XrLightEstimatorCreateInfoANDROID :

  • XrCubemapLightEstimatorCreateInfoANDROID

• Estensione di XrSystemProperties :

  • XrSystemCubemapLightEstimationPropertiesANDROID

Nuovi enum

• XrCubemapLightingColorFormatANDROID

Nuove costanti enum

• XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
• XR_ANDROID_light_estimation_cubemap_SPEC_VERSION

• Estensione di XrStructureType :

  • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
  • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problemi

Cronologia delle versioni

• Revisione 1, 05/12/2025 (Salar Khan)

  • Descrizione iniziale dell'estensione