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

2024-09-18

Stan adresu IP

Brak znanych roszczeń dotyczących adresu IP.

Twórcy

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, 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 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. 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 struktur. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.

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 struktur.
  • space to XrSpace definiujący przestrzeń odniesienia, w której wyrażane są zwrócone kierunki światła i harmoniki sferyczne.
  • time to XrTime, który określa 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 światła otoczenia, harmonik sferycznych i głównego światła kierunkowego, aplikacje mogą połączyć instancje następujących struktur: XrAmbientLightANDROID, XrSphericalHarmonicsANDROID i XrDirectionalLightANDROID z XrLightEstimateANDROID::next.

Prawidłowe użycie (domyślne)

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 struktur. Prawidłowe struktury to XrSphericalHarmonicsANDROID i XrDirectionalLightANDROID.
  • state to XrLightEstimateStateANDROID, który reprezentuje stan oszacowania światła.
  • intensity to XrVector3 reprezentujący 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 poprawioną wartością 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ę jasności oświetlenia otoczenia, z wyłączeniem wpływu światła głównego.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

Wyliczenie XrLightEstimateStateANDROID określa w czasie wykonywania, jakiego typu harmoniczne sferyczne potrzebuje 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łowa szacowana ilość światła

Przykładowy kod do szacowania oświetlenia

Poniższy przykładowy kod pokazuje, jak uzyskać wszystkie możliwe wartości szacowania światła 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,
};

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

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

Nowe wartości w polu enum

Nowe struktury

Nowe funkcje

Problemy

Historia wersji

  • Wersja 1, 16 września 2024 r. (Cairn Overturf)
    • Wstępny opis rozszerzenia