Rozszerzenie OpenXR XR_ANDROID_light_estimation

Ciąg znaków nazwy

XR_ANDROID_light_estimation

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

701

Weryfikacja

1

Zależności rozszerzenia i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-01-17

Stan adresu IP

Brak znanych roszczeń dotyczących praw autorskich do treści objętych ochroną prawną.

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 przedstawiających oświetlenie środowiska rzeczywistego wokół zestawu słuchawkowego. Te informacje mogą być używane podczas renderowania obiektów wirtualnych, aby oświetlać je w tych samych warunkach co sceny, w których się znajdują.

Sprawdzanie możliwości systemu

Aplikacja może sprawdzić, czy system obsługuje szacowanie światła, łącząc strukturę XrSystemLightEstimationPropertiesANDROID z 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 struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • supportsLightEstimation to XrBool32, który wskazuje, czy bieżący system obsługuje szacowanie światła.

Aplikacja może sprawdzić, czy system obsługuje szacowanie oświetlenia. Aby to zrobić, podczas wywołania xrGetSystemProperties rozszerza strukturę XrSystemProperties o strukturę XrSystemLightEstimationPropertiesANDROID.

Jeśli system nie obsługuje szacowania oświetlenia, zwraca XR_FALSE dla supportsLightEstimation i XR_ERROR_FEATURE_UNSUPPORTED z xrCreateLightEstimatorANDROID.

Prawidłowe użycie (domyślne)

Tworzenie konta szacującego

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Uchwyt XrLightEstimatorANDROID reprezentuje szacowanie światła. Za pomocą tego uchwytu można uzyskać dostęp do informacji o szacowaniu światła 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

Aplikacja może użyć funkcji xrCreateLightEstimatorANDROID do utworzenia szacowania światła.

Zwrócony identyfikator kalkulatora oświetlenia może być później używany w wywołaniach interfejsu API. Jeśli aplikacja chce wskazać środowisku uruchomieniowemu, że skończyła korzystać z danych oceny światła, musi zniszczyć uchwyt za pomocą funkcji xrDestroyLightEstimatorANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotu

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 struktury. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano żadnych takich struktur.

Prawidłowe użycie (domyślne)

Funkcja xrDestroyLightEstimatorANDROID zwalnia estimator i wszystkie zasoby podrzędne. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Opisy parametrów

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotu

Gotowe

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Dostęp do danych o szacowaniu światła

Funkcja xrGetLightEstimateANDROID jest zdefiniowana jako: 

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

Opisy parametrów

Prawidłowe użycie (domyślne)

Kody zwrotu

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

W XrLightEstimateGetInfoANDROID opisano informacje wymagane do uzyskania danych o szacowaniu światła. 

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 struktury.
  • space to XrSpace określający przestrzeń odniesienia, w której wyrażane są zwrócone kierunki światła i harmoniczne sferyczne oraz obrót mapy sześciennej.
  • time to XrTime określający czas, w którym aplikacja chce wysłać zapytanie o szacowanie światła.

Prawidłowe użycie (domyślne)

Struktura XrLightEstimateANDROID zawiera dane o szacowaniu światła. 

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

Opisy członków

Aby uzyskać informacje o szacowaniu światła dla mapy sześcienkowej oświetlenia otoczenia, światła rozproszonego, harmonik sferycznych i głównego światła kierunkowego, aplikacje mogą połączyć instancje następujących struktur: XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID i XrDirectionalLightANDROID z XrLightEstimateANDROID::next.

Prawidłowe użycie (domyślne)

Struktura XrEnvironmentLightingCubemapANDROID zawiera dane o szacowaniu oświetlenia w formacie cubemap dotyczące oświetlenia otoczenia w scenie. 

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 struktury. Dozwolone struktury to XrSphericalHarmonicsANDROID, XrAmbientLightANDROID i XrDirectionalLightANDROID.
  • state to XrLightEstimateStateANDROID reprezentujący stan oszacowania światła.
  • cubemapRightImage to float* reprezentujący bufor R32G32B32_SFLOAT po prawej stronie mapy sześcien. 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 po lewej stronie mapy sześcien. 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 mapy sześcien. Pamiętaj, że jest to HDR, więc wartości zmiennoprzecinkowe mogą być większe niż 1,0.
  • rotation to XrQuaternionf reprezentujący obrót mapy sześcien.
  • centerExposureTime to XrTime reprezentujący czas przechwycenia mapy sześcien. Przydatne do interpolacji między mapami sześcien.

Prawidłowe użycie (domyślne)

  • Przed użyciem funkcji XrEnvironmentLightingCubemapANDROID musi być włączone rozszerzenie XR_ANDROID_light_estimation.
  • type musi być XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktury.
  • 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 o szacowaniu światła oświetlenia otoczenia w scenie. 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Dozwolone struktury to XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID i XrDirectionalLightANDROID.
  • state to XrLightEstimateStateANDROID, który reprezentuje stan oszacowania światła.
  • intensity to XrVector3, który reprezentuje intensywność światła otoczenia. Każdy składnik wektora odpowiada kanałom czerwonemu, zielonemu i niebieskiemu.
  • colorCorrection to XrVector3 z wartościami w przestrzeni gamma. Komponentowo pomnóż kolor z rendera z poprawionym wygładzaniem gamma za pomocą tych wartości.

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 o szacowaniu światła. 

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 dla środowiska uruchomieniowego, jakiego typu harmonik sferycznych potrzebuje aplikacja. 

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

Wykazy te mają następujące znaczenia:

Wyliczenie

Opis

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Współczynniki harmoniczne sferyczne reprezentują funkcję promieniowania światła otoczenia, w tym udział światła głównego.

Wyliczenie XrLightEstimateStateANDROID określa w czasie wykonywania, jakiego typu harmoniczne sferyczne wymaga aplikacja. 

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

Wykazy te mają następujące znaczenia:

Wyliczenie

Opis

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

prawidłowa szacowana wartość światła;

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Nieprawidłowy szacowany koszt

Przykładowy kod do szacowania oświetlenia

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

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 września 2024 r. (Cairn Overturf)
    • Początkowy opis rozszerzenia