Estensione OpenXR XR_ANDROID_light_estimation

Stringa del nome

XR_ANDROID_light_estimation

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

701

Revisione

1

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-01-17

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Salar Khan, Google

Scott Chung, Google

Panoramica

Questa estensione consente all'applicazione di richiedere dati che rappresentano l'illuminazione dell'ambiente reale intorno al visore. Queste informazioni possono essere utilizzate durante il rendering di oggetti virtuali per illuminarli nelle stesse condizioni della scena in cui sono posizionati.

Controlla la funzionalità del sistema

Un'applicazione può verificare se il sistema supporta la stima della luce concatenando una struttura XrSystemLightEstimationPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties. 

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

Descrizioni dei membri

  • type è il 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.
  • supportsLightEstimation è un XrBool32 che indica se il sistema corrente supporta la stima della luce.

Un'applicazione può verificare se il sistema è in grado di supportare la stima della luce estendendo XrSystemProperties con la struttura XrSystemLightEstimationPropertiesANDROID quando chiama xrGetSystemProperties.

Se il sistema non è in grado di supportare la stima della luce, restituirà XR_FALSE per supportsLightEstimation e XR_ERROR_FEATURE_UNSUPPORTED da xrCreateLightEstimatorANDROID.

Utilizzo valido (implicito)

Creare un handle per l'estimatore della luce

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

L'handle XrLightEstimatorANDROID rappresenta un estimatore della luce. Questo handle può essere utilizzato per accedere alle informazioni di stima della luce utilizzando altre funzioni di questa estensione.

La funzione xrCreateLightEstimatorANDROID è definita come: 

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrCreateLightEstimatorANDROID per creare un estimatore della luce.

L'handle dell'estimatore della luce restituito potrebbe essere utilizzato successivamente nelle chiamate API. Se un'applicazione vuole indicare al runtime che ha terminato di accedere ai dati di stima della luce, deve distruggere l'handle utilizzando xrDestroyLightEstimatorANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

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

La struttura XrLightEstimatorCreateInfoANDROID descrive le informazioni necessarie per creare un handle XrLightEstimatorANDROID. 

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

Descrizioni dei membri

  • type è il 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.

Utilizzo valido (implicito)

La funzione xrDestroyLightEstimatorANDROID rilascia estimator e eventuali risorse di base. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descrizioni dei parametri

Utilizzo valido (implicito)

Coerenza di thread

  • L'accesso a estimator e a eventuali handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Accedere ai dati di stima della luce

La funzione xrGetLightEstimateANDROID è definita come: 

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Descrizioni dei parametri

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_TIME_INVALID

Un messaggio XrLightEstimateGetInfoANDROID descrive le informazioni necessarie per ottenere i dati di stima della luce. 

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • space è lo spazio XrSpace che definisce lo spazio di riferimento in cui vengono espressi la direzione della luce restituita, gli armonici sferici e la rotazione della mappa cubica.
  • time è il XrTime che descrive il momento in cui l'applicazione vuole eseguire una query sull'illuminazione stimata.

Utilizzo valido (implicito)

La struttura XrLightEstimateANDROID contiene i dati di stima della luce. 

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

Descrizioni dei membri

Per ottenere informazioni sulla stima della luce per la mappa cubo dell'illuminazione ambientale, la luce ambientale, le armoniche sferiche e la luce direzionale principale, le applicazioni possono concatenare istanze delle seguenti strutture, XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID, rispettivamente su XrLightEstimateANDROID::next.

Utilizzo valido (implicito)

