XR_ANDROID_composition_layer_passthrough_mesh OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_composition_layer_passthrough_mesh

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

463

버전

1

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

OpenXR 1.0

최종 수정일

2024-09-18

IP 상태

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

도움을 주신 분들

Google의 그랜트 요시다

케빈 뮬, Google

바실리 바라노프, Google

Google의 피터 첸

레바나 첸, Google

개요

여러 환경 혼합 모드를 지원하는 기기의 경우 시스템은 사용자에게 몰입형 뷰에서 실제 환경을 표시하기 위해 패스스루 구성을 제공할 수 있습니다.

이 확장 프로그램을 사용하면 애플리케이션이 추가 구성 레이어 XrCompositionLayerPassthroughANDROID를 통해 패스스루 텍스처를 임의의 도형에 투사할 수 있습니다.

패스스루 레이어 특성은 다음 매개변수로 지정되며, 여기서 투영은 XrPassthroughLayerANDROID로 표시됩니다.

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

전체 화면 패스스루의 경우 애플리케이션은 환경 혼합 모드를 사용할 수 있습니다.

시스템 기능 검사

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemPassthroughLayerPropertiesANDROID 구조를 XrSystemProperties에 연결하여 시스템이 레이어 패스스루 메시지를 컴포지션할 수 있는지 검사할 수 있습니다.

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • supportsPassthroughLayer는 현재 시스템이 컴포지션 레이어 패스스루 메시를 지원하는지 나타내는 XrBool32입니다.
  • maxMeshIndexCount는 패스스루 메시에 허용되는 최대 색인 수를 반환하는 uint32_t입니다.
  • maxMeshVertexCount는 패스스루 메시에 허용되는 최대 정점 수를 반환하는 uint32_t입니다.

supportsPassthroughLayer가 XR_FALSE를 반환하면 시스템에서 컴포지션 레이어 패스스루 메시지를 지원하지 않으므로 xrCreatePassthroughLayerANDROID에서 XR_ERROR_FEATURE_UNSUPPORTED를 수신합니다. 애플리케이션은 supportsPassthroughLayer이 XR_FALSE인 경우 컴포지션 레이어 패스스루 메시를 사용하지 않아야 합니다.

supportsPassthroughLayer가 XR_TRUE를 반환하면 시스템은 컴포지션 레이어 패스스루 메시를 지원합니다. 이 경우 maxMeshIndexCount 및 maxMeshVertexCount는 0이 아닌 숫자를 반환합니다. 애플리케이션은 xrCreatePassthroughLayerANDROID 및 xrSetPassthroughLayerMeshANDROID를 호출할 때 패스스루 메시지를 설정하는 최대 값으로 maxMeshIndexCount 및 maxMeshVertexCount를 사용해야 합니다. 그러지 않으면 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID이 반환되어 메시지 데이터가 지원되는 한도를 초과했음을 나타낼 수 있습니다.

유효한 사용 (암시적)

패스 스루 레이어 컴포지션

XrCompositionLayerPassthroughANDROID에는 xrEndFrame을 호출할 때 삼각형 메시에 패스스루 텍스처를 렌더링하는 데 필요한 정보가 포함되어 있습니다. XrCompositionLayerPassthroughANDROID는 XrFrameEndInfo에 사용되는 기본 구조체 XrCompositionLayerBaseHeader의 별칭 유형입니다.

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • layerFlags는 레이어에 적용할 플래그를 설명하는 XrCompositionLayerFlags의 비트 마스크입니다.
  • space은 시간 경과에 따라 레이어 메시의 pose가 평가되는 XrSpace입니다.
  • pose는 space의 참조 프레임에서 레이어 메시의 위치와 방향을 정의하는 XrPosef입니다.
  • scale는 레이어 메시의 배율을 정의하는 XrVector3f입니다.
  • opacity는 [0, 1] 범위에서 패스스루 텍스처의 불투명도를 정의하는 float입니다.
  • layer는 이전에 xrCreatePassthroughLayerANDROID로 만든 XrPassthroughLayerANDROID입니다.

애플리케이션은 생성된 layer 및 XrPassthroughLayerMeshANDROID에서 제공하는 해당 메시를 사용하여 XrCompositionLayerPassthroughANDROID 구조를 만들 수 있습니다.

XrCompositionLayerPassthroughANDROID의 포인터는 선택한 레이어 순서에서 기본 구조 XrCompositionLayerBaseHeader의 포인터로 xrEndFrame에 제출하여 런타임에 패스스루 레이어를 최종 프레임 출력에 합성하도록 요청할 수 있습니다.

유효한 사용 (암시적)

패스스루 레이어 핸들 만들기

XrPassthroughLayerANDROID 핸들은 XrCompositionLayerPassthroughANDROID의 동작을 정의하는 패스스루 레이어를 나타냅니다.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

애플리케이션은 xrCreatePassthroughLayerANDROID를 호출하여 XrPassthroughLayerANDROID 핸들을 만들 수 있습니다. 반환된 XrPassthroughLayerANDROID 핸들은 이후 API 호출에서 사용할 수 있습니다. 

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

매개변수 설명

애플리케이션은 XrPassthroughLayerCreateInfoANDROID::vertexCapacity 및 XrPassthroughLayerCreateInfoANDROID::indexCapacity에서 패스스루 메시 인덱스 수를 xrGetSystemProperties를 호출할 때 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 및 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount에서 반환된 최대 값 이하로 지정해야 합니다. createInfo로 정의된 메시 인덱스 수가 최대 값보다 큰 경우 xrCreatePassthroughLayerANDROID는 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID 오류를 반환합니다.

