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

Имя Строка

XR_ANDROID_light_estimation

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

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

Зарегистрированный добавочный номер

701

Пересмотр

1

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

OpenXR 1.0

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

2025-01-17

Статус ИС

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

Участники

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

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

Спенсер Куин, 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;

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

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

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

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

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;

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

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Допустимые структуры — XrSphericalHarmonicsANDROID , XrAmbientLightANDROID и XrDirectionalLightANDROID .
  • state — XrLightEstimateStateANDROID , представляющее состояние оценки освещенности.
  • cubemapRightImage — это float* представляющий буфер R32G32B32_SFLOAT правой стороны кубической карты. Обратите внимание, что это HDR, поэтому значения float могут быть больше 1,0.
  • cubemapLeftImage — это float* представляющий буфер R32G32B32_SFLOAT левой стороны кубической карты. Обратите внимание, что это HDR, поэтому значения float могут быть больше 1,0.
  • cubemapTopImage — это float* представляющий буфер R32G32B32_SFLOAT верхней стороны кубической карты. Обратите внимание, что это HDR, поэтому значения float могут быть больше 1,0.
  • cubemapBottomImage — это float* представляющий буфер R32G32B32_SFLOAT нижней стороны кубической карты. Обратите внимание, что это HDR, поэтому значения float могут быть больше 1,0.
  • cubemapFrontImage — это float* представляющий буфер R32G32B32_SFLOAT передней стороны кубической карты. Обратите внимание, что это HDR, поэтому значения float могут быть больше 1,0.
  • resolution — это uint32_t представляющее ширину и высоту изображения каждой стороны кубической карты. Обратите внимание, что это HDR, поэтому значения float могут быть больше 1,0.
  • rotation — это XrQuaternionf, представляющий вращение кубической карты.
  • centerExposureTime — это XrTime , представляющий время захвата кубической карты. Полезно для интерполяции между кубическими картами.

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

  • Расширение XR_ANDROID_light_estimation должно быть включено перед использованием XrEnvironmentLightingCubemapANDROID
  • type должен быть XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next должен быть NULL или действительным указателем на следующую структуру в цепочке структур
  • state должен быть допустимым значением XrLightEstimateStateANDROID
  • cubemapRightImage должен быть указателем на допустимое значение с плавающей точкой
  • cubemapLeftImage должен быть указателем на допустимое значение с плавающей точкой
  • cubemapTopImage должен быть указателем на допустимое значение с плавающей точкой
  • cubemapBottomImage должен быть указателем на допустимое значение с плавающей точкой
  • cubemapFrontImage должен быть указателем на допустимое значение с плавающей точкой
  • cubemapBackImage должен быть указателем на допустимое значение с плавающей точкой

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

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

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

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Допустимые структуры — XrSphericalHarmonicsANDROID , XrEnvironmentLightingCubemapANDROID и 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 , XrEnvironmentLightingCubemapANDROID и XrDirectionalLightANDROID .
  • state — XrLightEstimateStateANDROID , представляющее состояние оценки освещенности.
  • kind — это XrSphericalHarmonicsKindANDROID , запрошенный приложением.
  • coefficients — это двумерный массив float с размерами 9 строк и 3 столбцов. 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,
};


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

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

  • 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
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

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

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

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

Проблемы

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

  • Редакция 2, 2025-01-17 (Салар Хан)
    • Добавлена ​​поддержка кубической карты освещения окружающей среды.
  • Редакция 1, 2024-09-16 (Cairn Overturf)
    • Первоначальное описание расширения

OpenXR™ и логотип OpenXR являются товарными знаками компании Khronos Group Inc. и зарегистрированы в качестве товарного знака в Китае, Европейском Союзе, Японии и Великобритании.