XR_ANDROID_light_estimation_cubemap

Ciąg znaków nazwy

XR_ANDROID_light_estimation_cubemap

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

722

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_ANDROID_light_estimation

Data ostatniej modyfikacji

2025-08-06

Stan adresu IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Omówienie

To rozszerzenie jest oparte na podstawowym rozszerzeniu XR_ANDROID_light_estimation. Dodaje obsługę szacowania oświetlenia mapy sześciennej, co zapewnia bardziej szczegółowe szacunki dotyczące oświetlenia w środowisku fizycznym.

Uwaga

Mechanizm uzyskiwania danych szacowania oświetlenia jest taki sam jak w przypadku podstawowego rozszerzenia, z tym wyjątkiem, że podczas tworzenia uchwytu szacowania oświetlenia element XrCubemapLightEstimatorCreateInfoANDROID musi być połączony z elementem XrLightEstimatorCreateInfoANDROID.

Sprawdzanie możliwości systemu

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsCubemapLightEstimation to XrBool32, który wskazuje, czy bieżący system obsługuje szacowanie oświetlenia za pomocą mapy sześciennej.

Aplikacja może sprawdzić, czy system obsługuje szacowanie oświetlenia za pomocą mapy sześciennej, rozszerzając strukturę XrSystemProperties o strukturę XrSystemCubemapLightEstimationPropertiesANDROID podczas wywoływania funkcji xrGetSystemProperties .

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsCubemapLightEstimation, a struktura XrCubemapLightEstimatorCreateInfoANDROID została połączona w łańcuch ze strukturą XrLightEstimatorCreateInfoANDROID, środowisko wykonawcze musi zwrócić XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateLightEstimatorANDROID .

Prawidłowe użycie (domyślne)

Pobieranie obsługiwanych rozdzielczości mapy sześciennej

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

Opisy parametrów

  • instance to utworzony wcześniej obiekt XrInstance.
  • systemId to XrSystemId pobrany wcześniej przez funkcję xrGetSystem, dla którego mają zostać pobrane obsługiwane rozdzielczości mapy sześciennej.
  • resolutionCapacityInput to uint32_t, które wskazuje maksymalną liczbę elementów, które można przechowywać w tablicy resolutions.
  • resolutionCountOutput to wskaźnik do uint32_t, który jest ustawiany przez środowisko wykonawcze i wskazuje liczbę elementów zapisanych w tablicy resolutions przez środowisko wykonawcze.
  • resolutions to tablica uint32_t, która jest wypełniana przez środowisko wykonawcze obsługiwanymi rozdzielczościami mapy sześciennej.

Rozdzielczość mapy sześciennej określa szerokość i wysokość każdej ściany mapy sześciennej w pikselach. Idiom 2-call Aplikacja może następnie wybrać jedną z obsługiwanych rozdzielczości w XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution podczas tworzenia uchwytu estymatora światła. Aplikacja musi przydzielić odpowiednią ilość pamięci dla elementów bufora obrazu struktury XrCubemapLightingDataANDROID na podstawie wybranej rozdzielczości i formatu koloru.

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_light_estimation_cubemap musi być włączone przed wywołaniem funkcji xrEnumerateCubemapLightingResolutionsANDROID.
  • instance musi być prawidłowym uchwytem XrInstance.
  • resolutionCountOutput musi być wskaźnikiem wartości uint32_t
  •  Jeśli resolutionCapacityInput nie jest równe 0 , resolutions musi być wskaźnikiem do tablicy wartości resolutionCapacityInput uint32_t.

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • 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

Pobieranie obsługiwanych formatów kolorów mapy sześciennej

Wyliczenie XrCubemapLightingColorFormatANDROID określa format koloru oświetlenia mapy sześciennej, który ma być używany przez środowisko wykonawcze.

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;

Wartości wyliczeniowe mają następujące znaczenia:

Opis typu wyliczeniowego

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Format koloru z 3 kanałami, w którym każdy kanał ma 32-bitową wartość zmiennoprzecinkową.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Format koloru z 4 kanałami, w którym każdy kanał ma 32-bitową wartość zmiennoprzecinkową.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Format koloru z 4 kanałami, w którym każdy kanał ma 16-bitową wartość zmiennoprzecinkową.

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

Opisy parametrów

  • instance to utworzony wcześniej obiekt XrInstance.
  • systemId to XrSystemId pobrany wcześniej przez funkcję xrGetSystem, dla którego mają zostać pobrane obsługiwane rozdzielczości mapy sześciennej.
  • colorFormatCapacityInput to uint32_t, które wskazuje maksymalną liczbę elementów, które można przechowywać w tablicy colorFormats.
  • colorFormatCountOutput to wskaźnik do uint32_t, który jest ustawiany przez środowisko wykonawcze i wskazuje liczbę elementów zapisanych w tablicy colorFormats przez środowisko wykonawcze.
  • colorFormats to tablica XrCubemapLightingColorFormatANDROID, która jest wypełniana przez środowisko wykonawcze obsługiwanymi formatami kolorów mapy sześciennej.

Idiom 2-wywołań Aplikacja może następnie użyć jednego z obsługiwanych formatów kolorów w XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat podczas tworzenia uchwytu estymatora światła. Aplikacja musi przydzielić odpowiednią ilość pamięci dla elementów bufora obrazu struktury XrCubemapLightingDataANDROID na podstawie wybranego formatu koloru.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • 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