La struttura XrEnvironmentLightingCubemapANDROID contiene dati di stima della luce in un formato cubemap relativi all'illuminazione dell'ambiente della scena. 

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Le strutture valide sono XrSphericalHarmonicsANDROID, XrAmbientLightANDROID e XrDirectionalLightANDROID.
  • state è XrLightEstimateStateANDROID che rappresenta lo stato della stima della luce.
  • cubemapRightImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato destro della mappa cubica. Tieni presente che si tratta di HDR, quindi i valori in virgola mobile possono essere superiori a 1,0.
  • cubemapLeftImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato sinistro della mappa cubica. Tieni presente che si tratta di HDR, quindi i valori in virgola mobile possono essere superiori a 1,0.
  • cubemapTopImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato superiore della mappa cubica. Tieni presente che si tratta di HDR, quindi i valori in virgola mobile possono essere superiori a 1,0.
  • cubemapBottomImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato inferiore della mappa cubica. Tieni presente che si tratta di HDR, quindi i valori in virgola mobile possono essere superiori a 1,0.
  • cubemapFrontImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato anteriore della mappa cubica. Tieni presente che si tratta di HDR, quindi i valori in virgola mobile possono essere superiori a 1,0.
  • resolution è un uint32_t che rappresenta la larghezza e l'altezza dell'immagine di ogni lato della mappa cubica. Tieni presente che si tratta di HDR, quindi i valori in virgola mobile possono essere maggiori di 1,0.
  • rotation è un XrQuaternionf che rappresenta la rotazione della mappa cubica.
  • centerExposureTime è un XrTime che rappresenta il momento in cui è stata acquisita la mappa cubica. Utile per l'interpolazione tra cubemap.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_light_estimation deve essere attivata prima di utilizzare XrEnvironmentLightingCubemapANDROID
  • type deve essere XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • state deve essere un valore XrLightEstimateStateANDROID valido
  • cubemapRightImage deve essere un puntatore a un valore a virgola mobile valido
  • cubemapLeftImage deve essere un puntatore a un valore a virgola mobile valido
  • cubemapTopImage deve essere un puntatore a un valore a virgola mobile valido
  • cubemapBottomImage deve essere un puntatore a un valore a virgola mobile valido
  • cubemapFrontImage deve essere un puntatore a un valore a virgola mobile valido
  • cubemapBackImage deve essere un puntatore a un valore a virgola mobile valido

La struttura XrAmbientLightANDROID contiene dati di stima della luce relativi alla luce ambientale nella scena. 

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

Descrizioni dei membri

Utilizzo valido (implicito)

La struttura XrSphericalHarmonicsANDROID contiene armoniche sferiche che rappresentano l'illuminazione della scena. 

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

Descrizioni dei membri

Utilizzo valido (implicito)

La struttura XrDirectionalLightANDROID contiene i dati di stima della luce. 

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

Descrizioni dei membri

Utilizzo valido (implicito)

L'enumerazione XrSphericalHarmonicsKindANDROID identifica per il runtime il tipo di armoniche sferiche richieste dall'applicazione. 

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

Gli enum hanno i seguenti significati:

Enum

Descrizione

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

I coefficienti delle armoniche sferiche rappresentano la funzione di irraggiamento della luce ambientale, escludendo il contributo della luce principale.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

I coefficienti delle armoniche sferiche rappresentano la funzione di irraggiamento della luce ambientale, incluso il contributo della luce principale.

L'enumerazione XrLightEstimateStateANDROID identifica per il runtime il tipo di armoniche sferiche richieste dall'applicazione. 

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

Gli enum hanno i seguenti significati:

Enum

Descrizione

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

La stima della luce è valida

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

La stima della luce non è valida

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
XrSpace appSpace;   // 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 totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

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

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


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &lightingCubemap,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, if each
  // struct has a valid state field
}

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

Nuovi tipi di oggetti

  • XrLightEstimator

L'enumerazione XrObjectType è estesa con:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

L'enumerazione XrStructureType è stata estesa con:

  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_AMBIENT_LIGHT_ANDROID
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

  • Revisione 2, 17/01/2025 (Salar Khan)
    • È stato aggiunto il supporto della cubemap per l'illuminazione ambiente
  • Revisione 1, 16-09-2024 (Cairn Overturf)
    • Descrizione iniziale dell'estensione