XR_ANDROID_light_estimation

Stringa del nome

XR_ANDROID_light_estimation

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

701

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-03-13

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. L'applicazione può utilizzare queste informazioni per illuminare gli oggetti virtuali nelle stesse condizioni della scena reale in cui sono posizionati.

Autorizzazioni

Le applicazioni Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel loro manifest, in quanto questa estensione espone informazioni sull'illuminazione dell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE è considerata pericolosa. L'applicazione deve richiedere l'autorizzazione in fase di runtime per utilizzare queste funzioni:

(livello di protezione: pericoloso)

Ispezionare la funzionalità del sistema

La struttura XrSystemLightEstimationPropertiesANDROID è definita come:

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 e solo se un runtime restituisce XR_FALSE per supportsLightEstimation , il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateLightEstimatorANDROID .

Utilizzo valido (implicito)

Crea un handle per lo strumento di stima della luce

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

I dati di stima della luce vengono generati dal runtime e condivisi con l'applicazione utilizzando l'handle XrLightEstimatorANDROID.

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

  • session è la XrSession che crea lo strumento di stima della luce.
  • createInfo è un puntatore a una struttura XrLightEstimatorCreateInfoANDROID contenente i parametri da utilizzare per creare lo strumento di stima della luce.
  • outHandle è un puntatore a un handle in cui viene restituito l'oggetto XrLightEstimatorANDROID creato.

L'applicazione utilizza la funzione xrCreateLightEstimatorANDROID per creare uno strumento di stima della luce.

  • Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED se il sistema non supporta la stima della luce.
  • Il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT se le autorizzazioni richieste non sono state concesse all'app chiamante.

Se un'applicazione vuole indicare al runtime che ha terminato l'accesso ai dati di stima della luce, deve eliminare l'handle tramite xrDestroyLightEstimatorANDROID .

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

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

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

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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 è definita come:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descrizioni dei parametri

La funzione xrDestroyLightEstimatorANDROID rilascia estimator e tutte le risorse sottostanti.

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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrLightEstimateGetInfoANDROID è definita come:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 è l'XrSpace che definisce lo spazio di riferimento in cui sono espressi la direzione della luce e le armoniche sferiche restituite.
  • time è il XrTime che descrive l'ora in cui l'applicazione vuole eseguire una query per la 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 ogni struct di stima della luce, se state è XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, tutti gli altri campi dello struct sono arbitrari, il che significa che i loro valori non sono definiti.

Per ottenere informazioni sulla stima della luce per la luce ambientale, le armoniche sferiche e la luce direzionale primaria, le applicazioni possono concatenare istanze delle seguenti strutture, XrAmbientLightANDROID , XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID rispettivamente a XrLightEstimateANDROID :: next .

Utilizzo valido (implicito)

La struttura XrAmbientLightANDROID contiene dati di stima della 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 includono XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID .
  • state è XrLightEstimateStateANDROID che rappresenta lo stato della stima della luce.
  • intensity è un XrVector3f che rappresenta l'intensità della luce ambientale. Ogni componente del vettore corrisponde rispettivamente ai canali rosso, verde e blu.

  • colorCorrection è un XrVector3f con valori nello spazio gamma. Se il rendering viene eseguito nello spazio colore gamma, moltiplica i valori componente per componente rispetto al colore finale calcolato dopo il rendering. Se il rendering viene eseguito nello spazio lineare, converti prima i valori nello spazio lineare elevandoli alla potenza di 2,2, quindi moltiplica i componenti per il colore finale calcolato dopo il rendering.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

coefficients devono essere utilizzati in una funzione speciale che accetta una direzione come input e restituisce il colore della luce proveniente da quella direzione. Maggiori dettagli sono disponibili in questo documento .

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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

I valori di enumerazione hanno i seguenti significati:

Descrizione enum

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

I coefficienti armonici sferici rappresentano la funzione di radianza della luce ambientale, escluso il contributo della luce principale.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

I coefficienti armonici sferici rappresentano la funzione di radianza della luce ambientale, incluso il contributo della luce principale.

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 XrLightEstimateStateANDROID indica lo stato della stima della luce restituita dal runtime.

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

I valori di enumerazione hanno i seguenti significati:

Descrizione enum

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.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

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

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

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Estensione di XrStructureType :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 1, 16/09/2024 (Cairn Overturf)

    • Descrizione iniziale dell'estensione