Android XR for OpenXR | Android Developers

Android XR SDK достиг версии Developer Preview 3 , и нам важно ваше мнение! Попробуйте и посетите нашу страницу поддержки , чтобы связаться с нами.

Эта страница переведена с помощью Cloud Translation API.

XR_ANDROID_light_estimation_cubemap

Строка имени

XR_ANDROID_light_estimation_cubemap

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

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

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

722

Пересмотр

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

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

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

XR_ANDROID_light_estimation

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

2025-08-06

Статус IP

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

Авторы

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

Обзор

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

Примечание

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

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

typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;

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

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

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

Если среда выполнения возвращает XR_FALSE для supportsCubemapLightEstimation и XrCubemapLightEstimatorCreateInfoANDROID связана с XrLightEstimatorCreateInfoANDROID , среда выполнения должна вернуть XR_ERROR_FEATURE_UNSUPPORTED из xrCreateLightEstimatorANDROID .

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

Расширение XR_ANDROID_light_estimation_cubemap необходимо включить перед использованием XrSystemCubemapLightEstiminationPropertiesANDROID.
type должен быть XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.

Получение информации о поддерживаемых разрешениях кубических карт

XrResult xrEnumerateCubemapLightingResolutionsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    uint32_t*                                   resolutions);

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

instance — это экземпляр XrInstance , созданный ранее.
systemId — это идентификатор XrSystemId полученный ранее с помощью xrGetSystem , для которого необходимо узнать поддерживаемые разрешения кубической карты.
resolutionCapacityInput — это тип данных uint32_t , указывающий максимальное количество элементов, которые могут храниться в массиве resolutions .
resolutionCountOutput — это указатель на тип uint32_t , который устанавливается средой выполнения и указывает количество элементов, записанных средой выполнения в массив resolutions .
resolutions — это массив типов uint32_t , который заполняется средой выполнения поддерживаемыми разрешениями кубических карт.

Разрешение кубической карты указывает ширину и высоту каждой грани кубической карты в пикселях. Идиома 2-вызова. Затем приложение может выбрать одно из поддерживаемых разрешений в XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution при создании дескриптора оценки освещения. Приложение должно выделить соответствующий объем памяти для членов буфера изображения XrCubemapLightingDataANDROID в зависимости от выбранного разрешения и формата цвета.

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

Расширение XR_ANDROID_light_estimation_cubemap необходимо включить перед вызовом функции xrEnumerateCubemapLightingResolutionsANDROID.
instance должен быть допустимым дескриптором XrInstance.
resolutionCountOutput должен быть указателем на значение типа uint32_t
Если resolutionCapacityInput не равно 0 , resolutions должно быть указателем на массив значений типа uint32_t , содержащих resolutionCapacityInput .

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

Успех

XR_SUCCESS

Отказ

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

Получение информации о поддерживаемых форматах цветов кубических карт

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

typedef enum XrCubemapLightingColorFormatANDROID {
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID = 1,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID = 2,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID = 3,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrCubemapLightingColorFormatANDROID;

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

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

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Цветовой формат с 3 каналами, где каждый канал представляет собой 32-битное значение с плавающей запятой.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Цветовой формат с 4 каналами, где каждый канал представляет собой 32-битное значение с плавающей запятой.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Цветовой формат с 4 каналами, где каждый канал представляет собой 16-битное значение с плавающей запятой.

XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    colorFormatCapacityInput,
    uint32_t*                                   colorFormatCountOutput,
    XrCubemapLightingColorFormatANDROID*        colorFormats);

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

instance — это экземпляр XrInstance , созданный ранее.
systemId — это идентификатор XrSystemId полученный ранее с помощью xrGetSystem , для которого необходимо узнать поддерживаемые разрешения кубической карты.
colorFormatCapacityInput — это тип uint32_t , указывающий максимальное количество элементов, которые могут быть сохранены в массиве colorFormats .
colorFormatCountOutput — это указатель на тип uint32_t , устанавливаемый средой выполнения и указывающий количество элементов, записанных средой выполнения в массив colorFormats .
colorFormats — это массив объектов XrCubemapLightingColorFormatANDROID , который заполняется средой выполнения поддерживаемыми форматами цветов кубических карт.

Идиома 2-вызова. Затем приложение может выбрать один из поддерживаемых форматов цвета в XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat при создании дескриптора оценки освещенности. Приложение должно выделить соответствующий объем памяти для членов буфера изображения XrCubemapLightingDataANDROID в зависимости от выбранного формата цвета.

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

Расширение XR_ANDROID_light_estimation_cubemap необходимо включить перед вызовом функции xrEnumerateCubemapLightingColorFormatsANDROID.
instance должен быть допустимым дескриптором XrInstance.
colorFormatCountOutput должен быть указателем на значение типа uint32_t
Если colorFormatCapacityInput не равен 0 , colorFormats должен быть указателем на массив значений colorFormatCapacityInput XrCubemapLightingColorFormatANDROID.

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

Успех

XR_SUCCESS

Отказ

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
    XrStructureType                        type;
    const void*                            next;
    uint32_t                               cubemapResolution;
    XrCubemapLightingColorFormatANDROID    colorFormat;
    XrBool32                               reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;

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

