XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

719

Wersja

3

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-05-15

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

Przegląd

To rozszerzenie ma na celu dostarczanie siatek, które w przybliżeniu reprezentują obiekty fizyczne w środowisku użytkownika.

Aplikacje mogą używać tego rozszerzenia do wizualizacji sceny i umożliwiania interakcji obiektów wirtualnych z obiektami fizycznymi, np. kolizji.

Dane siatki sceny są generowane przez środowisko wykonawcze i udostępniane aplikacji za pomocą XrSceneMeshingTrackerANDROID i XrSceneMeshSnapshotANDROID . Aplikacje mogą uzyskiwać dostęp do wartości w informacjach o podsiatce sceny za pomocą XrSceneSubmeshStateANDROID zwracanego z xrGetAllSubmeshStatesANDROID . Aplikacje mogą uzyskiwać dostęp do wartości w danych podsiatki sceny za pomocą XrSceneSubmeshDataANDROID zwracanego z xrGetSubmeshDataANDROID .

Dane dotyczące siatki sceny to poufne dane osobowe, które są ściśle powiązane z prywatnością i integralnością osobistą. Zdecydowanie zalecamy, aby aplikacje, które przechowują lub przesyłają dane dotyczące siatki sceny, zawsze prosiły użytkownika o aktywne i wyraźne wyrażenie zgody na takie działanie.

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.SCENE_UNDERSTANDING_FINE. Uprawnienie android.permission.SCENE_UNDERSTANDING_FINE jest uznawane za uprawnienie newralgiczne, ponieważ umożliwia środowisku wykonawczemu analizowanie otoczenia użytkownika.

Aby korzystać z tych funkcji, aplikacja musi prosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczne)

Sprawdzanie możliwości systemu

Struktura XrSystemSceneMeshingPropertiesANDROID jest zdefiniowana w ten sposób:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsSceneMeshing to XrBool32, który wskazuje, czy system obsługuje siatkę sceny.

Aplikacja może sprawdzić, czy system jest w stanie utworzyć siatkę sceny, przez połączenie struktury XrSystemSceneMeshingPropertiesANDROID z XrSystemProperties podczas wywoływania xrGetSystemProperties .

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsSceneMeshing , system nie obsługuje tworzenia siatki sceny, więc musi zwracać XR_ERROR_FEATURE_UNSUPPORTED z xrCreateSceneMeshingTrackerANDROID . Aplikacja powinna unikać korzystania z funkcji siatki sceny, gdy supportsSceneMeshing ma wartość XR_FALSE .

Jeśli środowisko wykonawcze zwraca XR_TRUE dla supportsSceneMeshing , system obsługuje tworzenie siatki sceny.

Prawidłowe użycie (pośrednie)

Wyliczenie XrSceneMeshSemanticLabelSetANDROID opisuje zestawy etykiet semantycznych do tworzenia siatki sceny. Każda wartość w tym typie wyliczeniowym reprezentuje inny typ wyliczeniowy, który zawiera etykiety semantyczne. Na przykład wartość XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID reprezentuje zbiór XrSceneMeshSemanticLabelANDROID .

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

Wartości typu wyliczeniowego mają następujące znaczenie:

Opis typu wyliczeniowego

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Ten zestaw etykiet semantycznych oznacza brak etykiet semantycznych.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Ten zestaw etykiet semantycznych reprezentuje XrSceneMeshSemanticLabelANDROID.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Ten zestaw etykiet semantycznych reprezentuje XrSceneMeshSemanticLabel2ANDROID. (dodane przez rozszerzenie XR_ANDROID_scene_meshing_semantic_label2)

Funkcja xrEnumerateSupportedSemanticLabelSetsANDROID jest zdefiniowana w ten sposób:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

Opisy parametrów

  • instance to XrInstance utworzony przez aplikację.
  • systemId to XrSystemId ponowiony z xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity to pojemność supportedSemanticLabelSets lub 0, aby pobrać wymaganą pojemność.
  • supportedSemanticLabelSetsOutputCount to wskaźnik liczby zapisanych supportedSemanticLabelSets lub wskaźnik wymaganej pojemności, jeśli supportedSemanticLabelSetsInputCapacity jest niewystarczająca.
  • supportedSemanticLabelSets to wskaźnik do tablicy XrSceneMeshSemanticLabelSetANDROID . Może mieć wartość NULL, jeśli supportedSemanticLabelSetsInputCapacity wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru supportedSemanticLabelSets znajdziesz w rozdziale Parametry rozmiaru bufora.

