Rozszerzenie OpenXR XR_ANDROID_light_estimation

Ciąg znaków nazwy

XR_ANDROID_light_estimation

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

701

Wersja

1

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-01-17

Stan adresu IP

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

Twórcy

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Salar Khan, Google

Scott Chung, Google

Omówienie

To rozszerzenie umożliwia aplikacji żądanie danych reprezentujących oświetlenie środowiska w świecie rzeczywistym wokół zestawu słuchawkowego. Te informacje mogą być używane podczas renderowania obiektów wirtualnych, aby oświetlać je w tych samych warunkach co scena, w której są umieszczone.

Sprawdzanie możliwości systemu

Aplikacja może sprawdzić, czy system obsługuje szacowanie oświetlenia, łącząc strukturę XrSystemLightEstimationPropertiesANDROID ze strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties. 

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

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.
  • supportsLightEstimation to XrBool32, który wskazuje, czy bieżący system obsługuje szacowanie oświetlenia.

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

Jeśli system nie obsługuje szacowania oświetlenia, funkcja xrCreateLightEstimatorANDROID zwróci wartość XR_FALSE dla supportsLightEstimation i XR_ERROR_FEATURE_UNSUPPORTED.

Prawidłowe użycie (domyślne)

Tworzenie uchwytu narzędzia do szacowania oświetlenia

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Uchwyt XrLightEstimatorANDROID reprezentuje estymator światła. Ten uchwyt może być używany do uzyskiwania dostępu do informacji o szacowaniu oświetlenia za pomocą innych funkcji w tym rozszerzeniu.

Funkcja xrCreateLightEstimatorANDROID jest zdefiniowana w ten sposób: 

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Opisy parametrów

  • session to XrSession, która tworzy estymator światła.
  • createInfo to wskaźnik struktury XrLightEstimatorCreateInfoANDROID zawierającej parametry, które mają być użyte do utworzenia narzędzia do szacowania oświetlenia.
  • outHandle to wskaźnik do uchwytu, w którym zwracany jest utworzony obiekt XrLightEstimatorANDROID.

Aplikacja może użyć funkcji xrCreateLightEstimatorANDROID, aby utworzyć estymator światła.

  • Funkcja xrCreateLightEstimatorANDROID zwróci wartość XR_ERROR_FEATURE_UNSUPPORTED, jeśli system nie obsługuje szacowania oświetlenia.
  • Funkcja xrCreateLightEstimatorANDROID zwróci wartość XR_ERROR_PERMISSION_INSUFFICIENT, jeśli wymagane uprawnienia nie zostały przyznane aplikacji wywołującej.

Zwrócony uchwyt szacowania oświetlenia może być później używany w wywołaniach interfejsu API. Jeśli aplikacja chce poinformować środowisko wykonawcze, że zakończyła dostęp do danych szacowania oświetlenia, musi zniszczyć uchwyt za pomocą funkcji xrDestroyLightEstimatorANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotne

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrLightEstimatorCreateInfoANDROID zawiera informacje potrzebne do utworzenia uchwytu XrLightEstimatorANDROID. 

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

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.

Prawidłowe użycie (domyślne)

Funkcja xrDestroyLightEstimatorANDROID zwalnia estimator i wszystkie powiązane zasoby. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Opisy parametrów

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

  • Dostęp do estimator i wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.

Kody zwrotne

Gotowe

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Dostęp do danych szacowania oświetlenia

Funkcja xrGetLightEstimateANDROID jest zdefiniowana w ten sposób: 

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Opisy parametrów

Prawidłowe użycie (domyślne)

Kody zwrotne

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrLightEstimateGetInfoANDROID opisuje informacje wymagane do uzyskania danych szacowania oświetlenia. 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • space to XrSpace określający przestrzeń odniesienia, w której wyrażone są zwrócony kierunek światła, harmoniczne sferyczne i rotacja mapy sześciennej.
  • time to XrTime, który opisuje czas, w którym aplikacja chce wysłać zapytanie o szacowanie oświetlenia.

Prawidłowe użycie (domyślne)

Struktura XrLightEstimateANDROID zawiera dane szacowania oświetlenia. 

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

Opisy członków

Aby uzyskać informacje o szacunkowym oświetleniu w przypadku mapy sześciennej oświetlenia otoczenia, światła otoczenia, harmonicznych sferycznych i głównego światła kierunkowego, aplikacje mogą łączyć instancje tych struktur: XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID i XrDirectionalLightANDROID odpowiednio z XrLightEstimateANDROID::next.

Prawidłowe użycie (domyślne)

