Estensione OpenXR XR_ANDROID_light_estimation

Stringa del nome

XR_ANDROID_light_estimation

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

701

Revisione

1

Dipendenze da estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-01-17

Stato IP

Nessuna rivendicazione di proprietà intellettuale 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 per il rendering degli oggetti virtuali in modo che siano illuminati nelle stesse condizioni della scena in cui sono posizionati.

Ispezionare la funzionalità del sistema

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

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • supportsLightEstimation è un XrBool32, che indica se il sistema attuale 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)

Crea un handle per lo strumento di stima della luce

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

L'handle XrLightEstimatorANDROID rappresenta uno strumento di stima della luce. Questo handle può essere utilizzato per accedere alle informazioni sulla 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 uno strumento di stima della luce.

L'handle dell'estimator di luce restituito può essere utilizzato successivamente nelle chiamate API. Se un'applicazione vuole indicare al runtime che ha terminato l'accesso ai dati di stima della luce, deve eliminare 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 per creare un handle XrLightEstimatorANDROID. 

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.

Utilizzo valido (implicito)

La funzione xrDestroyLightEstimatorANDROID rilascia estimator e tutte le risorse sottostanti. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descrizioni dei parametri

Utilizzo valido (implicito)

Thread Safety

  • L'accesso a estimator e a tutti gli 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 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 è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • space è XrSpace che definisce lo spazio di riferimento in cui vengono espressi la direzione della luce restituita e la rotazione degli armonici sferici e della cubemap.
  • time è il XrTime che descrive l'ora in cui l'applicazione vuole eseguire una query sulla stima della luce.

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 cubemap 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 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 è l'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 cubemap. Tieni presente che si tratta di HDR, quindi i valori float possono essere maggiori di 1.0.
  • cubemapLeftImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato sinistro della cubemap. Tieni presente che si tratta di HDR, quindi i valori float possono essere maggiori di 1.0.
  • cubemapTopImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato superiore della cubemap. Tieni presente che si tratta di HDR, quindi i valori float possono essere maggiori di 1.0.
  • cubemapBottomImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato inferiore della cubemap. Tieni presente che si tratta di HDR, quindi i valori float possono essere maggiori di 1.0.
  • cubemapFrontImage è un float* che rappresenta il buffer R32G32B32_SFLOAT del lato anteriore della cubemap. Tieni presente che si tratta di HDR, quindi i valori float possono essere maggiori di 1.0.
  • resolution è un uint32_t che rappresenta la larghezza e l'altezza dell'immagine di ogni lato della cubemap.
  • rotation è un XrQuaternionf che rappresenta la rotazione della cubemap.
  • centerExposureTime è un XrTime che rappresenta il momento in cui è stata acquisita la cubemap. Utile per l'interpolazione tra cubemap.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_light_estimation deve essere abilitata 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 float valido
  • cubemapLeftImage deve essere un puntatore a un valore float valido
  • cubemapTopImage deve essere un puntatore a un valore float valido
  • cubemapBottomImage deve essere un puntatore a un valore float valido
  • cubemapFrontImage deve essere un puntatore a un valore float valido
  • cubemapBackImage deve essere un puntatore a un valore float 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

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Le strutture valide sono XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID, e XrDirectionalLightANDROID.
  • state è XrLightEstimateStateANDROID che rappresenta lo stato della stima della luce.
  • intensity è un XrVector3 che rappresenta l'intensità della luce ambientale. Ogni componente del vettore corrisponde ai canali rosso, verde e blu.
  • colorCorrection è un XrVector3 con valori nello spazio gamma. Moltiplica componente per componente il colore del rendering corretto in base alla gamma con questi valori.

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 richiesto 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 armonici sferici rappresentano la funzione di radianza della luce ambientale, inclusa la contribuzione della luce principale.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

I coefficienti armonici sferici rappresentano la funzione di radianza della luce ambientale, escluso 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 quantità possibili 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 è 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 per la cubemap dell'illuminazione ambientale
  • Revisione 1, 16/09/2024 (Cairn Overturf)
    • Descrizione iniziale dell'estensione

OpenXR™ e il logo OpenXR sono marchi di proprietà di The Khronos Group Inc. e sono registrati come marchi in Cina, nell'Unione Europea, in Giappone e nel Regno Unito.