Aplikacja może wyliczyć zbiory etykiet semantycznych obsługiwane przez system za pomocą funkcji xrEnumerateSupportedSemanticLabelSetsANDROID.

Każdy system musi obsługiwać co najmniej XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, ponieważ ta wartość typu wyliczeniowego nie reprezentuje żadnego zestawu etykiet semantycznych i może być używana, gdy aplikacja nie potrzebuje semantyki wierzchołków.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_scene_meshing musi być włączone przed wywołaniem funkcji xrEnumerateSupportedSemanticLabelSetsANDROID.
  • instance musi być prawidłowym uchwytem XrInstance
  • supportedSemanticLabelSetsOutputCount musi być wskaźnikiem do wartości uint32_t
  • Jeśli supportedSemanticLabelSetsInputCapacity nie jest równe 0 , supportedSemanticLabelSets musi być wskaźnikiem do tablicy wartości supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID.

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

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

Tworzenie uchwytu modułu śledzącego siatkę sceny

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Uchwyt XrSceneMeshingTrackerANDROID reprezentuje moduł śledzenia siatki sceny, który służy do tworzenia siatki sceny i zarządzania powiązanymi zasobami.

Ten uchwyt może służyć do tworzenia zrzutu siatki sceny za pomocą funkcji xrCreateSceneMeshSnapshotANDROID w tym rozszerzeniu.

Funkcja xrCreateSceneMeshingTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

Opisy parametrów

Aplikacja może utworzyć uchwyt XrSceneMeshingTrackerANDROID za pomocą funkcji xrCreateSceneMeshingTrackerANDROID.

Jeśli system nie obsługuje siatki sceny, środowisko wykonawcze musi zwrócić XR_ERROR_FEATURE_UNSUPPORTED z xrCreateSceneMeshingTrackerANDROID . W takim przypadku środowisko wykonawcze musi zwrócić XR_FALSE dla XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing, gdy wywoływana jest funkcja xrGetSystemProperties, aby aplikacja mogła uniknąć tworzenia modułu śledzącego siatkę sceny.

Podczas tworzenia modułu śledzenia siatki sceny aplikacja musi używać tylko zestawów etykiet semantycznych obsługiwanych przez system w XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet. Jeśli aplikacja używa nieobsługiwanego zestawu semantycznych etykiet wierzchołków siatki sceny, środowisko wykonawcze musi zwrócić XR_ERROR_FEATURE_UNSUPPORTED z xrCreateSceneMeshingTrackerANDROID .

Aplikacja może wyliczyć listę obsługiwanych zestawów etykiet semantycznych za pomocą funkcji xrEnumerateSupportedSemanticLabelSetsANDROID.

Uchwyt xrCreateSceneMeshingTrackerANDROID jest właścicielem wszystkich zasobów do tworzenia siatki sceny. Po zakończeniu korzystania z funkcji siatki sceny aplikacja musi zniszczyć uchwyt za pomocą funkcji xrDestroySceneMeshingTrackerANDROID.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSceneMeshingTrackerCreateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • semanticLabelSet to XrSceneMeshSemanticLabelSetANDROID, który służy do określania zestawu etykiet semantycznych do użycia w przypadku siatki sceny. Jeśli jest ustawiona wartość XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , środowisko wykonawcze zignoruje pole bufora XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals to XrBool32, który służy do określania, czy podczas pobierania danych siatki sceny w buforze siatki sceny mają być uwzględniane wektory normalne wierzchołków siatki.

Struktura XrSceneMeshingTrackerCreateInfoANDROID opisuje informacje potrzebne do utworzenia uchwytu XrSceneMeshingTrackerANDROID.

Prawidłowe użycie (pośrednie)

Funkcja xrDestroySceneMeshingTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Opisy parametrów

