XR_ANDROID_performance_metrics OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_performance_metrics

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

466

최종 수정일

2024-09-06

IP 상태

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

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

OpenXR 1.0

도움을 주신 분들

드미트리 코토프, Google

레바나 첸, Google

재러드 파인더, Google

스펜서 퀸, Google

개요

이 확장 프로그램은 현재 XR 기기, 컴포저, XR 애플리케이션의 다양한 성능 측정항목 카운터를 열거하고 쿼리하는 API를 제공합니다. 개발자는 수집되는 성능 측정항목 카운터를 사용하여 성능 분석을 실행하고 XR 애플리케이션을 타겟팅하여 최적화할 수 있습니다. 애플리케이션은 카운터 읽기에 따라 동작을 변경해서는 안 됩니다.

성능 측정항목 카운터는 루트 경로 /perfmetrics_android 아래에 사전 정의된 XrPath 값으로 구성됩니다. 애플리케이션은 xrEnumeratePerformanceMetricsCounterPathsANDROID를 통해 사용 가능한 카운터를 쿼리할 수 있습니다. 다음은 Android 기기에서 제공될 수 있는 성능 측정항목 카운터 경로 목록입니다.

  • /perfmetrics_android/app/cpu_frametime(밀리초, 부동 소수점 수) - 클라이언트가 프레임을 처리하는 데 소비한 실제 시간입니다.
  • /perfmetrics_android/app/gpu_frametime(밀리초, 부동 소수점 수) - 클라이언트가 프레임당 GPU 작업이 완료될 때까지 기다리는 데 소비한 벽시계 시간입니다. 참고:
    • 대기 시간이 길면 GPU가 다른 작업으로 바빴을 수 있으며 이 클라이언트가 GPU 작업을 너무 많이 하고 있는 것은 아닙니다.
    • 컴포저가 확인했을 때 렌더링이 이미 완료된 경우 GPU 대기 시간은 0이 될 수 있습니다.
  • /perfmetrics_android/app/cpu_utilization(백분율, 부동 소수점 수) - 시간 경과에 따른 총 앱 CPU 사용률의 평균입니다.
    • 멀티코어 프로세서에서는 100% 를 초과할 수 있습니다.
  • /perfmetrics_android/app/gpu_utilization(비율): 시간 경과에 따른 앱 총 GPU 사용률의 평균입니다.
  • /perfmetrics_android/app/motion_to_photon_latency(밀리초, 부동 소수점 수): 사용자가 시작한 모션 이벤트부터 디스플레이의 상응하는 실제 이미지 업데이트까지 걸린 시간입니다.
  • /perfmetrics_android/compositor/cpu_frametime(밀리초, 부동 소수점 수) - 컴포저이터가 프레임을 처리하는 데 소비한 벽시계 시간입니다.
  • /perfmetrics_android/compositor/gpu_frametime(밀리초, 부동 소수점 수) - 프레임당 GPU 작업이 완료될 때까지 컴포저이터가 기다린 실제 시간입니다.
  • /perfmetrics_android/compositor/dropped_frame_count(정수): 모든 앱에서 누락된 총 프레임 수입니다.
  • /perfmetrics_android/compositor/frames_per_second(부동 소수점 수) - 초당 기기에 그려지는 컴포저이터 프레임 수입니다.
  • /perfmetrics_android/device/cpu_utilization_average(백분율, 부동 소수점 수) - 모든 코어에서 시간 경과에 따라 평균을 낸 기기 CPU 사용률입니다.
  • /perfmetrics_android/device/cpu_utilization_worst(비율, 부동 소수점 수) - 시간 경과에 따른 실적이 가장 나쁜 코어의 기기 CPU 사용률입니다.
  • /perfmetrics_android/device/cpu0_utilization~/perfmetrics_android/device/cpuX_utilization(비율, 부동 소수점 수, X는 CPU 코어 수에서 1을 뺀 값) - 시간 경과에 따른 CPU 코어당 기기 CPU 사용률입니다.
  • /perfmetrics_android/device/cpu_frequency (MHz, 부동 소수점 수): 모든 코어에서 시간 경과에 따른 평균을 낸 기기 CPU 주파수입니다.
  • /perfmetrics_android/device/gpu_utilization(비율, 부동 소수점 수) - 시간 경과에 따른 기기 GPU 사용률의 평균입니다.

세션이 생성된 후 애플리케이션은 xrSetPerformanceMetricsStateANDROID를 사용하여 해당 세션의 성능 측정항목 시스템을 사용 설정할 수 있습니다. 애플리케이션은 xrQueryPerformanceMetricsCounterANDROID를 사용하여 성능 측정항목 시스템이 사용 설정된 세션에서 성능 측정항목 카운터를 쿼리하거나 xrGetPerformanceMetricsStateANDROID를 사용하여 성능 측정항목 시스템이 사용 설정되어 있는지 쿼리할 수 있습니다.

이 확장 프로그램의 기능을 사용 설정하려면 애플리케이션이 Extensions 섹션에 표시된 대로 XrInstanceCreateInfo::enabledExtensionNames 매개변수를 사용하여 확장 프로그램 이름을 xrCreateInstance에 전달해야 합니다.

새로운 플래그 유형

