XR_ANDROID_light_estimation_cubemap
이름 문자열
XR_ANDROID_light_estimation_cubemap
확장 프로그램 유형
인스턴스 확장
등록된 내선 번호
722
버전
1
비준 상태
비준되지 않음
확장 프로그램 및 버전 종속 항목
XR_ANDROID_light_estimation
최종 수정일
2025-08-06
IP 상태
알려진 IP 소유권 주장이 없습니다.
도움을 주신 분들
Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google
개요
이 확장 프로그램은 기본 XR_ANDROID_light_estimation 확장 프로그램을 기반으로 합니다. 큐브맵 조명 추정치를 가져오는 지원을 추가하여 실제 환경의 조명에 관한 더 자세한 추정치를 제공합니다.
참고
조명 추정 데이터 가져오기 메커니즘은 기본 확장 프로그램과 동일합니다. 단, 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID를 XrLightEstimatorCreateInfoANDROID에 연결해야 합니다.
시스템 기능 검사
typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.supportsCubemapLightEstimation는 현재 시스템이 큐브맵 조명 추정을 지원하는지 여부를 나타내는XrBool32입니다.
애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemCubemapLightEstimationPropertiesANDROID 구조로 XrSystemProperties를 확장하여 시스템이 큐브맵 조명 추정을 지원할 수 있는지 검사할 수 있습니다 .
런타임이 supportsCubemapLightEstimation에 대해 XR_FALSE를 반환하고 XrCubemapLightEstimatorCreateInfoANDROID가 XrLightEstimatorCreateInfoANDROID에 연결된 경우 런타임은 xrCreateLightEstimatorANDROID에서 XR_ERROR_FEATURE_UNSUPPORTED을 반환해야 합니다 .
유효한 사용 (암시적)
- XrSystemCubemapLightEstimationPropertiesANDROID를 사용하기 전에
XR_ANDROID_light_estimation_cubemap확장 프로그램을 사용 설정해야 합니다. -
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는 지원되는 큐브맵 해상도를 가져올 이전에 xrGetSystem으로 가져온XrSystemId입니다.resolutionCapacityInput는resolutions배열에 저장할 수 있는 최대 요소 수를 나타내는uint32_t입니다.resolutionCountOutput는 런타임에 의해 설정된uint32_t에 대한 포인터로, 런타임에 의해resolutions배열에 기록된 요소의 수를 나타냅니다.resolutions은 런타임에서 지원되는 큐브맵 해상도로 채워지는uint32_t배열입니다.
큐브맵 해상도는 큐브맵의 각 면의 너비와 높이를 픽셀 단위로 나타냅니다. 2 호출 관용구 그러면 애플리케이션은 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution에서 지원되는 해상도 중 하나를 사용하도록 선택할 수 있습니다. 애플리케이션은 선택한 해상도와 색상 형식을 기반으로 XrCubemapLightingDataANDROID의 이미지 버퍼 멤버에 적절한 메모리 양을 할당해야 합니다.
유효한 사용 (암시적)
- xrEnumerateCubemapLightingResolutionsANDROID를 호출하기 전에
XR_ANDROID_light_estimation_cubemap확장 프로그램을 사용 설정해야 합니다. -
instance은 유효한 XrInstance 핸들이어야 합니다. -
resolutionCountOutput은uint32_t값에 대한 포인터여야 합니다. -
resolutionCapacityInput이0이 아닌 경우resolutions은resolutionCapacityInputuint32_t값의 배열을 가리키는 포인터여야 합니다.
반환 코드
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_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
각 채널이 32비트 부동 소수점 값인 3채널 색상 형식입니다.
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID
각 채널이 32비트 부동 소수점 값인 4채널 색상 형식입니다.
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID
각 채널이 16비트 부동 소수점 값인 4채널 색상 형식입니다.
XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
XrInstance instance,
XrSystemId systemId,
uint32_t colorFormatCapacityInput,
uint32_t* colorFormatCountOutput,
XrCubemapLightingColorFormatANDROID* colorFormats);
매개변수 설명
instance은 이전에 생성된 XrInstance입니다.systemId는 지원되는 큐브맵 해상도를 가져올 이전에 xrGetSystem으로 가져온XrSystemId입니다.colorFormatCapacityInput는colorFormats배열에 저장할 수 있는 최대 요소 수를 나타내는uint32_t입니다.colorFormatCountOutput는 런타임에 의해 설정된uint32_t에 대한 포인터로, 런타임에 의해colorFormats배열에 기록된 요소의 수를 나타냅니다.colorFormats는 런타임에서 지원되는 큐브맵 색상 형식으로 채워지는 XrCubemapLightingColorFormatANDROID 배열입니다.
2 호출 관용구 그러면 애플리케이션은 조명 추정기 핸들을 생성할 때 XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat에서 지원되는 색상 형식 중 하나를 사용하도록 선택할 수 있습니다. 애플리케이션은 선택한 색상 형식을 기반으로 XrCubemapLightingDataANDROID의 이미지 버퍼 멤버에 적절한 메모리 양을 할당해야 합니다.
유효한 사용 (암시적)
- xrEnumerateCubemapLightingColorFormatsANDROID를 호출하기 전에
XR_ANDROID_light_estimation_cubemap확장 프로그램을 사용 설정해야 합니다. -
instance은 유효한 XrInstance 핸들이어야 합니다. -
colorFormatCountOutput은uint32_t값에 대한 포인터여야 합니다. -
colorFormatCapacityInput이0이 아닌 경우colorFormats은colorFormatCapacityInputXrCubemapLightingColorFormatANDROID 값의 배열에 대한 포인터여야 합니다.
반환 코드
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_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에서 반환된 색상 형식 중 하나로 설정해야 합니다 . 애플리케이션이 지원되는 해상도 중 하나로 해상도를 설정하지 않거나 지원되는 색상 형식 중 하나로 색상 형식을 설정하지 않으면 런타임은 xrCreateLightEstimatorANDROID에서 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다 .
유효한 사용 (암시적)
-
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에 연결할 수 있습니다 . 런타임은 XrCubemapLightEstimatorCreateInfoANDROID가 조명 추정기 핸들을 만드는 데 사용된 경우에만 xrGetLightEstimateANDROID에서 이 구조체를 채워야 합니다. 애플리케이션은 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution 및 XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat에 설정된 값에 따라 이미지 버퍼에 적절한 양의 메모리를 할당해야 합니다. 애플리케이션은 XrCubemapLightingDataANDROID :: imageBufferSize을 각 얼굴 이미지 버퍼의 용량(바이트)으로 설정해야 합니다. 애플리케이션이 큐브맵 조명 추정을 사용하지 않거나 XrCubemapLightingDataANDROID :: imageBufferSize가 런타임이 이미지 버퍼를 채우기에 충분하지 않은 경우 런타임은 XrCubemapLightingDataANDROID :: state을 XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID로 설정해야 합니다 .
애플리케이션이 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID :: reproject을 XR_TRUE로 설정하면 런타임은 XrCubemapLightingDataANDROID :: rotation을 ID 회전으로 설정하고 내부 회전된 큐브맵이 애플리케이션 기본 공간의 ID 큐브맵 면에 다시 투영되도록 해야 합니다.
조명 큐브맵의 레이아웃은 다음 이미지와 같이 OpenGL 큐브맵 레이아웃과 동일합니다.
그림 24. 큐브맵 레이아웃입니다.
유효한 사용 (암시적)
- XrCubemapLightingDataANDROID를 사용하기 전에
XR_ANDROID_light_estimation_cubemap확장 프로그램을 사용 설정해야 합니다. -
type은XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID이어야 합니다. -
next은NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다. -
state은(는) 유효한 XrLightEstimateStateANDROID 값이어야 합니다. -
imageBufferRight은imageBufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
imageBufferLeft은imageBufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
imageBufferTop은imageBufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
imageBufferBottom은imageBufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
imageBufferFront은imageBufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
imageBufferBack은imageBufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
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));
새 명령어
새 구조
XrSystemProperties 확장 :
새 열거형
새 열거형 상수
XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAMEXR_ANDROID_light_estimation_cubemap_SPEC_VERSIONXrStructureType 확장 :
XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROIDXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID
문제
버전 기록
버전 1, 2025년 12월 5일 (Salar Khan)
- 초기 확장 프로그램 설명