OpenXR-Erweiterung „XR_ANDROID_light_estimation“

Namensstring

XR_ANDROID_light_estimation

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

701

Revision

1

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2024-09-18

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

Ü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 Lichtermittler 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 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 Umgebungslicht, sphärische Harmonische und das primäre Richtungslicht zu erhalten, können Anwendungen Instanzen der folgenden Strukturen XrAmbientLightANDROID, XrSphericalHarmonicsANDROID und XrDirectionalLightANDROID jeweils an XrLightEstimateANDROID::next koppeln.

Gültige Verwendung (implizit)

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 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 Sie alle möglichen Werte für die Lichtschätzung 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,
};

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

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

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Revision 1, 16.09.2024 (Cairn Overturf)
    • Erste Beschreibung der Erweiterung