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를 반환해야 합니다(must).
올바른 사용 (암시적)
- XrSystemCubemapLightEstimationPropertiesANDROID를 사용하기 전에
XR_ANDROID_light_estimation_cubemap확장 프로그램을 사용 설정해야 합니다(must). -
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는 런타임에 의해resolutions배열에 작성된 요소의 수를 나타내는 런타임에 의해 설정된uint32_t에 대한 포인터입니다.resolutions는 지원되는 큐브맵 해상도로 런타임에 의해 채워지는uint32_t의 배열입니다.
큐브맵 해상도는 큐브맵의 각 면의 너비와 높이를 픽셀 단위로 나타냅니다. 2-call idiom 그런 다음 애플리케이션은 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution에서 지원되는 해상도 중 하나를 사용하도록 선택할 수 있습니다. 애플리케이션은 선택한 해상도와 색상 형식에 따라 XrCubemapLightingDataANDROID의 이미지 버퍼 멤버에 적절한 양의 메모리를 할당해야 합니다(must).
올바른 사용 (암시적)
-
XR_ANDROID_light_estimation_cubemap확장 프로그램은 xrEnumerateCubemapLightingResolutionsANDROID를 호출하기 전에 사용 설정해야 합니다. -
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;
enum의 의미는 다음과 같습니다.
enum 설명
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는 런타임에 의해colorFormats배열에 작성된 요소의 수를 나타내는 런타임에 의해 설정된uint32_t에 대한 포인터입니다.colorFormats는 XrCubemapLightingColorFormatANDROID의 배열로, 지원되는 큐브맵 색상 형식으로 런타임에 의해 채워집니다.
2-call idiom 그런 다음 애플리케이션은 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat에서 지원되는 색상 형식 중 하나를 사용하도록 선택할 수 있습니다. 애플리케이션은 선택한 색상 형식에 따라 XrCubemapLightingDataANDROID의 이미지 버퍼 멤버에 적절한 양의 메모리를 할당해야 합니다(MUST).
올바른 사용 (암시적)
-
XR_ANDROID_light_estimation_cubemap확장 프로그램은 xrEnumerateCubemapLightingColorFormatsANDROID를 호출하기 전에 사용 설정해야 합니다. -
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를 반환해야 합니다(MUST).
올바른 사용 (암시적)
- XrCubemapLightEstimatorCreateInfoANDROID를 사용하기 전에
XR_ANDROID_light_estimation_cubemap확장 프로그램을 사용 설정해야 합니다. -
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를 각 면 이미지 버퍼의 용량(바이트)으로 설정해야 합니다(must). 애플리케이션이 큐브맵 조명 추정을 사용하지 않거나 XrCubemapLightingDataANDROID :: imageBufferSize가 런타임에서 이미지 버퍼를 채우기에 충분하지 않은 경우 런타임은 XrCubemapLightingDataANDROID :: state를 XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID로 설정해야 합니다(must).
애플리케이션이 조명 추정기 핸들을 만들 때 XrCubemapLightEstimatorCreateInfoANDROID :: reproject를 XR_TRUE로 설정한 경우 런타임은 XrCubemapLightingDataANDROID :: rotation를 ID 회전으로 설정하고 내부 회전 큐브맵이 애플리케이션 기본 공간의 ID 큐브맵 면에 다시 투영되도록 해야 합니다.
조명 큐브맵의 레이아웃은 다음 이미지와 같이 OpenGL 큐브맵 레이아웃과 동일합니다.
그림 31. 큐브맵 레이아웃
올바른 사용 (암시적)
- 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));
새 명령어
새로운 구조
새 enum
새 enum 상수
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-05 (살라르 칸)
- 초기 확장 프로그램 설명