XR_ANDROID_light_estimation OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_light_estimation

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

701

버전

1

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

OpenXR 1.0

최종 수정일

2024-09-18

IP 상태

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

도움을 주신 분들

재러드 파인더, 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;

회원 설명

조명, 구면 조화 및 기본 방향성 조명에 관한 조명 추정치 정보를 얻으려면 애플리케이션은 다음 구조인 XrAmbientLightANDROID, XrSphericalHarmonicsANDROID, XrDirectionalLightANDROID의 인스턴스를 각각 XrLightEstimateANDROID::next에 체이닝할 수 있습니다.

유효한 사용 (암시적)

XrAmbientLightANDROID 구조에는 장면의 주변광에 관한 조명 추정 데이터가 포함됩니다. 

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 유효한 구조는 XrSphericalHarmonicsANDROID 및 XrDirectionalLightANDROID입니다.
  • state는 조명 추정치의 상태를 나타내는 XrLightEstimateStateANDROID입니다.
  • intensity는 주변광의 강도를 나타내는 XrVector3입니다. 벡터의 각 구성요소는 빨간색, 녹색, 파란색 채널에 해당합니다.
  • colorCorrection는 감마 공간에 값이 있는 XrVector3입니다. 구성요소별로 감마 보정 렌더링의 색상을 이러한 값으로 곱합니다.

유효한 사용 (암시적)

XrSphericalHarmonicsANDROID 구조에는 장면의 조명을 나타내는 구면 조화 함수가 포함됩니다. 

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 유효한 구조는 XrAmbientLightANDROID 및 XrDirectionalLightANDROID입니다.
  • state는 조명 추정치의 상태를 나타내는 XrLightEstimateStateANDROID입니다.
  • kind는 애플리케이션에서 요청한 XrSphericalHarmonicsKindANDROID입니다.
  • coefficients는 크기가 9행 3열인 2차원 float 배열입니다. 빨간색, 녹색, 파란색 색상 채널에 각각 해당하는 3개의 열입니다. 각 채널에는 9개의 구면 조화 계수가 있습니다.

유효한 사용 (암시적)

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

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 directionalLight, totalSh, ambientSh, ambientLight 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

새로운 enum

새로운 구조

새로운 함수

문제

버전 기록

  • 버전 1, 2024년 9월 16일 (케인 오버터프)
    • 초기 확장 프로그램 설명