XR_ANDROID_light_estimation

Строка имени

XR_ANDROID_light_estimation

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

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

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

701

Пересмотр

1

Статус ратификации

Не ратифицировано

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

OpenXR 1.0

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

2025-03-13

Статус IP

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

Авторы

Джаред Финдер, Google
Кэрн Овертурф, Google
Спенсер Куин, Google
Левана Чен, Google
Нихав Джайн, Google
Салар Хан, Google
Скотт Чанг, Google

Обзор

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

Разрешения

В манифесте Android-приложений должно быть указано разрешение android.permission.SCENE_UNDERSTANDING_COARSE, поскольку это расширение предоставляет информацию об освещении окружающей среды. Разрешение android.permission.SCENE_UNDERSTANDING_COARSE считается опасным. Приложение должно запрашивать это разрешение во время выполнения, чтобы использовать следующие функции:

(Уровень защиты: опасный)

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

Структура XrSystemLightEstiminationPropertiesANDROID определяется следующим образом: 

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

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

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

Приложение может проверить, способна ли система поддерживать оценку освещенности, расширив структуру XrSystemProperties с помощью XrSystemLightEstiminationPropertiesANDROID при вызове функции 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 для создания инструмента оценки освещенности.

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

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

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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

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

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

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

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

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

Функция xrDestroyLightEstimatorANDROID определена следующим образом: 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

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

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

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

  • Расширение XR_ANDROID_light_estimation необходимо включить перед вызовом функции xrDestroyLightEstimatorANDROID.
  • estimator должен быть действительным идентификатором XrLightEstimatorANDROID.

Безопасность резьбы

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

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

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

Функция xrGetLightEstimateANDROID определена следующим образом: 

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

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

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

  • Расширение XR_ANDROID_light_estimation необходимо включить перед вызовом функции xrGetLightEstimateANDROID.
  • estimator должен быть действительным идентификатором XrLightEstimatorANDROID.
  • input должны представлять собой указатель на допустимую структуру XrLightEstimateGetInfoANDROID.
  • output должны представлять собой указатель на структуру XrLightEstimateANDROID.

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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

Структура XrLightEstimateGetInfoANDROID определяется следующим образом: 

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

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

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

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

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

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

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

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

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

Для получения информации об оценке освещенности для окружающего света, сферических гармоник и основного направленного света приложения могут объединять экземпляры следующих структур: 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 — это объект XrVector3f, представляющий интенсивность окружающего света. Каждая компонента вектора соответствует красному, зеленому и синему каналам соответственно.

  • colorCorrection — это объект XrVector3f со значениями в гамма-пространстве. При рендеринге в гамма-пространстве значения умножаются поэлементно на итоговый вычисленный цвет после рендеринга. При рендеринге в линейном пространстве значения сначала преобразуются в линейное пространство путем возведения в степень 2,2, а затем умножаются поэлементно на итоговый вычисленный цвет после рендеринга. 

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

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

Структура 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 коэффициентов сферических гармоник.

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

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

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

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;

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

Описание перечисления

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

Структура 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 представляет собой вектор XrVector3f, отображающий интенсивность направленного света. Каждая компонента вектора соответствует красному, зеленому и синему каналам.
  • direction — это объект XrVector3f, представляющий направление света.

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

Перечисление XrLightEstimateStateANDROID указывает состояние оценки освещенности, возвращаемой средой выполнения. 

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;

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

Описание перечисления

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Оценка освещенности верна.

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Оценка освещенности неверна.

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

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

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

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

Новые команды

Новые сооружения

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

Новые константы перечислений

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Расширение XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Расширение 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

Проблемы

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

  • Редакция 1, 16.09.2024 (Cairn Overturf)

    • Первоначальное описание расширения