OpenXR-Erweiterung „XR_ANDROID_light_estimation“

Namensstring

XR_ANDROID_light_estimation

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

701

Revision

1

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2025-01-17

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Mitwirkende

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Salar Khan, Google

Scott Chung, Google

Übersicht

Mit dieser Erweiterung kann die Anwendung Daten anfordern, die die Beleuchtung der Umgebung um das Headset herum darstellen. Diese Informationen können beim Rendern virtueller Objekte verwendet werden, um sie unter denselben Bedingungen wie die Szene zu beleuchten, in der sie platziert sind.

Systemkapazität prüfen

Eine Anwendung kann prüfen, ob das System die Lichtschätzung unterstützt, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemLightEstimationPropertiesANDROID-Struktur an die XrSystemProperties-Struktur anhängt. 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • supportsLightEstimation ist ein XrBool32, das angibt, ob das aktuelle System die Lichtschätzung unterstützt.

Eine Anwendung kann prüfen, ob das System die Lichtschätzung unterstützt, indem sie XrSystemProperties beim Aufruf von xrGetSystemProperties um die Struktur XrSystemLightEstimationPropertiesANDROID erweitert.

Wenn das System die Lichtschätzung nicht unterstützt, wird XR_FALSE für supportsLightEstimation und XR_ERROR_FEATURE_UNSUPPORTED von xrCreateLightEstimatorANDROID zurückgegeben.

Gültige Verwendung (implizit)

Light-Estimator-Handle erstellen

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Der Handle XrLightEstimatorANDROID steht für einen Lichtempfänger. Über diesen Handle kann mit anderen Funktionen in dieser Erweiterung auf Informationen zur Lichtschätzung zugegriffen werden.

Die Funktion xrCreateLightEstimatorANDROID ist so definiert: 

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

Parameterbeschreibungen

  • session ist die XrSession, die den Licht-Estimator erstellt.
  • createInfo ist ein Verweis auf eine XrLightEstimatorCreateInfoANDROID-Struktur mit Parametern, die zum Erstellen des Lichtestellers verwendet werden.
  • outHandle ist ein Verweis auf einen Handle, über den der erstellte XrLightEstimatorANDROID zurückgegeben wird.

Die Anwendung kann die Funktion xrCreateLightEstimatorANDROID verwenden, um einen Lichtempfänger zu erstellen.

  • Wenn das System die Lichtschätzung nicht unterstützt, gibt xrCreateLightEstimatorANDROID XR_ERROR_FEATURE_UNSUPPORTED zurück.
  • xrCreateLightEstimatorANDROID gibt XR_ERROR_PERMISSION_INSUFFICIENT zurück, wenn der aufrufenden Anwendung die erforderlichen Berechtigungen nicht gewährt wurden.

Der zurückgegebene Handle für den Lichtempfänger kann in API-Aufrufen verwendet werden. Wenn eine Anwendung der Laufzeit mitteilen möchte, dass der Zugriff auf Daten zur Lichtschätzung beendet ist, muss sie den Handle mit xrDestroyLightEstimatorANDROID löschen.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrLightEstimatorCreateInfoANDROID beschreibt die Informationen zum Erstellen eines XrLightEstimatorANDROID-Handles. 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.

Gültige Verwendung (implizit)

Die Funktion xrDestroyLightEstimatorANDROID gibt die estimator und alle zugrunde liegenden Ressourcen frei. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Parameterbeschreibungen

Gültige Verwendung (implizit)

Threadsicherheit

  • Der Zugriff auf estimator und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Auf Daten zur Lichtschätzung zugreifen

Die Funktion xrGetLightEstimateANDROID ist so definiert: 

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

Parameterbeschreibungen

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

In XrLightEstimateGetInfoANDROID werden die Informationen beschrieben, die zum Abrufen von Daten zur Lichtschätzung erforderlich sind. 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • space ist der XrSpace, der den Referenzraum definiert, in dem die zurückgegebene Lichtrichtung und die sphärischen Harmonischen und die Cubemap-Rotation ausgedrückt werden.
  • time ist die XrTime, die die Zeit angibt, zu der die Anwendung die Lichtschätzung abfragen möchte.

Gültige Verwendung (implizit)

Die Struktur XrLightEstimateANDROID enthält Daten zur Lichtschätzung. 

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

Beschreibungen von Mitgliedern

Um Informationen zur Lichtschätzung für die Umgebungslicht-Cubemap, das Umgebungslicht, die sphärischen Harmonischen und das primäre Richtungslicht zu erhalten, können Anwendungen Instanzen der folgenden Strukturen XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID und XrDirectionalLightANDROID jeweils an XrLightEstimateANDROID::next koppeln.

Gültige Verwendung (implizit)

