XR_ANDROID_light_estimation

이름 문자열

XR_ANDROID_light_estimation

확장 프로그램 유형

인스턴스 확장

등록된 내선 번호

701

버전

1

비준 상태

비준되지 않음

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

OpenXR 1.0

최종 수정일

2025-03-13

IP 상태

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

도움을 주신 분들

Jared Finder, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Salar Khan, Google
Scott Chung, Google

개요

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

권한

이 확장 프로그램은 환경에 관한 조명 정보를 노출하므로 Android 애플리케이션은 매니페스트에 android.permission.SCENE_UNDERSTANDING_COARSE 권한이 나열되어 있어야 합니다. android.permission.SCENE_UNDERSTANDING_COARSE 권한은 위험한 권한으로 간주됩니다. 애플리케이션은 다음 기능을 사용하기 위해 런타임에 권한을 요청해야 합니다.

(보호 수준: 위험)

시스템 기능 검사

XrSystemLightEstimationPropertiesANDROID 구조는 다음과 같이 정의됩니다.

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 함수를 사용하여 조명 에스티메이터를 만듭니다.

  • 시스템이 조명 추정을 지원하지 않으면 런타임은 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다.
  • 필요한 권한이 호출 앱에 부여되지 않은 경우 런타임은 XR_ERROR_PERMISSION_INSUFFICIENT를 반환해야 합니다.

애플리케이션이 런타임에 조명 추정 데이터 액세스가 완료되었음을 나타내려면 xrDestroyLightEstimatorANDROID를 통해 핸들을 소멸해야 합니다 .

유효한 사용 (암시적)

반환 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

XrLightEstimatorCreateInfoANDROID 구조체는 XrLightEstimatorANDROID 핸들을 만드는 정보를 설명합니다.

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrLightEstimatorCreateInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.

유효한 사용 (암시적)

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

매개변수 설명

xrDestroyLightEstimatorANDROID 함수는 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrLightEstimateGetInfoANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다.
  • space는 반환된 조명 방향과 구면 조화 함수가 표현되는 참조 공간을 정의하는 XrSpace입니다.
  • time는 애플리케이션이 조명 추정치를 쿼리하려는 시간을 설명하는 XrTime입니다.

유효한 사용 (암시적)

  • XrLightEstimateGetInfoANDROID를 사용하기 전에 XR_ANDROID_light_estimation 확장 프로그램을 사용 설정해야 합니다.
  • type은 XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID이어야 합니다.
  • next은 NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다.
  • space은 유효한 XrSpace 핸들이어야 합니다.

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

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

회원 설명

state이 XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID인 모든 조명 추정 구조체의 경우 구조체의 다른 모든 필드는 임의적입니다. 즉, 값이 정의되지 않습니다.

주변광, 구면 조화 함수, 기본 방향광의 조명 추정 정보를 가져오기 위해 애플리케이션은 각각 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는 주변광의 강도를 나타내는 XrVector3f입니다. 벡터의 각 구성요소는 각각 빨간색, 녹색, 파란색 채널에 해당합니다.

  • colorCorrection는 감마 공간의 값이 있는 XrVector3f입니다. 감마 색상 공간에서 렌더링하는 경우 렌더링 후 최종 계산된 색상에 구성요소별로 곱합니다. 선형 공간에서 렌더링하는 경우 먼저 2.2의 거듭제곱으로 값을 선형 공간으로 변환한 다음 렌더링 후 최종 계산된 색상에 구성요소별로 곱합니다.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

유효한 사용 (암시적)

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개의 구면 조화 함수 계수가 있습니다.

coefficients는 방향을 입력으로 받아 해당 방향에서 나오는 빛의 색상을 출력하는 특수 함수에서 사용됩니다. 자세한 내용은 이 논문을 참고하세요 .

유효한 사용 (암시적)

XrSphericalHarmonicsKindANDROID 열거형은 애플리케이션이 요청하는 구면 조화 함수의 유형을 런타임에 식별합니다.

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

열거형 값은 다음과 같은 의미를 갖습니다.

열거형 설명

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

구면 조화 함수 계수는 기본 조명의 기여도를 제외한 환경 조명 복사 휘도 함수를 나타냅니다.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

구면 조화 함수 계수는 기본 조명의 기여도를 포함한 환경 조명 복사 함수를 나타냅니다.

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

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

회원 설명

유효한 사용 (암시적)

XrLightEstimateStateANDROID 열거형은 런타임에서 반환된 조명 추정치의 상태를 나타냅니다.

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1,
    XR_LIGHT_ESTIMATE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrLightEstimateStateANDROID;

열거형 값은 다음과 같은 의미를 갖습니다.

열거형 설명

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

조명 추정치가 유효함

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

조명 추정치가 잘못되었습니다.

조명 추정 예시 코드

다음 예시 코드는 런타임에서 가능한 모든 조명 추정 수치를 가져오는 방법을 보여줍니다.

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

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));

새 객체 유형

새 명령어

새 구조

새 열거형

새 열거형 상수

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • XrObjectType 확장 :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • XrStructureType 확장 :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

문제

버전 기록

  • 버전 1, 2024-09-16 (케언 오버터프)

    • 초기 확장 프로그램 설명