XR_ANDROID_light_estimation Расширение OpenXR

Строка имени

XR_ANDROID_light_estimation

Тип расширения

Расширение экземпляра

Зарегистрированный внутренний номер

701

Редакция

1

Зависимости расширений и версий

ОпенXR 1.0

Дата последнего изменения

2024-09-18

IP-статус

Нет известных претензий на интеллектуальную собственность.

Авторы

Джаред Файндер, Google

Кэрн Овертерф, Google

Спенсер Куин, Google

Левана Чен, Google

Нихав Джайн, Google

Обзор

Это расширение позволяет приложению запрашивать данные, представляющие освещение реальной среды вокруг гарнитуры. Эту информацию можно использовать при рендеринге виртуальных объектов, чтобы осветить их в тех же условиях, что и сцена, в которой они размещены.

Проверьте возможности системы

Приложение может проверить, поддерживает ли система оценку освещенности, связывая структуру XrSystemLightEstimationPropertiesANDROID с XrSystemProperties при вызове xrGetSystemProperties .

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

Описания участников

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Никакие такие структуры не определены в ядре OpenXR или этом расширении.
  • supportsLightEstimation — это XrBool32 , указывающий, поддерживает ли текущая система оценку освещенности.

Приложение может проверить, способна ли система поддерживать оценку освещенности, расширив XrSystemProperties структурой XrSystemLightEstimationPropertiesANDROID при вызове xrGetSystemProperties .

Если система не поддерживает оценку освещенности, она вернет XR_FALSE для supportsLightEstimation и XR_ERROR_FEATURE_UNSUPPORTED для xrCreateLightEstimatorANDROID .

Допустимое использование (неявное)

Создайте ручку средства оценки освещенности 

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Дескриптор XrLightEstimatorANDROID представляет собой средство оценки освещенности. Этот дескриптор можно использовать для доступа к информации об оценке освещенности с помощью других функций этого расширения.

Функция xrCreateLightEstimatorANDROID определяется как:

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

Описание параметров

  • session — это XrSession , который создает оценщик освещенности.
  • createInfo — это указатель на структуру XrLightEstimatorCreateInfoANDROID , содержащую параметры, которые будут использоваться для создания средства оценки освещенности.
  • outHandle — это указатель на дескриптор, в котором возвращается созданный XrLightEstimatorANDROID .

Приложение может использовать функцию xrCreateLightEstimatorANDROID для создания средства оценки освещенности.

  • xrCreateLightEstimatorANDROID вернет XR_ERROR_FEATURE_UNSUPPORTED если система не поддерживает оценку освещенности.
  • xrCreateLightEstimatorANDROID вернет XR_ERROR_PERMISSION_INSUFFICIENT , если требуемые разрешения не были предоставлены вызывающему приложению.

Возвращенный дескриптор средства оценки освещенности впоследствии может использоваться в вызовах API. Если приложение хочет указать среде выполнения, что доступ к данным оценки освещенности завершен, оно должно уничтожить дескриптор с помощью xrDestroyLightEstimatorANDROID .

Допустимое использование (неявное)

Коды возврата

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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

Структура XrLightEstimatorCreateInfoANDROID описывает информацию для создания дескриптора XrLightEstimatorANDROID .

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

Описания участников

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Никакие такие структуры не определены в ядре OpenXR или этом расширении.

Допустимое использование (неявное)

Функция xrDestroyLightEstimatorANDROID освобождает estimator и все базовые ресурсы.

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Описание параметров

Допустимое использование (неявное)

Безопасность потоков

  • Доступ к estimator и любым дочерним дескрипторам должен быть синхронизирован извне.

Коды возврата

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Доступ к данным оценки освещенности

Функция xrGetLightEstimateANDROID определяется как:

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

Описание параметров

Допустимое использование (неявное)

Коды возврата

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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

XrLightEstimateGetInfoANDROID описывает информацию, необходимую для получения данных оценки освещенности.

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

Описания участников

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур.
  • space — это XrSpace, определяющее опорное пространство, в котором выражаются направление отраженного света и сферические гармоники.
  • time — это XrTime , который описывает время, в которое приложение желает запросить оценку освещенности.

Допустимое использование (неявное)

Структура XrLightEstimateANDROID содержит данные оценки освещенности.

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

Описания участников

Чтобы получить информацию об оценке освещенности для окружающего освещения, сферических гармоник и основного направленного света, приложения могут связывать экземпляры следующих структур: XrAmbientLightANDROID , XrSphericalHarmonicsANDROID и XrDirectionalLightANDROID соответственно с XrLightEstimateANDROID::next .

Допустимое использование (неявное)

Структура XrAmbientLightANDROID содержит данные оценки освещенности об окружающем освещении в сцене.

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

Описания участников

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Допустимые структуры: XrSphericalHarmonicsANDROID и XrDirectionalLightANDROID .
  • state — это XrLightEstimateStateANDROID, представляющий состояние оценки освещенности.
  • intensity — это XrVector3 представляющий интенсивность окружающего света. Каждый компонент вектора соответствует красному, зеленому и синему каналам.
  • colorCorrection — это XrVector3 со значениями в гамма-пространстве. Покомпонентно умножьте цвет вашего гамма-рендера на эти значения.

Допустимое использование (неявное)

Структура XrSphericalHarmonicsANDROID содержит сферические гармоники, представляющие освещение сцены. 

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

Описания участников

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Допустимые структуры: XrAmbientLightANDROID и XrDirectionalLightANDROID .
  • state — это XrLightEstimateStateANDROID, представляющий состояние оценки освещенности.
  • kind — это XrSphericalHarmonicsKindANDROID , запрошенный приложением.
  • coefficients — это двумерный массив с float размером 9 строк и 3 столбца. Три столбца соответствуют цветовым каналам: красному, зеленому и синему соответственно. Каждый канал имеет 9 коэффициентов сферических гармоник.

Допустимое использование (неявное)

Структура XrDirectionalLightANDROID содержит данные оценки освещенности. 

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

Описания участников

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Допустимые структуры: XrAmbientLightANDROID , XrSphericalHarmonicsANDROID и XrDirectionalLightANDROID .
  • state — это XrLightEstimateStateANDROID, представляющий состояние оценки освещенности.
  • intensity — это XrVector3 представляющий интенсивность направленного света. Каждый компонент вектора соответствует красному, зеленому и синему каналам.
  • direction — это XrVector3 представляющий направление света.

Допустимое использование (неявное)

Перечисление XrSphericalHarmonicsKindANDROID определяет для среды выполнения, какой тип сферических гармоник запрашивает приложение. 

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

Перечисления имеют следующие значения:

Перечисление

Описание

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Коэффициенты сферических гармоник представляют собой функцию освещенности окружающей среды без учета вклада основного света.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Коэффициенты сферических гармоник представляют собой функцию освещенности окружающей среды, включая вклад основного света.

Перечисление XrLightEstimateStateANDROID определяет для среды выполнения, какой тип сферических гармоник запрашивает приложение. 

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

Перечисления имеют следующие значения:

Перечисление

Описание

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Оценка освещенности действительна

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Оценка освещенности недействительна.

Пример кода для оценки освещенности

В следующем примере кода показано, как получить все возможные величины оценки освещенности во время выполнения. 

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

Новые типы объектов

  • XrLightEstimator

Перечисление XrObjectType расширено:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Перечисление XrStructureType расширено:

  • 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

Новые перечисления

Новые структуры

Новые функции

Проблемы

История версий

  • Редакция 1, 16 сентября 2024 г. (Cairn Overturf)
    • Первоначальное описание расширения