Rozszerzenie OpenXR XR_ANDROID_composition_layer_passthrough_mesh

Ciąg znaków nazwy

XR_ANDROID_composition_layer_passthrough_mesh

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

463

Weryfikacja

1

Zależności rozszerzenia i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2024-09-18

Stan adresu IP

Brak znanych roszczeń dotyczących adresu IP.

Twórcy

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Omówienie

W przypadku urządzeń obsługujących wiele trybów mieszania środowiska system może udostępniać konfiguracje przepuszczania, aby pokazać użytkownikowi jego fizyczne otoczenie w wyświetlanym ujęciu.

To rozszerzenie umożliwia aplikacjom wyświetlanie tekstur typu passthrough na dowolnej geometrii za pomocą dodatkowej warstwy kompozytowej XrCompositionLayerPassthroughANDROID.

Właściwości warstwy przepuszczającej są określane przez te parametry, w których projekcja jest reprezentowana przez XrPassthroughLayerANDROID.

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

W przypadku przesyłania obrazu w trybie pełnoekranowym aplikacje mogą używać trybu mieszania środowiska.

Sprawdzanie możliwości systemu

Aplikacja może sprawdzić, czy system jest w stanie stworzyć siatkę przepuszczania warstwy kompozycji, łącząc strukturę XrSystemPassthroughLayerPropertiesANDROID z XrSystemProperties podczas wywołania xrGetSystemProperties.

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • supportsPassthroughLayer to XrBool32, który wskazuje, czy bieżący system obsługuje siatkę przepuszczania warstwy kompozycji.
  • maxMeshIndexCount to uint32_t zwraca maksymalną liczbę indeksów, które zostaną zaakceptowane dla siatki przepuszczania.
  • maxMeshVertexCount to uint32_t zwraca maksymalną liczbę wierzchołków, które zostaną zaakceptowane dla siatki przelotowej.

Jeśli supportsPassthroughLayer zwraca XR_FALSE, system nie obsługuje siatki przepuszczania warstwy kompozycji, dlatego otrzyma XR_ERROR_FEATURE_UNSUPPORTED z xrCreatePassthroughLayerANDROID. Aplikacja nie powinna używać siatki przepuszczania warstwy kompozytowej, gdy supportsPassthroughLayer ma wartość XR_FALSE.

Jeśli supportsPassthroughLayer zwraca XR_TRUE, system obsługuje siatkę przepuszczania warstwy kompozycji. W tym przypadku maxMeshIndexCount i maxMeshVertexCount zwrócą liczbę niezerową. Aplikacja powinna użyć wartości maxMeshIndexCount i maxMeshVertexCount jako maksymalnych wartości, aby ustawić siatki przepuszczania podczas wywoływania funkcji xrCreatePassthroughLayerANDROID i xrSetPassthroughLayerMeshANDROID. W przeciwnym razie może zostać zwrócona wartość XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID, aby wskazać, że dane siatki przekraczają obsługiwany limit.

Prawidłowe użycie (domyślne)

Kompozycja warstwy przepuszczającej

Struktura XrCompositionLayerPassthroughANDROID zawiera informacje potrzebne do renderowania przezroczystej tekstury na siatce trójkątów podczas wywoływania funkcji xrEndFrame. XrCompositionLayerPassthroughANDROID to typ aliasu dla podstawowej struktury XrCompositionLayerBaseHeader używanej w XrFrameEndInfo.

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • layerFlags to maska bitowa XrCompositionLayerFlags, która opisuje flagi stosowane do warstwy.
  • space to XrSpace, w którym pose siatki warstwy jest oceniana w czasie.
  • pose to XrPosef określający położenie i orientację siatki warstwy w układzie odniesienia space.
  • scale to XrVector3f określający skalę siatki warstwy.
  • opacity to float określający nieprzezroczystość tekstury w zakresie [0, 1].
  • layer to XrPassthroughLayerANDROID utworzony wcześniej przez funkcję xrCreatePassthroughLayerANDROID.

Aplikacja może utworzyć strukturę XrCompositionLayerPassthroughANDROID z utworzoną warstwą layer i odpowiednimi siatkami udostępnionymi przez XrPassthroughLayerMeshANDROID.

W xrEndFrame można przesłać wskaźnik do XrCompositionLayerPassthroughANDROID jako wskaźnik do struktury podstawowej XrCompositionLayerBaseHeader w wybranym porządku warstw, aby poprosić środowisko wykonawcze o złożenie warstwy przepuszczającej do wyjścia ostatniej ramki.

Prawidłowe użycie (domyślne)

Tworzenie uchwytu warstwy przelotowej

Uchwyt XrPassthroughLayerANDROID reprezentuje warstwę przelotową, która określa działanie XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Aplikacja może utworzyć obiekt XrPassthroughLayerANDROID, wywołując funkcję xrCreatePassthroughLayerANDROID. Zwrócony obiekt XrPassthroughLayerANDROID może być następnie używany w wywołaniach interfejsu API. 

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

Opisy parametrów

Aplikacja powinna określić liczbę indeksów siatki przepuszczania w XrPassthroughLayerCreateInfoANDROID::vertexCapacity i XrPassthroughLayerCreateInfoANDROID::indexCapacity, która jest mniejsza lub równa maksymalnym wartościom zwracanym przez XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount i XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount podczas wywołania xrGetSystemProperties. xrCreatePassthroughLayerANDROID zwraca błąd XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID, jeśli liczba indeksów siatki zdefiniowana przez createInfo jest większa niż maksymalne wartości.

