XR_ANDROID_light_estimation

Ciąg znaków nazwy

XR_ANDROID_light_estimation

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

701

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-03-13

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 otoczenia w świecie rzeczywistym wokół zestawu słuchawkowego. Aplikacja może używać tych informacji do oświetlania wirtualnych obiektów w takich samych warunkach jak w przypadku sceny w świecie rzeczywistym, w której są umieszczone.

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu uprawnienia android.permission.SCENE_UNDERSTANDING_COARSE, ponieważ to rozszerzenie udostępnia informacje o oświetleniu otoczenia. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uznawane za niebezpieczne. Aby korzystać z tych funkcji, aplikacja musi prosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczny)

Sprawdzanie możliwości systemu

Struktura XrSystemLightEstimationPropertiesANDROID jest zdefiniowana w ten sposób:

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 środowisko wykonawcze zwraca XR_FALSE dla supportsLightEstimation , musi zwrócić XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateLightEstimatorANDROID .

Prawidłowe użycie (domyślne)

Tworzenie uchwytu narzędzia do szacowania oświetlenia

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Dane szacowania oświetlenia są generowane przez środowisko wykonawcze i udostępniane aplikacji za pomocą uchwytu XrLightEstimatorANDROID.

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 używa funkcji xrCreateLightEstimatorANDROID do utworzenia estymatora oświetlenia.

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

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

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

Struktura XrLightEstimatorCreateInfoANDROID zawiera informacje potrzebne do utworzenia uchwytu XrLightEstimatorANDROID.

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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 jest zdefiniowana w ten sposób:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Opisy parametrów

Funkcja xrDestroyLightEstimatorANDROID zwalnia estimator i wszystkie zasoby bazowe.

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

Sukces

  • 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

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrLightEstimateGetInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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żony jest zwrócony kierunek światła i harmoniczne sferyczne.
  • time to XrTime, które 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

Jeśli w przypadku każdej struktury szacowania oświetlenia pole state ma wartość XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, wszystkie pozostałe pola w strukturze są dowolne, co oznacza, że ich wartości są niezdefiniowane.

Aby uzyskać informacje o szacunkowej wartości jasności otoczenia, harmonicznych sferycznych i głównego światła kierunkowego, aplikacje mogą łączyć instancje tych struktur: XrAmbientLightANDROID, XrSphericalHarmonicsANDROID i XrDirectionalLightANDROID odpowiednio z XrLightEstimateANDROID :: next .

Prawidłowe użycie (domyślne)

Struktura XrAmbientLightANDROID zawiera dane szacunkowe dotyczące jasności 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 reprezentujący stan szacowania oświetlenia.
  • intensity to XrVector3f reprezentujący jasność otoczenia. Każdy składnik wektora odpowiada odpowiednio kanałom czerwonego, zielonego i niebieskiego.

  • colorCorrection to XrVector3f z wartościami w przestrzeni gamma. Jeśli renderowanie odbywa się w przestrzeni kolorów gamma, pomnóż je komponent po komponencie przez ostateczny obliczony kolor po renderowaniu. Jeśli renderowanie odbywa się w przestrzeni liniowej, najpierw przekonwertuj wartości na przestrzeń liniową, podnosząc je do potęgi 2,2, a następnie pomnóż poszczególne komponenty przez ostateczny obliczony kolor po renderowaniu.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

coefficients są używane w specjalnej funkcji, która przyjmuje kierunek jako dane wejściowe i zwraca kolor światła pochodzącego z tego kierunku. Więcej informacji znajdziesz w tym dokumencie .

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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

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

Opis typu wyliczeniowego

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Współczynniki harmonicznych sferycznych 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 wkład głównego światła.

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 XrLightEstimateStateANDROID wskazuje stan oszacowania oświetlenia zwróconego przez środowisko wykonawcze.

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

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

Opis typu wyliczeniowego

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

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
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

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

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problemy

Historia zmian

  • Wersja 1, 16.09.2024 r. (Cairn Overturf)

    • Wstępny opis rozszerzenia