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

2024-09-18

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Panoramica

Questa estensione consente all'applicazione di richiedere dati che rappresentano l'illuminazione dell'ambiente reale intorno all'auricolare. 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 all'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 le 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 sono espressi la direzione della luce restituita e gli armonici sferici.
  • 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 luce ambientale, le armoniche sferiche e la luce direzionale principale, le applicazioni possono concatenare istanze delle seguenti strutture, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID rispettivamente su XrLightEstimateANDROID::next.

Utilizzo valido (implicito)

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 è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Le strutture valide sono XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID.
  • state è l'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 per componente il colore del rendering con correzione 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 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 intensità luminosa dell'ambiente, escludendo il contributo della luce principale.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

I coefficienti delle armoniche sferiche rappresentano la funzione di intensità luminosa dell'ambiente, 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,
};

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 directionalLight, totalSh, ambientSh, ambientLight 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

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

  • Revisione 1, 16/09/2024 (Cairn Overturf)
    • Descrizione iniziale dell'estensione