Funkcja xrDestroySceneMeshingTrackerANDROID zwalnia tracker i powiązane zasoby po zakończeniu korzystania z funkcji siatki sceny.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do tracker i wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Tworzenie uchwytu zrzutu siatki sceny

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Uchwyt XrSceneMeshSnapshotANDROID reprezentuje zrzut siatki sceny. Ten zrzut jest tworzony za pomocą funkcji xrCreateSceneMeshSnapshotANDROID, która wykonuje zrzut danych siatki sceny w momencie wywołania funkcji.

Ten uchwyt może służyć do pobierania informacji i danych o siatce podrzędnej za pomocą funkcji xrGetAllSubmeshStatesANDROID i xrGetSubmeshDataANDROID .

Funkcja xrCreateSceneMeshSnapshotANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

Opisy parametrów

Aplikacja może używać funkcji xrCreateSceneMeshSnapshotANDROID do tworzenia migawki siatki sceny z trackera siatki sceny. Ta funkcja zwraca uchwyt XrSceneMeshSnapshotANDROID wraz z XrSceneMeshTrackingStateANDROID opakowanym w strukturę XrSceneMeshSnapshotCreationResultANDROID. Uchwyt jest technicznie zrzutem danych siatki sceny w momencie utworzenia. Uchwyt można wykorzystać do wysyłania zapytań o informacje i dane dotyczące siatki sceny, odpowiednio za pomocą funkcji xrGetAllSubmeshStatesANDROID i xrGetSubmeshDataANDROID.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

Struktura XrSceneMeshSnapshotCreateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • baseSpace to XrSpace, w której reprezentowane są informacje o położeniu siatki podrzędnej sceny.
  • time to XrTime, który opisuje czas, kiedy siatka sceny zostanie przetworzona lub wyświetlona, zwykle XrFrameState :: predictedDisplayTime .
  • boundingBox to XrBoxf opisujący ramkę ograniczającą, w której ma zostać pozyskana siatka sceny.

Struktura XrSceneMeshSnapshotCreateInfoANDROID opisuje informacje potrzebne do utworzenia uchwytu XrSceneMeshSnapshotANDROID.

Prawidłowe użycie (pośrednie)

Struktura XrSceneMeshSnapshotCreationResultANDROID jest zdefiniowana w ten sposób:

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • snapshot to uchwyt XrSceneMeshSnapshotANDROID utworzony przez środowisko wykonawcze.
  • trackingState to XrSceneMeshTrackingStateANDROID, który opisuje stan śledzenia siatki sceny w momencie utworzenia zrzutu.

Struktura XrSceneMeshSnapshotCreationResultANDROID przechowuje wynik utworzenia zrzutu siatki sceny zwrócony przez xrCreateSceneMeshSnapshotANDROID .

Prawidłowe użycie (pośrednie)

Wyliczenie XrSceneMeshTrackingStateANDROID opisuje stan śledzenia modułu śledzącego siatkę sceny. Każda wartość w tym typie wyliczeniowym reprezentuje stan modułu śledzącego siatkę sceny.

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

Wartości typu wyliczeniowego mają następujące znaczenie:

Opis typu wyliczeniowego

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Tracker nie jest jeszcze gotowy do dostarczania danych siatki.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Monitor aktywności aktywnie śledzi.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Tracker czeka na prawidłowe pomiary do zintegrowania od czasu ostatniej aktualizacji siatki.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Tracker nie otrzymał prawidłowych pomiarów przez kilka cykli i jest w stanie błędu.

Ten stan służy tylko jako dodatkowe informacje dla aplikacji. Jeśli nie ma innych źródeł błędów, środowisko wykonawcze musi nadal umożliwiać aplikacji tworzenie zrzutów i pobieranie z nich danych niezależnie od bieżącego stanu XrSceneMeshTrackingStateANDROID modułu śledzącego. Jeśli stan nie jest XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , zrzuty mogą być nieaktualne lub puste.

pobieranie danych siatki sceny ze zrzutu siatki sceny,

Funkcja xrGetAllSubmeshStatesANDROID jest zdefiniowana w ten sposób:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