Musisz ostatecznie uwolnić uchwyt XrPassthroughLayerANDROID za pomocą funkcji xrDestroyPassthroughLayerANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrPassthroughLayerCreateInfoANDROID jest zdefiniowana w ten sposób: 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. XrPassthroughLayerMeshANDROID może być przekazywany w kolejnych elementach łańcucha, aby określić początkową siatkę dla warstwy przepuszczania podczas wywoływania funkcji xrCreatePassthroughLayerANDROID.
  • vertexCapacity to uint32_t reprezentujący maksymalną pojemność bufora wierzchołków dla siatki tego poziomu lub 0, jeśli nie określono inaczej. Jeśli została określona, wartość XrPassthroughLayerMeshANDROID::vertexCount dowolnego zestawu siatek dla tej warstwy musi być mniejsza lub równa wartości vertexCapacity.
  • indexCapacity to uint32_t reprezentujący maksymalną pojemność bufora indeksu dla siatki tego poziomu lub 0, jeśli nie jest określony. Jeśli została określona, wartość XrPassthroughLayerMeshANDROID::indexCount dowolnego zestawu siatek dla tej warstwy musi być mniejsza lub równa wartości indexCapacity.

Prawidłowe użycie (domyślne)

Aplikacja może użyć funkcji xrDestroyPassthroughLayerANDROID, aby zwolnić warstwę przepuszczającą i podstawowe zasoby.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Opisy parametrów

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

  • Dostęp do layer i wszystkich jego obiektów potomnych musi być zsynchronizowany zewnętrznie.

Kody zwrotu

Gotowe

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

Ustawianie siatki warstwy przepuszczania

Aplikacja może użyć funkcji xrSetPassthroughLayerMeshANDROID, aby skonfigurować siatkę dla warstwy przelotowej.

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

Opisy parametrów

Aplikacja powinna określić liczbę indeksów siatki przepuszczania w XrPassthroughLayerMeshANDROID::vertexCount i XrPassthroughLayerMeshANDROID::indexCount, która jest mniejsza lub równa maksymalnym wartościom zwracanym przez XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount i XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount podczas wywoływania xrGetSystemProperties. Jeśli liczba indeksów siatki zwracana przez mesh z xrSetPassthroughLayerMeshANDROID jest większa niż maksymalna liczba wartości, zwracana jest wartość XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID.

Jeśli pojemność bufora siatki jest określona przez XrPassthroughLayerCreateInfoANDROID::vertexCapacity i XrPassthroughLayerCreateInfoANDROID::indexCapacity podczas tworzenia layer za pomocą xrCreatePassthroughLayerANDROID, błąd XR_ERROR_SIZE_INSUFFICIENT zostanie zwrócony w xrSetPassthroughLayerMeshANDROID, jeśli liczba indeksów siatki zdefiniowanych przez mesh jest większa niż pojemność.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrPassthroughLayerMeshANDROID jest zdefiniowana jako: 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • windingOrder to XrWindingOrderANDROID trójkątów siatki, która będzie używana do odrzucania tylnych powierzchni podczas renderowania siatki.
  • vertexCount to uint32_t, który reprezentuje liczbę wierzchołków w siatce. Gdy parametr XrPassthroughLayerCreateInfoANDROID::vertexCapacity jest określony, parametr vertexCount musi być mniejszy lub równy parametrowi vertexCapacity.
    • vertices to wskaźnik do tablicy XrVector3f, która zawiera pozycje wierzchołków siatki trójkąta.
  • indexCount to uint32_t, czyli liczba indeksów w siatce trójkątów. Ostatnie indexCount % 3 indeksów (jeśli takie istnieją) nie zostaną wylosowane. Gdy określono parametr XrPassthroughLayerCreateInfoANDROID::indexCapacity, wartość indexCount musi być mniejsza lub równa wartości indexCapacity.
  • indices to wskaźnik do tablicy uint16_t, która zawiera indeksy siatki trójkąta.

Prawidłowe użycie (domyślne)

Wyliczenie XrWindingOrderANDROID identyfikuje kolejność nawijania trójkątów siatki, która jest używana przez środowisko uruchomieniowe do odrzucania tylnych powierzchni podczas renderowania siatki warstwy przepuszczania. 

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

Opisy wyliczanych

  • XR_WINDING_ORDER_UNKNOWN_ANDROID  — kolejność nawinięcia trójkątów siatki jest nieznana.
  • XR_WINDING_ORDER_CW_ANDROID  — kolejność nawinięcia trójkątów siatki jest zgodna z kierunkiem wskazówek zegara.
  • XR_WINDING_ORDER_CCW_ANDROID  — kolejność nawinięcia trójkątów siatki jest przeciwna do ruchu wskazówek zegara.

Przykładowy kod do tworzenia kompozycji warstwy przepuszczania

Poniższy przykładowy kod pokazuje, jak utworzyć warstwę przepuszczającą i użyć jej w kompozycji.

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

Nowe typy obiektów

Nowe stałe typu wyliczeniowego

Wyliczenie XrObjectType zostało rozszerzone o:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

Wyliczenie XrStructureType zostało rozszerzone o:

  • 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

Wyliczenie XrResult zostało rozszerzone o:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Nowe wartości w polu enum

Nowe struktury

Nowe funkcje

Problemy

Historia wersji

  • Wersja 1, 11 września 2024 r. (Levana Chen)
    • Wstępny opis rozszerzenia