XR_ANDROID_light_estimation_cubemap

Name String

XR_ANDROID_light_estimation_cubemap

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

722

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_ANDROID_light_estimation

Datum der letzten Änderung

2025-08-06

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google

Übersicht

Diese Erweiterung baut auf der einfachen XR_ANDROID_light_estimation-Erweiterung auf. Sie bietet Unterstützung für die Schätzung der Beleuchtung mit Cubemaps, was detailliertere Schätzungen der Beleuchtung in der physischen Umgebung ermöglicht.

Hinweis

Der Mechanismus zum Abrufen der Daten zur Lichtschätzung ist derselbe wie bei der grundlegenden Erweiterung, mit der Ausnahme, dass XrCubemapLightEstimatorCreateInfoANDROID beim Erstellen des Handles für die Lichtschätzung mit XrLightEstimatorCreateInfoANDROID verkettet werden muss.

Systemkapazität prüfen

typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;

Mitgliederbeschreibungen

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

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

Wenn die Laufzeit XR_FALSE für supportsCubemapLightEstimation zurückgibt und XrCubemapLightEstimatorCreateInfoANDROID mit XrLightEstimatorCreateInfoANDROID verkettet wurde, muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateLightEstimatorANDROID zurückgeben.

Gültige Verwendung (implizit)

Unterstützte Cubemap-Auflösungen abrufen

XrResult xrEnumerateCubemapLightingResolutionsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    uint32_t*                                   resolutions);

Parameterbeschreibungen

  • instance ist eine zuvor erstellte XrInstance.
  • systemId ist die XrSystemId, die zuvor von xrGetSystem abgerufen wurde und für die die unterstützten Cubemap-Auflösungen abgerufen werden sollen.
  • resolutionCapacityInput ist ein uint32_t, der die maximale Anzahl von Elementen angibt, die im Array resolutions gespeichert werden können.
  • resolutionCountOutput ist ein Verweis auf einen uint32_t, der von der Laufzeit festgelegt wird und die Anzahl der Elemente angibt, die von der Laufzeit in das resolutions-Array geschrieben wurden.
  • resolutions ist ein Array von uint32_t, das von der Laufzeit mit den unterstützten Cubemap-Auflösungen gefüllt wird.

Die Auflösung einer Cubemap gibt die Breite und Höhe jeder Seite der Cubemap in Pixeln an. 2-Aufruf-Idiom: Die Anwendung kann dann eine der unterstützten Auflösungen in XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution verwenden, wenn das Light Estimator-Handle erstellt wird. Die Anwendung muss den entsprechenden Arbeitsspeicher für die Bildpuffer-Mitglieder von XrCubemapLightingDataANDROID basierend auf der ausgewählten Auflösung und dem Farbformat zuweisen.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_light_estimation_cubemap muss aktiviert werden, bevor xrEnumerateCubemapLightingResolutionsANDROID aufgerufen wird.
  • instance muss ein gültiges XrInstance-Handle sein
  • resolutionCountOutput muss ein Zeiger auf einen uint32_t-Wert sein
  • Wenn resolutionCapacityInput nicht 0 ist, muss resolutions ein Zeiger auf ein Array von resolutionCapacityInput-uint32_t-Werten sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Unterstützte Cubemap-Farbformate abrufen

Die Aufzählung XrCubemapLightingColorFormatANDROID gibt der Laufzeit das zu verwendende Farbformat der Cubemap-Beleuchtung an.

typedef enum XrCubemapLightingColorFormatANDROID {
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID = 1,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID = 2,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID = 3,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrCubemapLightingColorFormatANDROID;

Die Enums haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Ein Farbformat mit 3 Kanälen, wobei jeder Kanal ein 32-Bit-Gleitkommawert ist.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Ein Farbformat mit 4 Kanälen, wobei jeder Kanal ein 32-Bit-Gleitkommawert ist.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Ein Farbformat mit 4 Kanälen, wobei jeder Kanal ein 16-Bit-Gleitkommawert ist.

XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    colorFormatCapacityInput,
    uint32_t*                                   colorFormatCountOutput,
    XrCubemapLightingColorFormatANDROID*        colorFormats);

