XR_ANDROID_light_estimation OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_light_estimation

확장 프로그램 유형

인스턴스 확장

등록된 내선 번호

701

버전

1

확장 프로그램 및 버전 종속 항목

OpenXR 1.0

최종 수정일

2025-01-17

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

Jared Finder, Google

케언 오버터프, Google

스펜서 퀸, Google

레바나 첸, Google

니하브 제인, Google

Salar Khan, Google

스콧 청, Google

개요

이 확장 프로그램을 사용하면 애플리케이션이 헤드셋 주변의 실제 환경 조명을 나타내는 데이터를 요청할 수 있습니다. 이 정보는 가상 객체를 렌더링하여 배치된 장면과 동일한 조건에서 조명을 비추는 데 사용할 수 있습니다.

시스템 기능 검사

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemLightEstimationPropertiesANDROID 구조를 XrSystemProperties에 연결하여 시스템이 조명 추정을 지원하는지 검사할 수 있습니다. 

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

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.
  • supportsLightEstimation은 현재 시스템이 조명 추정을 지원하는지 나타내는 XrBool32입니다.

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemLightEstimationPropertiesANDROID 구조로 XrSystemProperties를 확장하여 시스템이 조명 추정을 지원할 수 있는지 검사할 수 있습니다.

시스템에서 조명 추정을 지원할 수 없는 경우 supportsLightEstimation에 XR_FALSE를 반환하고 xrCreateLightEstimatorANDROID에서 XR_ERROR_FEATURE_UNSUPPORTED를 반환합니다.

유효한 사용 (암시적)

조명 추정기 핸들 만들기

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

XrLightEstimatorANDROID 핸들은 조명 추정기를 나타냅니다. 이 핸들을 사용하여 이 확장 프로그램의 다른 함수를 통해 조명 추정 정보에 액세스할 수 있습니다.

xrCreateLightEstimatorANDROID 함수는 다음과 같이 정의됩니다. 

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

매개변수 설명

애플리케이션은 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는 큐브맵의 오른쪽 R32G32B32_SFLOAT 버퍼를 나타내는 float*입니다. HDR이므로 부동 소수점 값이 1.0보다 클 수 있습니다.
  • cubemapLeftImage은 큐브 맵의 왼쪽 R32G32B32_SFLOAT 버퍼를 나타내는 float*입니다. HDR이므로 부동 소수점 값이 1.0보다 클 수 있습니다.
  • cubemapTopImage는 큐브맵의 상단 측면의 R32G32B32_SFLOAT 버퍼를 나타내는 float*입니다. HDR이므로 부동 소수점 값이 1.0보다 클 수 있습니다.
  • cubemapBottomImage는 큐브맵의 하단 측면의 R32G32B32_SFLOAT 버퍼를 나타내는 float*입니다. HDR이므로 부동 소수점 값이 1.0보다 클 수 있습니다.
  • cubemapFrontImage은 큐브맵 앞면의 R32G32B32_SFLOAT 버퍼를 나타내는 float*입니다. HDR이므로 부동 소수점 값이 1.0보다 클 수 있습니다.
  • resolution는 큐브맵의 각 면의 이미지 너비와 높이를 나타내는 uint32_t입니다.
  • 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;

회원 설명

유효한 사용 (암시적)

XrDirectionalLightANDROID 구조에는 조명 추정 데이터가 포함됩니다. 

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

회원 설명

유효한 사용 (암시적)

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 (케언 오버터프)
    • 초기 확장 프로그램 설명

OpenXR™ 및 OpenXR 로고는 The Khronos Group Inc. 소유의 상표이며 중국, 유럽 연합, 일본, 영국에 상표로 등록되어 있습니다.