type — это XrStructureType данной структуры.
next — это NULL или указатель на следующую структуру в цепочке структур.
cubemapResolution — это тип данных uint32_t , указывающий разрешение освещения кубической карты, которое следует использовать.
colorFormat — это объект XrCubemapLightingColorFormatANDROID , указывающий формат цвета данных освещения кубической карты, который следует использовать.
reproject имеет тип XrBool32 и указывает, следует ли перепроецировать освещение кубической карты в базовое пространство приложения.

Структура XrCubemapLightEstimatorCreateInfoANDROID описывает информацию, необходимую для создания дескриптора XrLightEstimatorANDROID , способного предоставлять оценки освещения кубической карты. Член XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution должен быть установлен на одно из разрешений, возвращаемых функцией xrEnumerateCubemapLightingResolutionsANDROID . Член XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat должен быть установлен на один из цветовых форматов, возвращаемых функцией xrEnumerateCubemapLightingColorFormatsANDROID . Если приложение не устанавливает разрешение на одно из поддерживаемых разрешений или цветовой формат на один из поддерживаемых цветовых форматов, среда выполнения должна вернуть XR_ERROR_FEATURE_UNSUPPORTED из xrCreateLightEstimatorANDROID .

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

Расширение XR_ANDROID_light_estimation_cubemap необходимо включить перед использованием XrCubemapLightEstimatorCreateInfoANDROID.
type должен быть XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
colorFormat должно быть допустимым значением XrCubemapLightingColorFormatANDROID.

Оценки освещенности по кубической карте

typedef struct XrCubemapLightingDataANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    uint32_t                       imageBufferSize;
    uint8_t*                       imageBufferRight;
    uint8_t*                       imageBufferLeft;
    uint8_t*                       imageBufferTop;
    uint8_t*                       imageBufferBottom;
    uint8_t*                       imageBufferFront;
    uint8_t*                       imageBufferBack;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrCubemapLightingDataANDROID;

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

type — это XrStructureType данной структуры.
next — это NULL или указатель на следующую структуру в цепочке структур. Допустимые структуры: XrAmbientLightANDROID , XrSphericalHarmonicsANDROID , XrDirectionalLightANDROID .
state объекта XrLightEstimateStateANDROID отражает состояние оценки освещенности.
imageBufferSize — это тип данных uint32_t , указывающий размер в байтах каждого буфера изображения лица в кубической карте.
imageBufferRight — это буфер uint8_t , содержащий изображение правой грани кубической карты.
imageBufferLeft — это буфер uint8_t , содержащий изображение левой грани кубической карты.
imageBufferTop — это буфер uint8_t , содержащий изображение верхней грани кубической карты.
imageBufferBottom — это буфер uint8_t , содержащий изображение нижней грани кубической карты.
imageBufferFront — это буфер uint8_t , содержащий изображение лицевой стороны кубической карты.
imageBufferBack — это буфер uint8_t , содержащий изображение обратной стороны кубической карты.
rotation — это XrQuaternionf, указывающий на вращение кубической карты.
centerExposureTime — это объект XrTime , указывающий время захвата кубической карты.

Эта структура может быть связана с XrLightEstimateANDROID . Среда выполнения должна заполнять эту структуру в xrGetLightEstimateANDROID только в том случае, если для создания дескриптора оценки освещения использовался XrCubemapLightEstimatorCreateInfoANDROID . Приложение должно выделить соответствующий объем памяти для буферов изображений, который зависит от значений, установленных в XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution и XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat при создании дескриптора оценки освещения. Приложение должно установить XrCubemapLightingDataANDROID :: imageBufferSize равным емкости каждого буфера изображения лица в байтах. Если приложение не использует оценку освещения с помощью кубической карты или если значение XrCubemapLightingDataANDROID :: imageBufferSize недостаточно велико для заполнения буферов изображений средой выполнения, среда выполнения должна установить значение XrCubemapLightingDataANDROID :: state в XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .

Если приложение при создании дескриптора оценщика освещения устанавливает значение XrCubemapLightEstimatorCreateInfoANDROID :: reproject равным XR_TRUE , среда выполнения должна установить значение XrCubemapLightingDataANDROID :: rotation равным идентичному вращению и обеспечить перепроецирование внутренней повернутой кубической карты на грани идентичной кубической карты в базовом пространстве приложения.

Расположение кубической карты освещения аналогично расположению кубической карты в OpenGL, как показано на следующем изображении.

XR ANDROID оценка освещенности кубическая карта макета

Рисунок 24. Макет кубической карты.

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

Расширение XR_ANDROID_light_estimation_cubemap необходимо включить перед использованием XrCubemapLightingDataANDROID.
type должен быть XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
state должно быть допустимым значением XrLightEstimateStateANDROID.
imageBufferRight должен быть указателем на массив значений uint8_t , содержащих imageBufferSize .
imageBufferLeft должен быть указателем на массив значений uint8_t , содержащих imageBufferSize .
imageBufferTop должен быть указателем на массив значений uint8_t , содержащих imageBufferSize .
imageBufferBottom должен быть указателем на массив значений uint8_t , содержащих imageBufferSize .
imageBufferFront должен быть указателем на массив значений uint8_t , содержащих imageBufferSize .
imageBufferBack должен быть указателем на массив значений uint8_t , содержащих imageBufferSize .
Параметр imageBufferSize должен быть больше 0

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

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