Parameterbeschreibungen

  • instance ist eine zuvor erstellte XrInstance.
  • systemId ist die XrSystemId, die zuvor von xrGetSystem abgerufen wurde und für die die unterstützten Cubemap-Auflösungen abgerufen werden sollen.
  • colorFormatCapacityInput ist ein uint32_t, der die maximale Anzahl von Elementen angibt, die im Array colorFormats gespeichert werden können.
  • colorFormatCountOutput ist ein Verweis auf einen uint32_t, der von der Laufzeit festgelegt wird und die Anzahl der Elemente angibt, die von der Laufzeit in das colorFormats-Array geschrieben wurden.
  • colorFormats ist ein Array von XrCubemapLightingColorFormatANDROID, das von der Laufzeit mit den unterstützten Cubemap-Farbformaten gefüllt wird.

2-Aufruf-Idiom: Die Anwendung kann dann eines der unterstützten Farbformate in XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat verwenden, wenn das Light Estimator-Handle erstellt wird. Die Anwendung muss den entsprechenden Arbeitsspeicher für die Bildpuffer-Mitglieder von XrCubemapLightingDataANDROID basierend auf dem ausgewählten Farbformat zuweisen.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Cubemap-Lichtschätzungs-Handle erstellen

typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
    XrStructureType                        type;
    const void*                            next;
    uint32_t                               cubemapResolution;
    XrCubemapLightingColorFormatANDROID    colorFormat;
    XrBool32                               reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • cubemapResolution ist ein uint32_t, der die Auflösung der zu verwendenden Cubemap-Beleuchtung angibt.
  • colorFormat ist ein XrCubemapLightingColorFormatANDROID, das das Farbformat der zu verwendenden Cubemap-Beleuchtungsdaten angibt.
  • reproject ist ein XrBool32, der angibt, ob die Cubemap-Beleuchtung in den Basisbereich der Anwendung neu projiziert werden sollte.

Die Struktur XrCubemapLightEstimatorCreateInfoANDROID beschreibt die Informationen zum Erstellen eines XrLightEstimatorANDROID-Handles, mit dem Cubemap-Lichtschätzungen bereitgestellt werden können. Das Mitglied XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution muss auf eine der von xrEnumerateCubemapLightingResolutionsANDROID zurückgegebenen Auflösungen festgelegt werden. Das Mitglied XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat muss auf eines der Farbformate festgelegt werden, die von xrEnumerateCubemapLightingColorFormatsANDROID zurückgegeben werden. Wenn die Anwendung die Auflösung nicht auf eine der unterstützten Auflösungen oder das Farbformat nicht auf eines der unterstützten Farbformate festlegt, muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateLightEstimatorANDROID zurückgeben.

Gültige Verwendung (implizit)

Cubemap-Lichtschätzungen

typedef struct XrCubemapLightingDataANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    uint32_t                       imageBufferSize;
    uint8_t*                       imageBufferRight;
    uint8_t*                       imageBufferLeft;
    uint8_t*                       imageBufferTop;
    uint8_t*                       imageBufferBottom;
    uint8_t*                       imageBufferFront;
    uint8_t*                       imageBufferBack;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrCubemapLightingDataANDROID;

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 XrAmbientLightANDROID, XrSphericalHarmonicsANDROID und XrDirectionalLightANDROID .
  • state ist der XrLightEstimateStateANDROID, der den Status der Lichtschätzung darstellt.
  • imageBufferSize ist ein uint32_t, der die Bytegröße jedes Bildpuffers für die Seiten der Cubemap angibt.
  • imageBufferRight ist ein uint8_t-Zwischenspeicher, der das rechte Bild der Cubemap enthält.
  • imageBufferLeft ist ein uint8_t-Zwischenspeicher, der das linke Bild der Cubemap enthält.
  • imageBufferTop ist ein uint8_t-Zwischenspeicher, der das Bild der oberen Fläche der Cubemap enthält.
  • imageBufferBottom ist ein uint8_t-Zwischenspeicher, der das Bild der unteren Fläche der Cubemap enthält.
  • imageBufferFront ist ein uint8_t-Zwischenspeicher, der das Bild der Vorderseite der Cubemap enthält.
  • imageBufferBack ist ein uint8_t-Zwischenspeicher, der das Bild der Rückseite der Cubemap enthält.
  • rotation ist ein XrQuaternionf, der die Drehung der Cubemap angibt.
  • centerExposureTime ist ein XrTime, der den Zeitpunkt der Aufnahme der Cubemap angibt.