Struktura XrEnvironmentLightingCubemapANDROID zawiera dane szacowania oświetlenia w formacie cubemap dotyczące oświetlenia otoczenia sceny. 

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;

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 XrSphericalHarmonicsANDROID, XrAmbientLightANDROID i XrDirectionalLightANDROID.
  • state to XrLightEstimateStateANDROID reprezentujący stan szacowania oświetlenia.
  • cubemapRightImage to float* reprezentujący bufor R32G32B32_SFLOAT prawej strony mapy sześciennej. Pamiętaj, że jest to HDR, więc wartości zmiennoprzecinkowe mogą być większe niż 1,0.
  • cubemapLeftImage to float* reprezentujący bufor R32G32B32_SFLOAT lewej strony mapy sześciennej. Pamiętaj, że jest to HDR, więc wartości zmiennoprzecinkowe mogą być większe niż 1,0.
  • cubemapTopImage to float* reprezentujący bufor R32G32B32_SFLOAT górnej strony mapy sześciennej. Pamiętaj, że jest to HDR, więc wartości zmiennoprzecinkowe mogą być większe niż 1,0.
  • cubemapBottomImage to float* reprezentujący bufor R32G32B32_SFLOAT dolnej strony mapy sześciennej. Pamiętaj, że jest to HDR, więc wartości zmiennoprzecinkowe mogą być większe niż 1,0.
  • cubemapFrontImage to float* reprezentujący bufor R32G32B32_SFLOAT przedniej strony mapy sześciennej. Pamiętaj, że jest to HDR, więc wartości zmiennoprzecinkowe mogą być większe niż 1,0.
  • resolution to uint32_t reprezentujący szerokość i wysokość obrazu każdej strony sześcianu.
  • rotation to XrQuaternionf reprezentujący obrót mapy sześciennej.
  • centerExposureTime to XrTime reprezentujący czas, w którym zarejestrowano mapę sześcienną. Przydatne do interpolacji między mapami sześciennymi.

Prawidłowe użycie (domyślne)

  • Rozszerzenie XR_ANDROID_light_estimation musi być włączone przed użyciem XrEnvironmentLightingCubemapANDROID.
  • type musi mieć wartość XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next musi być wartością NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
  • state musi być prawidłową wartością XrLightEstimateStateANDROID
  • cubemapRightImage musi być wskaźnikiem do prawidłowej wartości zmiennoprzecinkowej.
  • cubemapLeftImage musi być wskaźnikiem do prawidłowej wartości zmiennoprzecinkowej.
  • cubemapTopImage musi być wskaźnikiem do prawidłowej wartości zmiennoprzecinkowej.
  • cubemapBottomImage musi być wskaźnikiem do prawidłowej wartości zmiennoprzecinkowej.
  • cubemapFrontImage musi być wskaźnikiem do prawidłowej wartości zmiennoprzecinkowej.
  • cubemapBackImage musi być wskaźnikiem do prawidłowej wartości zmiennoprzecinkowej.

Struktura XrAmbientLightANDROID zawiera dane szacowania oświetlenia dotyczące oświetlenia otoczenia w scenie. 

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

Opisy członków

Prawidłowe użycie (domyślne)

Struktura XrSphericalHarmonicsANDROID zawiera harmoniczne sferyczne reprezentujące oświetlenie sceny. 

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

Opisy członków

Prawidłowe użycie (domyślne)

Struktura XrDirectionalLightANDROID zawiera dane szacowania oświetlenia. 

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

Opisy członków

Prawidłowe użycie (domyślne)

Wyliczenie XrSphericalHarmonicsKindANDROID określa środowisku wykonawczemu, jakiego typu harmonicznych sferycznych żąda aplikacja. 

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

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

Enum

Opis

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Współczynniki harmoniczne sferyczne reprezentują funkcję luminancji światła otoczenia, z wyłączeniem wpływu światła głównego.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Współczynniki harmonicznych sferycznych reprezentują funkcję luminancji światła otoczenia, w tym udział głównego źródła światła.

Wyliczenie XrLightEstimateStateANDROID określa dla środowiska wykonawczego, jakiego typu harmonicznych sferycznych żąda aplikacja. 

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;

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

Enum

Opis

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Oszacowanie oświetlenia jest prawidłowe

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Oszacowanie oświetlenia jest nieprawidłowe

Przykładowy kod do szacowania oświetlenia

Przykładowy kod poniżej pokazuje, jak uzyskać z czasu działania wszystkie możliwe wartości szacowania oświetlenia.

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

Nowe typy obiektów

  • XrLightEstimator

Wyliczenie XrObjectType zostało rozszerzone o:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Wyliczenie XrStructureType zostało rozszerzone o:

  • 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

Nowe wartości w polu enum

Nowe struktury

Nowe funkcje

Problemy

Historia wersji

  • Wersja 2, 17 stycznia 2025 r. (Salar Khan)
    • Dodano obsługę mapy sześciennej oświetlenia otoczenia
  • Wersja 1, 16.09.2024 (Cairn Overturf)
    • Wstępny opis rozszerzenia

OpenXR™ i logo OpenXR są znakami towarowymi należącymi do The Khronos Group Inc. i są zarejestrowane jako znaki towarowe w Chinach, Unii Europejskiej, Japonii i Wielkiej Brytanii.