XrSession session;  // Created at app startup
XrInstance instance; // Created at app startup
XrSpace appSpace;   // Created previously.
XrSystemId systemId; // Retrieved previously by xrGetSystem
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingResolutionsANDROID xrEnumerateCubemapLightingResolutionsANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingColorFormatsANDROID xrEnumerateCubemapLightingColorFormatsANDROID; // Created previously.

XrSystemCubemapLightEstimationPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID};
XrSystemProperties base = {.type = XR_TYPE_SYSTEM_PROPERTIES,
                           .next = &props};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));
if (!props.supportsCubemapLightEstimation) {
   // Cubemap light estimation is not supported
}

uint32_t cubemapResolution = 0;
std::vector<uint32_t> supportedCubemapResolutions;
uint32_t resolutionCount;
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
  instance, systemId, 0, &resolutionCount, nullptr));
supportedCubemapResolutions.resize(resolutionCount);
if (resolutionCount == 0) {
  // No cubemap lighting supported
} else {
  CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
    instance, systemId, 0, &resolutionCount, supportedCubemapResolutions.data()));
  cubemapResolution = supportedCubemapResolutions[0];
}

uint32_t pixelCount = cubemapResolution * cubemapResolution;

XrCubemapLightingColorFormatANDROID colorFormat;
std::vector<XrCubemapLightingColorFormatANDROID> supportedColorFormats;
uint32_t colorFormatCount;
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
  instance, systemId, 0, &colorFormatCount, nullptr));
supportedColorFormats.resize(colorFormatCount);
if (colorFormatCount == 0) {
  // No supported color formats for cubemap lighting. Cannot use cubemap
  // light estimation.
} else {
  CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
    instance, systemId, 0, &colorFormatCount, supportedColorFormats.data()));
  colorFormat = supportedColorFormats[0];
}

uint32_t pixelSize = 0;
switch (colorFormat) {
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID:
    pixelSize = 3 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(uint16_t);
    break;
  default:
    // Should not happen since the color format was validated previously.
    break;
}

uint32_t perFaceImageBufferSize = pixelCount * pixelSize;

XrLightEstimatorANDROID estimator;
XrCubemapLightEstimatorCreateInfoANDROID cubemapCreateInfo = {
    .type = XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .cubemapResolution = cubemapResolution,
    .colorFormat = colorFormat,
    .reproject = XR_TRUE
};
XrLightEstimatorCreateInfoANDROID basicCreateInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .next = &cubemapCreateInfo};
CHK_XR(xrCreateLightEstimatorANDROID(session, &basicCreateInfo, &estimator));

std::vector<uint8_t> cubemapBuffer(perFaceImageBufferSize * 6); // 6 faces * perFaceImageBufferSize

// 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,
};

XrCubemapLightingDataANDROID cubemap = {
    .type = XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID,
    .next = nullptr,
    .imageBufferSize = perFaceImageBufferSize,
    .imageBufferRight = cubemapBuffer.data() + 0 * perFaceImageBufferSize,
    .imageBufferLeft = cubemapBuffer.data() + 1 * perFaceImageBufferSize,
    .imageBufferTop = cubemapBuffer.data() + 2 * perFaceImageBufferSize,
    .imageBufferBottom = cubemapBuffer.data() + 3 * perFaceImageBufferSize,
    .imageBufferFront = cubemapBuffer.data() + 4 * perFaceImageBufferSize,
    .imageBufferBack = cubemapBuffer.data() + 5 * perFaceImageBufferSize,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
    .next = &cubemap,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &totalSh,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
};

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 cubemap, directionalLight, totalSh, ambientSh, and
  // ambientLight if each struct has a valid state field

  if (cubemap.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
    // use cubemap
    if (cubemapCreateInfo.reproject == XR_TRUE) {
      XrQuaternionf identityQuaternion = {0.0f, 0.0f, 0.0f, 1.0f};
      assert(memcmp(&cubemap.rotation, &identityQuaternion, sizeof(XrQuaternionf)) == 0);
    }
  }
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

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

xrEnumerateCubemapLightingColorFormatsANDROID
xrEnumerateCubemapLightingResolutionsANDROID

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

Расширение XrLightEstimateANDROID :
- XrCubemapLightingDataANDROID
Расширение XrLightEstimatorCreateInfoANDROID :
- XrCubemapLightEstimatorCreateInfoANDROID
Расширение XrSystemProperties :
- XrSystemCubemapLightEtimationPropertiesANDROID

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

XrCubemapLightingColorFormatANDROID

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

XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
XR_ANDROID_light_estimation_cubemap_SPEC_VERSION
Расширение XrStructureType :
- XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
- XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
- XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Проблемы

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

Редакция 1, 05.12.2025 (Салар Хан)
- Первоначальное описание расширения