typedef XrFlags64 XrPerformanceMetricsCounterFlagsANDROID;

// Flag bits for XrPerformanceMetricsCounterFlagsANDROID
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_ANY_VALUE_VALID_BIT_ANDROID = 0x00000001;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID = 0x00000002;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID = 0x00000004;

새 enum 상수

XrStructureType 열거형은 다음과 같이 확장됩니다.

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

새 열거형

typedef enum XrPerformanceMetricsCounterUnitANDROID {
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_GENERIC_ANDROID = 0,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_PERCENTAGE_ANDROID = 1,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_MILLISECONDS_ANDROID = 2,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_BYTES_ANDROID = 3,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_HERTZ_ANDROID = 4
} XrPerformanceMetricsCounterUnitANDROID;

새로운 구조

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

typedef struct XrPerformanceMetricsStateANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           enabled;
} XrPerformanceMetricsStateANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • enabled는 상태를 가져올 때 성능 측정항목 시스템이 사용 설정되었음을 나타내기 위해 XR_TRUE로 설정되고 그렇지 않으면 XR_FALSE로 설정됩니다. 상태를 설정할 때 XR_TRUE로 설정하여 성능 측정항목 시스템을 사용 설정하고 XR_FALSE로 설정하여 사용 중지합니다.

XrPerformanceMetricsStateANDROID는 xrSetPerformanceMetricsStateANDROID를 호출하여 성능 측정 시스템을 사용 설정하거나 중지할 때 입력으로 제공됩니다. XrPerformanceMetricsStateANDROID는 xrGetPerformanceMetricsStateANDROID를 호출하여 성능 측정항목 시스템이 사용 설정되어 있는지 쿼리할 때 출력 매개변수로 채워집니다.

유효한 사용 (암시적)

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

typedef struct XrPerformanceMetricsCounterANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrPerformanceMetricsCounterFlagsANDROID    counterFlags;
    XrPerformanceMetricsCounterUnitANDROID     counterUnit;
    uint32_t                                   uintValue;
    float                                      floatValue;
} XrPerformanceMetricsCounterANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • counterFlags는 값 멤버의 유효성을 나타내는 XrPerformanceMetricsCounterFlagsANDROID의 비트 마스크입니다.
  • counterUnit는 측정 단위를 설명하는 XrPerformanceMetricsCounterUnitANDROID의 enum입니다.
  • uintValue는 uint32_t 형식의 카운터 값입니다. counterFlags에 XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID가 포함된 경우 유효합니다.
  • floatValue는 float 형식의 카운터 값입니다. counterFlags에 XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID가 포함된 경우에 유효합니다.

XrPerformanceMetricsCounterANDROID는 xrQueryPerformanceMetricsCounterANDROID를 호출하여 실시간 성능 측정항목 카운터 정보를 쿼리하여 채워집니다.

유효한 사용 (암시적)

새로운 함수

xrEnumeratePerformanceMetricsCounterPathsANDROID 함수는 런타임에서 지원되는 모든 성능 측정항목 카운터 경로를 열거하며 다음과 같이 정의됩니다. 

XrResult xrEnumeratePerformanceMetricsCounterPathsANDROID(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

매개변수 설명

  • instance는 이전에 xrCreateInstance로 만든 XrInstance 핸들입니다.
  • counterPathCapacityInput는 counterPaths 배열의 용량이거나 필요한 용량을 검색하라는 요청을 나타내는 0입니다.
  • counterPathCountOutput는 런타임에 의해 쓰여진 counterPaths 개수 또는 counterPathCapacityInput가 충분하지 않은 경우 필요한 용량으로 채워집니다.
  • counterPaths는 런타임에 의해 채워지는 XrPath 배열로, 사용 가능한 모든 실적 측정항목 카운터가 포함되어 있지만 counterPathCapacityInput가 0인 경우 NULL일 수 있습니다.
  • 필요한 counterPaths 크기를 검색하는 방법에 관한 자세한 내용은 버퍼 크기 매개변수 섹션을 참고하세요.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT

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

XrResult xrSetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    const XrPerformanceMetricsStateANDROID*     state);

매개변수 설명

xrSetPerformanceMetricsStateANDROID 함수는 성능 측정항목 시스템을 사용 설정하거나 사용 중지합니다.

유효한 사용 (암시적)

반품 코드

성공

  • 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

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

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

매개변수 설명

xrGetPerformanceMetricsStateANDROID 함수는 성능 측정항목 시스템의 현재 상태를 가져옵니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

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

XrResult xrQueryPerformanceMetricsCounterANDROID(
    XrSession                                   session,
    XrPath                                      counterPath,
    XrPerformanceMetricsCounterANDROID*         counter);

매개변수 설명

xrQueryPerformanceMetricsCounterANDROID 함수는 성능 측정항목 카운터를 쿼리합니다.

애플리케이션은 xrQueryPerformanceMetricsCounterANDROID를 사용하여 측정항목을 쿼리하기 전에 xrSetPerformanceMetricsStateANDROID를 호출하여 성능 측정항목 시스템을 사용 설정해야 합니다.

유효한 사용 (암시적)

반품 코드

성공

  • 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_PATH_UNSUPPORTED
  • XR_ERROR_PATH_INVALID