Tworzenie uchwytu do szacowania oświetlenia mapy sześciennej

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • cubemapResolution to uint32_t wskazująca rozdzielczość oświetlenia mapy sześciennej, która ma zostać użyta.
  • colorFormat to XrCubemapLightingColorFormatANDROID określający format koloru danych oświetlenia mapy sześciennej, który ma być używany.
  • reproject to XrBool32 wskazujący, czy oświetlenie mapy sześciennej powinno zostać ponownie zrzutowane na przestrzeń bazową aplikacji.

Struktura XrCubemapLightEstimatorCreateInfoANDROID zawiera informacje potrzebne do utworzenia uchwytu XrLightEstimatorANDROID, który umożliwia podawanie szacunków oświetlenia w postaci mapy sześciennej. Element XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution musi być ustawiony na jedną z rozdzielczości zwróconych przez funkcję xrEnumerateCubemapLightingResolutionsANDROID . Element XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat musi być ustawiony na jeden z formatów kolorów zwróconych przez funkcję xrEnumerateCubemapLightingColorFormatsANDROID . Jeśli aplikacja nie ustawi rozdzielczości na jedną z obsługiwanych rozdzielczości lub formatu koloru na jeden z obsługiwanych formatów koloru, środowisko wykonawcze musi zwrócić wartość XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateLightEstimatorANDROID .

Prawidłowe użycie (domyślne)

Szacowanie oświetlenia w przypadku mapy sześciennej

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;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. Prawidłowe struktury to XrAmbientLightANDROID, XrSphericalHarmonicsANDROIDXrDirectionalLightANDROID .
  • state to XrLightEstimateStateANDROID reprezentujący stan szacowania oświetlenia.
  • imageBufferSize to uint32_t wskazujący rozmiar w bajtach każdego bufora obrazu ściany w mapie sześciennej.
  • imageBufferRight to uint8_t bufor zawierający obraz prawej ściany sześcianu środowiska.
  • imageBufferLeft to uint8_t bufor zawierający obraz lewej ściany sześcianu.
  • imageBufferTop to bufor uint8_t zawierający obraz górnej ściany mapy sześciennej.
  • imageBufferBottom to uint8_t bufor zawierający obraz dolnej ściany mapy sześciennej.
  • imageBufferFront to bufor uint8_t zawierający obraz przedniej ściany mapy sześciennej.
  • imageBufferBack to uint8_t zawierający obraz tylnej ściany mapy sześciennej.
  • rotation to XrQuaternionf wskazujący obrót mapy sześciennej.
  • centerExposureTime to XrTime wskazująca czas, w którym zarejestrowano mapę otoczenia.

Tę strukturę można połączyć z elementem XrLightEstimateANDROID . Środowisko wykonawcze musi wypełniać tę strukturę w funkcji xrGetLightEstimateANDROID tylko wtedy, gdy do utworzenia uchwytu estymatora światła użyto struktury XrCubemapLightEstimatorCreateInfoANDROID. Aplikacja musi przydzielić odpowiednią ilość pamięci na bufory obrazów, która zależy od wartości ustawionych w strukturach XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolutionXrCubemapLightEstimatorCreateInfoANDROID :: colorFormat podczas tworzenia uchwytu estymatora światła. Aplikacja musi ustawić wartość XrCubemapLightingDataANDROID :: imageBufferSize na pojemność każdego bufora obrazu twarzy w bajtach. Jeśli aplikacja nie korzysta z szacowania oświetlenia za pomocą mapy sześciennej lub jeśli XrCubemapLightingDataANDROID :: imageBufferSize nie jest wystarczająco duży, aby środowisko wykonawcze mogło wypełnić bufory obrazów, środowisko wykonawcze musi ustawić XrCubemapLightingDataANDROID :: state na XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .

Jeśli aplikacja ustawiła XrCubemapLightEstimatorCreateInfoANDROID :: reproject na XR_TRUE podczas tworzenia uchwytu estymatora oświetlenia, środowisko wykonawcze musi ustawić XrCubemapLightingDataANDROID :: rotation na rotację tożsamości i zapewnić, że wewnętrzna obrócona mapa sześcianu zostanie ponownie zrzutowana na ściany mapy sześcianu tożsamości w przestrzeni bazowej aplikacji.

Układ mapy sześciennej oświetlenia jest taki sam jak układ mapy sześciennej OpenGL, co widać na tym obrazie.

Układ mapy sześciennej do szacowania oświetlenia w XR na Androidzie

Ilustracja 24. Układ mapy sześciennej.

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_light_estimation_cubemap musi być włączone przed użyciem XrCubemapLightingDataANDROID.
  • type musi mieć wartość XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
  • next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
  • state musi być prawidłową wartością XrLightEstimateStateANDROID.
  • imageBufferRight musi być wskaźnikiem tablicy wartości imageBufferSize uint8_t.
  • imageBufferLeft musi być wskaźnikiem tablicy wartości imageBufferSize uint8_t.
  • imageBufferTop musi być wskaźnikiem tablicy wartości imageBufferSize uint8_t.
  • imageBufferBottom musi być wskaźnikiem tablicy wartości imageBufferSize uint8_t.
  • imageBufferFront musi być wskaźnikiem tablicy wartości imageBufferSize uint8_t.
  • imageBufferBack musi być wskaźnikiem tablicy wartości imageBufferSize uint8_t.
  •  Parametr imageBufferSize musi być większy niż 0.

Przykładowy kod do szacowania oświetlenia

Poniższy przykładowy kod pokazuje, jak uzyskać z czasu działania wszystkie możliwe wartości szacowania oświetlenia.

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

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

  • XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
  • XR_ANDROID_light_estimation_cubemap_SPEC_VERSION
  • Rozszerzanie XrStructureType :

    • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
    • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problemy

Historia wersji

  • Wersja 1, 2025-12-05 (Salar Khan)

    • Wstępny opis rozszerzenia