Diese Struktur kann mit XrLightEstimateANDROID verkettet werden. Die Laufzeit muss diese Struktur in xrGetLightEstimateANDROID nur dann füllen, wenn XrCubemapLightEstimatorCreateInfoANDROID zum Erstellen des Light Estimator-Handles verwendet wurde. Die Anwendung muss die entsprechende Menge an Arbeitsspeicher für die Bildpuffer zuweisen. Diese hängt von den Werten ab, die beim Erstellen des Handles für die Lichtschätzung in XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution und XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat festgelegt wurden. Die Anwendung muss XrCubemapLightingDataANDROID :: imageBufferSize auf die Kapazität jedes Bildpuffers in Byte festlegen. Wenn die Anwendung keine Cubemap-Lichtschätzung verwendet oder wenn XrCubemapLightingDataANDROID :: imageBufferSize nicht groß genug ist, damit die Laufzeit die Bildpuffer füllen kann, muss die Laufzeit XrCubemapLightingDataANDROID :: state auf XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID setzen.

Wenn die Anwendung beim Erstellen des Handles für die Lichtschätzung XrCubemapLightEstimatorCreateInfoANDROID :: reproject auf XR_TRUE festgelegt hat, muss die Laufzeit XrCubemapLightingDataANDROID :: rotation auf die Identitätsrotation festlegen und dafür sorgen, dass die intern rotierte Cubemap auf die Flächen einer Identitäts-Cubemap im Basisbereich der Anwendung reprojiziert wird.

Das Layout der Beleuchtungs-Cubemap entspricht dem OpenGL-Cubemap-Layout, wie in der folgenden Abbildung dargestellt.

XR ANDROID-Cubemap-Layout für die Lichtschätzung

Abbildung 31: Cube Map-Layout.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_light_estimation_cubemap muss aktiviert sein, bevor XrCubemapLightingDataANDROID verwendet werden kann.
  • type muss XR_TYPE_CUBEMAP_LIGHTING_DATA_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
  • imageBufferRight muss ein Zeiger auf ein Array von imageBufferSize uint8_t-Werten sein.
  • imageBufferLeft muss ein Zeiger auf ein Array von imageBufferSize uint8_t-Werten sein.
  • imageBufferTop muss ein Zeiger auf ein Array von imageBufferSize uint8_t-Werten sein.
  • imageBufferBottom muss ein Zeiger auf ein Array von imageBufferSize uint8_t-Werten sein.
  • imageBufferFront muss ein Zeiger auf ein Array von imageBufferSize uint8_t-Werten sein.
  • imageBufferBack muss ein Zeiger auf ein Array von imageBufferSize uint8_t-Werten sein.
  • Der Parameter imageBufferSize muss größer als 0 sein.

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

Der folgende Beispielcode zeigt, wie Sie alle möglichen Werte für die Lichtschätzung von der Laufzeit abrufen:

XrSession session;  // Created at app startup
XrInstance instance; // Created at app startup
XrSpace appSpace;   // Created previously.
XrSystemId systemId; // Retrieved previously by xrGetSystem
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingResolutionsANDROID xrEnumerateCubemapLightingResolutionsANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingColorFormatsANDROID xrEnumerateCubemapLightingColorFormatsANDROID; // Created previously.

XrSystemCubemapLightEstimationPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID};
XrSystemProperties base = {.type = XR_TYPE_SYSTEM_PROPERTIES,
                           .next = &props};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));
if (!props.supportsCubemapLightEstimation) {
   // Cubemap light estimation is not supported
}

uint32_t cubemapResolution = 0;
std::vector<uint32_t> supportedCubemapResolutions;
uint32_t resolutionCount;
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
  instance, systemId, 0, &resolutionCount, nullptr));
supportedCubemapResolutions.resize(resolutionCount);
if (resolutionCount == 0) {
  // No cubemap lighting supported
} else {
  CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
    instance, systemId, 0, &resolutionCount, supportedCubemapResolutions.data()));
  cubemapResolution = supportedCubemapResolutions[0];
}

uint32_t pixelCount = cubemapResolution * cubemapResolution;

XrCubemapLightingColorFormatANDROID colorFormat;
std::vector<XrCubemapLightingColorFormatANDROID> supportedColorFormats;
uint32_t colorFormatCount;
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
  instance, systemId, 0, &colorFormatCount, nullptr));
supportedColorFormats.resize(colorFormatCount);
if (colorFormatCount == 0) {
  // No supported color formats for cubemap lighting. Cannot use cubemap
  // light estimation.
} else {
  CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
    instance, systemId, 0, &colorFormatCount, supportedColorFormats.data()));
  colorFormat = supportedColorFormats[0];
}

uint32_t pixelSize = 0;
switch (colorFormat) {
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID:
    pixelSize = 3 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(uint16_t);
    break;
  default:
    // Should not happen since the color format was validated previously.
    break;
}

uint32_t perFaceImageBufferSize = pixelCount * pixelSize;

XrLightEstimatorANDROID estimator;
XrCubemapLightEstimatorCreateInfoANDROID cubemapCreateInfo = {
    .type = XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .cubemapResolution = cubemapResolution,
    .colorFormat = colorFormat,
    .reproject = XR_TRUE
};
XrLightEstimatorCreateInfoANDROID basicCreateInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .next = &cubemapCreateInfo};
CHK_XR(xrCreateLightEstimatorANDROID(session, &basicCreateInfo, &estimator));

std::vector<uint8_t> cubemapBuffer(perFaceImageBufferSize * 6); // 6 faces * perFaceImageBufferSize

// 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,
};

XrCubemapLightingDataANDROID cubemap = {
    .type = XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID,
    .next = nullptr,
    .imageBufferSize = perFaceImageBufferSize,
    .imageBufferRight = cubemapBuffer.data() + 0 * perFaceImageBufferSize,
    .imageBufferLeft = cubemapBuffer.data() + 1 * perFaceImageBufferSize,
    .imageBufferTop = cubemapBuffer.data() + 2 * perFaceImageBufferSize,
    .imageBufferBottom = cubemapBuffer.data() + 3 * perFaceImageBufferSize,
    .imageBufferFront = cubemapBuffer.data() + 4 * perFaceImageBufferSize,
    .imageBufferBack = cubemapBuffer.data() + 5 * perFaceImageBufferSize,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
    .next = &cubemap,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &totalSh,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
};

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 cubemap, directionalLight, totalSh, ambientSh, and
  // ambientLight if each struct has a valid state field

  if (cubemap.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
    // use cubemap
    if (cubemapCreateInfo.reproject == XR_TRUE) {
      XrQuaternionf identityQuaternion = {0.0f, 0.0f, 0.0f, 1.0f};
      assert(memcmp(&cubemap.rotation, &identityQuaternion, sizeof(XrQuaternionf)) == 0);
    }
  }
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

Neue Befehle

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
  • XR_ANDROID_light_estimation_cubemap_SPEC_VERSION
  • Erweiterung von XrStructureType :

    • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
    • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Probleme

Versionsverlauf

  • Version 1, 05.12.2025 (Salar Khan)

    • Anfängliche Beschreibung der Erweiterung