OpenXR-Erweiterung „XR_ANDROID_light_estimation“

Name String

XR_ANDROID_light_estimation

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

701

Revision

1

Abhängigkeiten von Erweiterungen und Versionen

OpenXR 1.0

Datum der letzten Änderung

2025-01-17

IP-Status

Es sind keine Ansprüche wegen geistigen Eigentums 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 zur Beleuchtung der realen Umgebung um das Headset herum anfordern. Diese Informationen können verwendet werden, um virtuelle Objekte so zu rendern, dass sie unter denselben Bedingungen beleuchtet werden wie die Szene, in der sie platziert sind.

Systemfunktionen prüfen

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

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Im OpenXR-Kern oder in dieser Erweiterung sind keine solchen Strukturen definiert.
  • supportsLightEstimation ist ein XrBool32, der angibt, ob das aktuelle System die Schätzung von Licht unterstützt.

Eine Anwendung kann prüfen, ob das System die Schätzung von Lichtquellen unterstützt, indem sie die XrSystemProperties-Klasse beim Aufrufen von xrGetSystemProperties mit der Struktur XrSystemLightEstimationPropertiesANDROID erweitert.

Wenn das System keine Schätzung der Lichtverhältnisse unterstützt, wird für supportsLightEstimation der Wert XR_FALSE und für xrCreateLightEstimatorANDROID der Wert XR_ERROR_FEATURE_UNSUPPORTED zurückgegeben.

Gültige Nutzung (implizit)

Handle für die Schätzung von Licht erstellen

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Das Handle XrLightEstimatorANDROID stellt einen Lichtschätzer dar. Mit diesem Handle kann über andere 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

Die Anwendung kann die Funktion xrCreateLightEstimatorANDROID verwenden, um einen Lichtschätzer zu erstellen.

  • xrCreateLightEstimatorANDROID gibt XR_ERROR_FEATURE_UNSUPPORTED zurück, wenn das System die Schätzung der Lichtverhältnisse nicht unterstützt.
  • xrCreateLightEstimatorANDROID gibt XR_ERROR_PERMISSION_INSUFFICIENT zurück, wenn der aufrufenden Anwendung die erforderlichen Berechtigungen nicht erteilt wurden.

Das zurückgegebene Light Estimator-Handle kann anschließend in API-Aufrufen verwendet werden. Wenn eine Anwendung der Laufzeit mitteilen möchte, dass sie den Zugriff auf Daten zur Lichtschätzung beendet hat, muss sie das Handle mit xrDestroyLightEstimatorANDROID zerstören.

Gültige Nutzung (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;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Im OpenXR-Kern oder in dieser Erweiterung sind keine solchen Strukturen definiert.

Gültige Nutzung (implizit)

Mit der Funktion xrDestroyLightEstimatorANDROID werden estimator und alle zugrunde liegenden Ressourcen freigegeben.

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Parameterbeschreibungen

Gültige Nutzung (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 Nutzung (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

XrLightEstimateGetInfoANDROID beschreibt die Informationen, die zum Abrufen von Daten zur Lichtschätzung erforderlich sind.

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

Mitgliederbeschreibungen

  • 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, die sphärischen Harmonischen und die Cubemap-Rotation angegeben werden.
  • time ist der XrTime, der den Zeitpunkt beschreibt, zu dem die Anwendung die Schätzung der Lichtverhältnisse abfragen möchte.

Gültige Nutzung (implizit)

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

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

Mitgliederbeschreibungen

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

Gültige Nutzung (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;

Mitgliederbeschreibungen

  • 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*, der den R32G32B32_SFLOAT-Puffer der rechten Seite der Cubemap darstellt. Da es sich um HDR handelt, können Gleitkommawerte größer als 1,0 sein.
  • cubemapLeftImage ist ein float*, der den R32G32B32_SFLOAT-Puffer der linken Seite der Cubemap darstellt. Da es sich um HDR handelt, können Gleitkommawerte größer als 1,0 sein.
  • cubemapTopImage ist ein float*, der den R32G32B32_SFLOAT-Puffer der Oberseite des Cubemaps darstellt. Da es sich um HDR handelt, können Gleitkommawerte größer als 1,0 sein.
  • cubemapBottomImage ist ein float*, der den R32G32B32_SFLOAT-Puffer der Unterseite des Cubemaps darstellt. Da es sich um HDR handelt, können Gleitkommawerte größer als 1,0 sein.
  • cubemapFrontImage ist ein float*, das den R32G32B32_SFLOAT-Puffer der Vorderseite der Cubemap darstellt. Da es sich um HDR handelt, können Gleitkommawerte größer als 1,0 sein.
  • resolution ist ein uint32_t, das die Breite und Höhe des Bildes jeder Seite der Cubemap darstellt.
  • rotation ist ein XrQuaternionf, das die Rotation der Cubemap darstellt.
  • centerExposureTime ist ein XrTime, der den Zeitpunkt der Aufnahme des Cubemaps darstellt. Nützlich für die Interpolation zwischen Cubemaps.

Gültige Nutzung (implizit)

  • Die Erweiterung XR_ANDROID_light_estimation muss aktiviert werden, bevor XrEnvironmentLightingCubemapANDROID verwendet wird.
  • 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 XrLightEstimateStateANDROID-Wert sein.
  • cubemapRightImage muss ein Zeiger auf einen gültigen Gleitkommawert sein.
  • cubemapLeftImage muss ein Zeiger auf einen gültigen Gleitkommawert sein.
  • cubemapTopImage muss ein Zeiger auf einen gültigen Gleitkommawert sein.
  • cubemapBottomImage muss ein Zeiger auf einen gültigen Gleitkommawert sein.
  • cubemapFrontImage muss ein Zeiger auf einen gültigen Gleitkommawert sein.
  • cubemapBackImage muss ein Zeiger auf einen gültigen Gleitkommawert sein.

Die Struktur XrAmbientLightANDROID enthält Daten zur Schätzung des Umgebungslichts in der Szene.

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

Mitgliederbeschreibungen

  • 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 dem roten, grünen und blauen Kanal.
  • colorCorrection ist ein XrVector3 mit Werten im Gammabereich. Multiplizieren Sie die Farbe Ihres gammakorrigierten Renderings komponentenweise mit diesen Werten.

Gültige Nutzung (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;

Mitgliederbeschreibungen

Gültige Nutzung (implizit)

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

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

Mitgliederbeschreibungen

Gültige Nutzung (implizit)

Die Enumeration XrSphericalHarmonicsKindANDROID gibt der Laufzeit an, welche Art von sphärischen Harmonischen die Anwendung anfordert.

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

Die Enums haben die folgenden Bedeutungen:

Enum

Beschreibung

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Die sphärischen harmonischen Koeffizienten stellen die Strahlungsfunktion des Umgebungslichts dar, einschließlich des Beitrags des Hauptlichts.

Die Enumeration 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 Enums haben die folgenden Bedeutungen:

Enum

Beschreibung

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Die Lichtschätzung ist gültig.

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Die Lichtschätzung ist ungültig

Beispielcode für die Schätzung der Lichtverhältnisse

Der folgende Beispielcode zeigt, wie Sie alle möglichen Schätzwerte für die Beleuchtung aus der Laufzeit abrufen.

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 Enumeration XrObjectType wird um Folgendes erweitert:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Die Enumeration XrStructureType wurde um Folgendes 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

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

OpenXR™ und das OpenXR-Logo sind Marken von The Khronos Group Inc. und sind in China, der Europäischen Union, Japan und dem Vereinigten Königreich als Marke eingetragen.