Opisy parametrów

  • snapshot to uchwyt XrSceneMeshSnapshotANDROID utworzony wcześniej za pomocą xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput to pojemność submeshStates lub 0, aby pobrać wymaganą pojemność.
  • submeshStateCountOutput to wskaźnik liczby zapisanych submeshStates lub wskaźnik wymaganej pojemności, jeśli submeshStateCapacityInput jest niewystarczająca.
  • submeshStates to wskaźnik do tablicy struktur XrSceneSubmeshStateANDROID, do których środowisko wykonawcze będzie wysyłać stan wszystkich siatek podrzędnych w siatce sceny. Może mieć wartość NULL, jeśli submeshStateCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru submeshStates znajdziesz w rozdziale Parametry rozmiaru bufora.

Aplikacja może używać funkcji xrGetAllSubmeshStatesANDROID, aby uzyskać stan wszystkich podsiatek w siatce sceny. Zawiera podstawowe informacje, które umożliwiają aplikacji wybór siatek podrzędnych, dla których aplikacja chce uzyskać dane.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_scene_meshing musi być włączone przed wywołaniem xrGetAllSubmeshStatesANDROID.
  • snapshot musi być prawidłowym uchwytem XrSceneMeshSnapshotANDROID
  • submeshStateCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli submeshStateCapacityInput nie jest równe 0 , submeshStates musi być wskaźnikiem do tablicy struktur submeshStateCapacityInput XrSceneSubmeshStateANDROID.

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

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

Struktura XrSceneSubmeshStateANDROID jest zdefiniowana w ten sposób:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • submeshId to XrUuid identyfikujący siatkę podrzędną.
  • lastUpdatedTime to XrTime reprezentujący czas ostatniej aktualizacji podsieci.
  • submeshPoseInBaseSpace to XrPosef reprezentujący pozę siatki podrzędnej w przestrzeni podstawowej użytej do utworzenia zrzutu siatki sceny. Pozycja jest też środkiem ramki ograniczającej siatki podrzędnej.
  • bounds to XrExtent3Df opisujący wymiary ramki ograniczającej, która obejmuje siatkę podrzędną. Te granice są zdefiniowane w przestrzeni podstawowej, która została użyta do utworzenia uchwytu siatki sceny.

Środowisko wykonawcze stara się jak najlepiej dopasować submeshId do regionu przestrzeni fizycznej zajmowanej przez podsiatkę. Środowiska wykonawcze mogą w każdej chwili utracić to mapowanie i przypisać nowy identyfikator UUID do dowolnego podzbioru wykrytych podsieci. W szczególności środowiska wykonawcze nie muszą ponownie używać tych samych identyfikatorów UUID dla tych samych siatek w kolejnych instancjach aplikacji.

Prawidłowe użycie (pośrednie)

Funkcja xrGetSubmeshDataANDROID jest zdefiniowana w ten sposób:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

Opisy parametrów

Aplikacja może używać funkcji xrGetSubmeshDataANDROID, aby pobierać grupy siatek podrzędnych lub wszystkie siatki podrzędne naraz, przekazując listę XrSceneSubmeshDataANDROID z każdym elementem XrSceneSubmeshDataANDROID :: submeshId ustawionym na odpowiedni identyfikator siatki podrzędnej do pobrania.

Wartość XrSceneSubmeshDataANDROID :: submeshId musi być unikalna dla każdego elementu w inoutSubmeshData i możliwa do pobrania przez xrGetAllSubmeshStatesANDROID dla tego samego snapshot . Jeśli identyfikator submesh jest nieprawidłowy lub więcej niż 1 element w inoutSubmeshData ma ten sam identyfikator submesh, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .

submeshDataCount musi być mniejsza lub równa wartości zwracanej przez xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput , w przeciwnym razie środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .

Można go użyć w idiomie z 2 wywołaniami, aby sprawdzić liczbę wierzchołków i indeksów we wszystkich wybranych podsiatkach.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

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

