XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

701

Revision

1

Ratifikationsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

OpenXR 1.0

Datum der letzten Änderung

2025-03-13

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 anfordern, die die Beleuchtung der realen Umgebung um das Headset herum darstellen. Die Anwendung kann diese Informationen verwenden, um virtuelle Objekte unter denselben Bedingungen zu beleuchten wie die reale Szene, in der sie platziert werden.

Berechtigungen

Android-Anwendungen müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest aufführen, da diese Erweiterung Informationen zur Beleuchtung der Umgebung bereitstellt. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ gilt als gefährliche Berechtigung. Die App muss die Berechtigung zur Laufzeit anfordern, um diese Funktionen zu verwenden:

(Schutzebene: gefährlich)

Systemfunktionen prüfen

Die Struktur XrSystemLightEstimationPropertiesANDROID wird so definiert:

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. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht 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 der Lichtverhältnisse unterstützt, indem sie die XrSystemProperties beim Aufrufen von xrGetSystemProperties mit der Struktur XrSystemLightEstimationPropertiesANDROID erweitert .

Wenn und nur wenn eine Laufzeit XR_FALSE für supportsLightEstimation zurückgibt , muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateLightEstimatorANDROID zurückgeben .

Gültige Nutzung (implizit)

Handle für Schätzung der Lichtverhältnisse erstellen

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Die Daten zur Lichtschätzung werden von der Laufzeit generiert und über das XrLightEstimatorANDROID-Handle für die Anwendung freigegeben.

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

  • session ist die XrSession, mit der der Lichtschätzer erstellt wird.
  • createInfo ist ein Zeiger auf eine XrLightEstimatorCreateInfoANDROID-Struktur, die Parameter enthält, die zum Erstellen des Lichtschätzers verwendet werden sollen.
  • outHandle ist ein Zeiger auf ein Handle, in dem der erstellte XrLightEstimatorANDROID zurückgegeben wird.

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

  • Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn das System die Schätzung der Lichtverhältnisse nicht unterstützt.
  • Die Laufzeit muss XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben, wenn der Anruf-App die erforderlichen Berechtigungen nicht erteilt wurden.

Wenn eine Anwendung der Laufzeit mitteilen möchte, dass sie den Zugriff auf Daten zur Lichtschätzung beendet hat, muss sie das Handle über xrDestroyLightEstimatorANDROID zerstören .

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

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

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

Mitgliederbeschreibungen

  • 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 Core oder dieser Erweiterung nicht definiert.

Gültige Nutzung (implizit)

Die Funktion xrDestroyLightEstimatorANDROID ist so definiert:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Parameterbeschreibungen

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

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_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

Die Struktur XrLightEstimateGetInfoANDROID ist so definiert:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 und die sphärischen Harmonischen ausgedrückt werden.
  • time ist der XrTime, der die Uhrzeit beschreibt, zu der 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

Wenn für jede Light Estimate-Struktur state gleich XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID ist , sind alle anderen Felder in der Struktur beliebig. Das bedeutet, dass ihre Werte nicht definiert sind.

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

Gültige Nutzung (implizit)

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 und XrDirectionalLightANDROID .
  • state ist der XrLightEstimateStateANDROID, der den Status der Lichtschätzung darstellt.
  • intensity ist ein XrVector3f, der die Intensität des Umgebungslichts darstellt. Jede Komponente des Vektors entspricht dem roten, grünen bzw. blauen Kanal.

  • colorCorrection ist ein XrVector3f mit Werten im Gammabereich. Wenn im Gamma-Farbraum gerendert wird, multiplizieren Sie sie komponentenweise mit der endgültigen berechneten Farbe nach dem Rendern. Wenn die Darstellung im linearen Raum erfolgt, müssen die Werte zuerst in den linearen Raum konvertiert werden, indem sie mit 2,2 potenziert werden.Anschließend werden sie nach der Darstellung komponentenweise mit der endgültigen berechneten Farbe multipliziert.

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

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

Die coefficients werden in einer speziellen Funktion verwendet, die eine Richtung als Eingabe akzeptiert und die Lichtfarbe aus dieser Richtung ausgibt. Weitere Informationen

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

Die Aufzählungswerte haben die folgende Bedeutung:

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 Leuchtdichtefunktion des Umgebungslichts dar, einschließlich des Beitrags des Hauptlichts.

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 Aufzählung XrLightEstimateStateANDROID gibt den Status der von der Laufzeit zurückgegebenen Lichtschätzung an.

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;

Die Aufzählungswerte haben die folgende Bedeutung:

Enum-Beschreibung

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Die Lichtschätzung ist gültig

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Die Schätzung der Lichtverhältnisse ist ungültig

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

Der folgende Beispielcode zeigt, wie Sie alle möglichen Mengen für die Lichtschätzung aus der Laufzeit abrufen können.

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

Neue Objekttypen

Neue Befehle

Neue Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • XrObjectType erweitern :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Erweitern von 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

Probleme

Versionsverlauf

  • Revision 1, 16.09.2024 (Cairn Overturf)

    • Erste Beschreibung der Erweiterung