Die Struktur XrEnvironmentLightingCubemapANDROID enthält Daten zur Lichtschätzung im Cubemap-Format für die Umgebungsbeleuchtung der Szene. 

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;

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Gültige Strukturen sind XrSphericalHarmonicsANDROID, XrAmbientLightANDROID und XrDirectionalLightANDROID.
  • state ist der XrLightEstimateStateANDROID, der den Status der Lichtschätzung darstellt.
  • cubemapRightImage ist ein float*, das den R32G32B32_SFLOAT-Puffer der rechten Seite der Cubemap darstellt. Hinweis: Da es sich um HDR handelt, können Gleitkommawerte über 1,0 liegen.
  • cubemapLeftImage ist ein float*, das den R32G32B32_SFLOAT-Puffer der linken Seite der Cubemap darstellt. Hinweis: Da es sich um HDR handelt, können Gleitkommawerte über 1,0 liegen.
  • cubemapTopImage ist ein float*, das den R32G32B32_SFLOAT-Puffer der Oberseite der Cubemap darstellt. Hinweis: Da es sich um HDR handelt, können Gleitkommawerte größer als 1,0 sein.
  • cubemapBottomImage ist ein float*, das den R32G32B32_SFLOAT-Puffer der Unterseite der Cubemap darstellt. Hinweis: Da es sich um HDR handelt, können Gleitkommawerte über 1,0 liegen.
  • cubemapFrontImage ist ein float*, das den R32G32B32_SFLOAT-Puffer der Vorderseite der Cubemap darstellt. Hinweis: Da es sich um HDR handelt, können Gleitkommawerte über 1,0 liegen.
  • resolution ist eine uint32_t, die die Breite und Höhe des Bildes jeder Seite der Cubemap angibt. Hinweis: Da es sich um HDR handelt, können Gleitkommawerte über 1,0 liegen.
  • rotation ist eine XrQuaternionf, die die Rotation der Cubemap darstellt.
  • centerExposureTime ist ein XrTime, das die Zeit angibt, zu der die Cubemap erfasst wurde. Nützlich für die Interpolation zwischen Cubemaps.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_light_estimation muss aktiviert sein, bevor XrEnvironmentLightingCubemapANDROID verwendet werden kann.
  • type muss XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID sein.
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
  • state muss ein gültiger Wert für XrLightEstimateStateANDROID sein
  • cubemapRightImage muss ein Verweis auf einen gültigen Gleitkommawert sein.
  • cubemapLeftImage muss ein Verweis auf einen gültigen Gleitkommawert sein.
  • cubemapTopImage muss ein Verweis auf einen gültigen Gleitkommawert sein.
  • cubemapBottomImage muss ein Verweis auf einen gültigen Gleitkommawert sein.
  • cubemapFrontImage muss ein Verweis auf einen gültigen Gleitkommawert sein.
  • cubemapBackImage muss ein Verweis auf einen gültigen Gleitkommawert sein.

Die Struktur XrAmbientLightANDROID enthält Daten zur Lichtschätzung für das Umgebungslicht in der Szene. 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Gültige Strukturen sind XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID und XrDirectionalLightANDROID.
  • state ist der XrLightEstimateStateANDROID, der den Status der Lichtschätzung darstellt.
  • intensity ist ein XrVector3, das die Intensität des Umgebungslichts darstellt. Jede Komponente des Vektors entspricht den roten, grünen und blauen Kanälen.
  • colorCorrection ist ein XrVector3 mit Werten im Gamma-Raum. Multiplizieren Sie die Farbe Ihres gammakorrigierten Renderings komponentenweise mit diesen Werten.

Gültige Verwendung (implizit)

Die Struktur XrSphericalHarmonicsANDROID enthält sphärische Harmonische, die die Beleuchtung der Szene darstellen. 

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

Beschreibungen von Mitgliedern

Gültige Verwendung (implizit)

Die Struktur XrDirectionalLightANDROID enthält Daten zur Lichtschätzung. 

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

Beschreibungen von Mitgliedern

Gültige Verwendung (implizit)

Die Aufzählung XrSphericalHarmonicsKindANDROID gibt der Laufzeit an, welche Art von sphärischen Harmonischen von der Anwendung angefordert wird. 

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

Die Enumerationen haben folgende Bedeutungen:

Enum

Beschreibung

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Die sphärischen harmonischen Koeffizienten stellen die Leuchtdichtefunktion des Umgebungslichts dar, ohne den Beitrag des Hauptlichts.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Die sphärischen harmonischen Koeffizienten repräsentieren die Leuchtdichtefunktion des Umgebungslichts, einschließlich des Beitrags des Hauptlichts.

Die Aufzählung XrLightEstimateStateANDROID gibt der Laufzeit an, welche Art von sphärischen Harmonischen die Anwendung anfordert. 

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

Die Enumerationen haben folgende Bedeutungen:

Enum

Beschreibung

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Die Lichtschätzung ist gültig.

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Die Schätzung für die Beleuchtung ist ungültig.

Beispielcode für die Lichtschätzung

Im folgenden Beispielcode wird gezeigt, wie alle möglichen Werte für die Lichtschätzung aus der Laufzeit abgerufen werden.

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));

Neue Objekttypen

  • XrLightEstimator

Die Aufzählung XrObjectType wurde um Folgendes erweitert:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Die Aufzählung XrStructureType wurde um folgende Elemente erweitert:

  • 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

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Revision 2, 17.01.2025 (Salar Khan)
    • Unterstützung für Umgebungsbeleuchtungs-Cubemaps hinzugefügt
  • Revision 1, 16.09.2024 (Cairn Overturf)
    • Erste Beschreibung der Erweiterung