XrPassthroughLayerANDROID 핸들은 결국 xrDestroyPassthroughLayerANDROID 함수를 사용하여 해제해야 합니다.

유효한 사용 (암시적)

반품 코드

성공

  • 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_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

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

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL이거나 구조 체인의 다음 구조체에 대한 포인터입니다. xrCreatePassthroughLayerANDROID를 호출할 때 패스스루 레이어의 초기 메시지를 지정하기 위해 다음 체인에 XrPassthroughLayerMeshANDROID를 제공할 수 있습니다().
  • vertexCapacity는 이 레이어의 메시스에 대한 정점 버퍼의 최대 용량을 나타내는 uint32_t이거나 지정되지 않은 경우 0입니다. 지정된 경우 이 레이어에 설정된 메시의 XrPassthroughLayerMeshANDROID::vertexCount는 vertexCapacity보다 작거나 같아야 합니다.
  • indexCapacity는 이 레이어의 메시에 대한 색인 버퍼의 최대 용량을 나타내는 uint32_t이거나 지정되지 않은 경우 0입니다. 지정된 경우 이 레이어에 설정된 메시의 XrPassthroughLayerMeshANDROID::indexCount는 indexCapacity보다 작거나 같아야 합니다.

유효한 사용 (암시적)

애플리케이션은 xrDestroyPassthroughLayerANDROID 함수를 사용하여 패스스루 레이어와 기본 리소스를 해제할 수 있습니다.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

매개변수 설명

유효한 사용 (암시적)

스레드 안전

  • layer 및 모든 하위 핸들에 대한 액세스는 외부에서 동기화해야 함

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

패스 스루 레이어 메시 설정

애플리케이션은 xrSetPassthroughLayerMeshANDROID 함수를 사용하여 패스스루 레이어의 메시를 설정할 수 있습니다.

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

매개변수 설명

애플리케이션은 XrPassthroughLayerMeshANDROID::vertexCount 및 XrPassthroughLayerMeshANDROID::indexCount의 패스스루 메시 색인 수를 xrGetSystemProperties를 호출할 때 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 및 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount에서 반환된 최대 값보다 작거나 같게 지정해야 합니다. xrSetPassthroughLayerMeshANDROID의 mesh에서 제공된 메시 색인 수가 최대 값보다 크면 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID이 반환됩니다.

xrCreatePassthroughLayerANDROID를 사용하여 layer를 만들 때 메시 버퍼 용량이 XrPassthroughLayerCreateInfoANDROID::vertexCapacity 및 XrPassthroughLayerCreateInfoANDROID::indexCapacity로 지정된 경우 mesh로 정의된 메시 색인 수가 용량보다 큰 경우 xrSetPassthroughLayerMeshANDROID에서 XR_ERROR_SIZE_INSUFFICIENT 오류가 반환됩니다.

유효한 사용 (암시적)

반품 코드

성공

  • 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_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

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

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • windingOrder는 메시 삼각형의 XrWindingOrderANDROID이며, 메시를 렌더링할 때 후면 면 컬링에 사용됩니다.
  • vertexCount는 메시의 꼭짓점 수를 나타내는 uint32_t입니다. XrPassthroughLayerCreateInfoANDROID::vertexCapacity가 지정된 경우 vertexCount는 vertexCapacity보다 작거나 같아야 합니다.
    • vertices는 삼각형 메시의 정점 위치가 포함된 XrVector3f 배열에 대한 포인터입니다.
  • indexCount는 삼각형 메시의 색인 수를 나타내는 uint32_t입니다. 마지막 indexCount % 3 색인(있는 경우)은 그려지지 않습니다. XrPassthroughLayerCreateInfoANDROID::indexCapacity가 지정된 경우 indexCount는 indexCapacity보다 작거나 같아야 합니다.
  • indices는 삼각형 메시의 색인이 포함된 uint16_t 배열에 대한 포인터입니다.

유효한 사용 (암시적)

XrWindingOrderANDROID 열거형은 메시의 삼각형의 와인딩 순서를 식별합니다. 이 순서는 패스스루 레이어의 메시를 렌더링할 때 백페이스 컬링에 런타임에서 사용됩니다. 

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

열거자 설명

  • XR_WINDING_ORDER_UNKNOWN_ANDROID  — 메시의 삼각형 와인딩 순서를 알 수 없습니다.
  • XR_WINDING_ORDER_CW_ANDROID  — 메시의 삼각형 와인딩 순서는 시계 방향입니다.
  • XR_WINDING_ORDER_CCW_ANDROID  — 메시의 삼각형 와인딩 순서는 시계 반대 방향입니다.

패스 스루 레이어 컴포지션 코드 예시

다음 코드 예는 패스스루 레이어를 만들고 컴포지팅에 사용하는 방법을 보여줍니다.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

    // ...
    // Finish frame loop
    // ...
}

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

새로운 객체 유형

새로운 enum 상수

XrObjectType 열거형은 다음으로 확장됩니다.

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

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

  • XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
  • XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
  • XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
  • XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

XrResult 열거형이 다음과 같이 확장되었습니다.

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

새로운 enum

새로운 구조

새로운 함수

문제

버전 기록

  • 버전 1, 2024년 9월 11일 (레바나 첸)
    • 초기 확장 프로그램 설명