Struktura XrSceneSubmeshDataANDROID jest zdefiniowana w ten sposób:

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • submeshId to XrUuid identyfikujący siatkę podrzędną.
  • vertexCapacityInput to pojemność vertexPositions , vertexNormals i vertexSemantics lub 0, aby pobrać wymaganą pojemność.
  • vertexCountOutput to wskaźnik liczby zapisanych elementów vertexPositions, vertexNormals i vertexSemantics lub wskaźnik wymaganej pojemności, jeśli vertexCapacityInput jest niewystarczająca.
  • vertexPositions to tablica XrVector3f, do której środowisko wykonawcze będzie wysyłać pozycje wierzchołków siatki podrzędnej.
  • vertexNormals to tablica XrVector3f, do której środowisko wykonawcze będzie wysyłać wektory normalne wierzchołków siatki podrzędnej. To pole może pozostać NULL, jeśli aplikacja utworzyła tracker z wyłączonymi normalnymi.
  • vertexSemantics to tablica uint8_t, do której środowisko wykonawcze będzie wysyłać semantykę wierzchołków podsiatki. To pole może pozostać puste (NULL), jeśli aplikacja utworzyła tracker z ustawioną etykietą semantyczną XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput to pojemność indices lub 0, aby pobrać wymaganą pojemność.
  • indexCountOutput to wskaźnik liczby zapisanych indices lub wskaźnik wymaganej pojemności, jeśli vertexCapacityInput jest niewystarczająca.
  • indices to tablica uint32_t, do której środowisko wykonawcze będzie wysyłać indeksy siatki podrzędnej.
  • Szczegółowy opis pobierania wymaganych rozmiarów vertexPositions, vertexNormals, vertexSemantics i indices znajdziesz w rozdziale Parametry rozmiaru bufora.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_scene_meshing musi być włączone przed użyciem XrSceneSubmeshDataANDROID.
  • type musi mieć wartość XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur
  • Jeśli vertexCapacityInput nie jest 0 , vertexPositions musi być wskaźnikiem do tablicy struktur vertexCapacityInput XrVector3f
  • Jeśli vertexCapacityInput nie jest 0 , vertexNormals musi być wskaźnikiem do tablicy struktur vertexCapacityInput XrVector3f
  • Jeśli vertexCapacityInput nie jest 0 , vertexSemantics musi być wskaźnikiem do tablicy wartości vertexCapacityInput uint8_t
  • Jeśli indexCapacityInput nie jest 0 , indices musi być wskaźnikiem do tablicy wartości indexCapacityInput uint32_t

Wyliczenie XrSceneMeshSemanticLabelANDROID to domyślny zestaw etykiet semantycznych, które mogą służyć do oznaczania wierzchołków siatki, aby opisać, na której powierzchni środowiska fizycznego znajduje się dany wierzchołek. Ten zbiór typów wyliczeniowych jest reprezentowany przez wartość XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID w XrSceneMeshSemanticLabelSetANDROID .

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

Typy wyliczeniowe mają następujące znaczenie:

Opis typu wyliczeniowego

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Ta etykieta semantyczna wskazuje, że odpowiedni element siatki reprezentuje nieznany obiekt.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Ta etykieta semantyczna wskazuje, że odpowiedni element siatki reprezentuje podłogę.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Ta etykieta semantyczna wskazuje, że odpowiedni element siatki reprezentuje sufit.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Ta etykieta semantyczna wskazuje, że odpowiedni element siatki reprezentuje ścianę.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Ta etykieta semantyczna wskazuje, że odpowiedni element siatki reprezentuje tabelę.

Usuwanie zrzutu siatki sceny

Funkcja xrDestroySceneMeshSnapshotANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Opisy parametrów

Aplikacja może używać funkcji xrDestroySceneMeshSnapshotANDROID do niszczenia zrzutu siatki sceny. Po zniszczeniu uchwytu aplikacja nie może już go używać do uzyskiwania informacji o podsiatce ani jej danych. Uchwyt jest automatycznie niszczony, gdy niszczony jest moduł śledzący, ponieważ uchwyt modułu śledzącego jest elementem nadrzędnym uchwytu zrzutu siatki sceny.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do snapshot i wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Przykładowy kod do tworzenia siatki sceny

Poniższy przykładowy kod pokazuje, jak uzyskać dostęp do danych siatki sceny na potrzeby renderowania.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Nowe typy obiektów

Nowe polecenia

Nowe domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

Problemy

Historia zmian

  • Wersja 3, 15 maja 2025 r. (Salar Khan)

    • Początkowy opis rozszerzenia