XR_ANDROID_light_estimation OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_light_estimation

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

701

버전

1

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

OpenXR 1.0

최종 수정일

2025-01-17

IP 상태

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

도움을 주신 분들

재러드 파인더, Google

케인 오버터프, Google

스펜서 퀸, Google

레바나 첸, Google

니하브 자인, Google

살라르 칸, Google

Google의 스콧 청

개요

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

시스템 기능 검사

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

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

회원 설명

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

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

시스템이 조명 추정을 지원할 수 없는 경우 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를 사용하여 핸들을 소멸해야(MUST) 합니다.

유효한 사용 (암시적)

반품 코드

성공

  • 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입니다. HDR이므로 부동 소수점 값이 1.0보다 클 수 있습니다.
  • rotation는 큐브맵의 회전을 나타내는 XrQuaternionf입니다.
  • centerExposureTime는 큐브맵이 캡처된 시간을 나타내는 XrTime입니다. 큐브맵 간의 보간법에 유용합니다.

유효한 사용 (암시적)

  • XrEnvironmentLightingCubemapANDROID를 사용하기 전에 XR_ANDROID_light_estimation 확장 프로그램을 사용 설정해야 합니다.
  • 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;

enum은 다음과 같은 의미를 갖습니다.

enum

설명

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;

enum은 다음과 같은 의미를 갖습니다.

enum

설명

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

새로운 enum

새로운 구조

새로운 함수

문제

버전 기록

  • 버전 2, 2025년 1월 17일 (Salar Khan)
    • 환경 조명 큐브맵 지원을 추가했습니다.
  • 버전 1, 2024년 9월 16일 (케인 오버터프)
    • 초기 확장 프로그램 설명