XR_ANDROID_scene_meshing

Ciąg znaków nazwy

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 adresu 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 otoczeniu 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ą interfejsów XrSceneMeshingTrackerANDROID i XrSceneMeshSnapshotANDROID . Aplikacje mogą uzyskiwać dostęp do wartości w informacjach o podsiatce sceny za pomocą struktury XrSceneSubmeshStateANDROID zwracanej przez funkcję xrGetAllSubmeshStatesANDROID . Aplikacje mogą uzyskiwać dostęp do wartości w danych podsiatki sceny za pomocą struktury XrSceneSubmeshDataANDROID zwracanej przez funkcję xrGetSubmeshDataANDROID .

Dane siatki sceny są poufnymi danymi osobowymi i są ściśle powiązane z prywatnością i integralnością osobistą. Zdecydowanie zalecamy, aby aplikacje, które przechowują lub przesyłają dane siatki sceny, zawsze prosiły użytkownika o aktywną i wyraźną zgodę 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 uważane 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: niebezpieczny)

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 podstawowej specyfikacji 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 obsługuje tworzenie siatki sceny, łącząc strukturę XrSystemSceneMeshingPropertiesANDROID ze strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties .

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsSceneMeshing , system nie obsługuje tworzenia siatki sceny, a w związku z tym musi zwracać XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateSceneMeshingTrackerANDROID . Aplikacja powinna unikać korzystania z funkcji siatki sceny, gdy wartość parametru supportsSceneMeshing to XR_FALSE .

Jeśli środowisko wykonawcze zwraca wartość XR_TRUE dla supportsSceneMeshing, oznacza to, że system obsługuje siatkę sceny.

Prawidłowe użycie (domyślne)

Wyliczenie XrSceneMeshSemanticLabelSetANDROID opisuje zestawy etykiet semantycznych dla siatki sceny. Każda wartość w tym wyliczeniu reprezentuje inne wyliczenie, które 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_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

Wartości wyliczeniowe mają następujące znaczenia:

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.

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 obiekt XrInstance utworzony przez aplikację.
  • systemId to XrSystemId ponowiona próba wywołania funkcji xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity to pojemność supportedSemanticLabelSets lub 0 , aby pobrać wymaganą pojemność.
  • supportedSemanticLabelSetsOutputCount to wskaźnik liczby zapisanych bajtów supportedSemanticLabelSets lub wskaźnik wymaganej pojemności w przypadku, gdy supportedSemanticLabelSetsInputCapacity jest niewystarczająca.
  • supportedSemanticLabelSets to wskaźnik do tablicy XrSceneMeshSemanticLabelSetANDROID . Może to być 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 wartość XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, ponieważ ta wartość wyliczeniowa nie reprezentuje żadnego zestawu etykiet semantycznych i może być używana w przypadku, gdy aplikacja nie potrzebuje semantyki wierzchołków.

Prawidłowe użycie (domyślne)

  •  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 wartości uint32_t.
  •  Jeśli supportedSemanticLabelSetsInputCapacity nie jest równe 0 , supportedSemanticLabelSets musi być wskaźnikiem do tablicy wartości supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID.

Kody zwrotne

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 śledzenia łączenia scen

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Uchwyt XrSceneMeshingTrackerANDROID reprezentuje tracker siatki sceny do tworzenia siatki sceny i zarządzania powiązanymi zasobami.

Ten uchwyt może być używany 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 tworzenia siatki sceny, środowisko wykonawcze musi zwrócić wartość XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateSceneMeshingTrackerANDROID . W takim przypadku środowisko wykonawcze musi zwracać wartość XR_FALSE dla XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing po wywołaniu funkcji xrGetSystemProperties, aby aplikacja mogła uniknąć tworzenia trackera siatki sceny.

Aplikacja musi używać tylko zestawów etykiet semantycznych obsługiwanych przez system w XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet podczas tworzenia trackera siatki sceny. Jeśli aplikacja używa nieobsługiwanego zestawu semantycznych etykiet wierzchołków siatki sceny, środowisko wykonawcze musi zwrócić wartość XR_ERROR_FEATURE_UNSUPPORTED z funkcji 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 siatki sceny. Po zakończeniu tworzenia siatki sceny aplikacja musi zniszczyć uchwyt za pomocą funkcji xrDestroySceneMeshingTrackerANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • semanticLabelSet to XrSceneMeshSemanticLabelSetANDROID używany do określania zestawu etykiet semantycznych, który ma być używany do tworzenia siatki sceny. Jeśli ta wartość jest ustawiona na XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , środowisko wykonawcze zignoruje pole bufora XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals to XrBool32 używany do określania, czy podczas pobierania danych siatki sceny mają być uwzględniane wektory normalne wierzchołków siatki w buforze siatki sceny.

Struktura XrSceneMeshingTrackerCreateInfoANDROID zawiera informacje potrzebne do utworzenia uchwytu XrSceneMeshingTrackerANDROID.

Prawidłowe użycie (domyślne)

Funkcja xrDestroySceneMeshingTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Opisy parametrów

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

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Utwórz uchwyt 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 podsiatkach 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 wartością XrSceneMeshTrackingStateANDROID zawartą w strukturze XrSceneMeshSnapshotCreationResultANDROID. Uchwyt jest technicznie migawką danych siatki sceny w momencie tworzenia. Ten uchwyt może służyć do wykonywania zapytań o informacje i dane siatki sceny za pomocą funkcji xrGetAllSubmeshStatesANDROID i xrGetSubmeshDataANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • baseSpace to XrSpace, w której reprezentowane są informacje o pozycji podsieci sceny.
  • time to XrTime, który opisuje czas, w którym siatka sceny będzie przetwarzana lub wyświetlana. Zwykle jest to XrFrameState :: predictedDisplayTime.
  • boundingBox to XrBoxf opisujący pole ograniczenia, w którym ma zostać uzyskana siatka sceny.

Struktura XrSceneMeshSnapshotCreateInfoANDROID zawiera informacje potrzebne do utworzenia uchwytu XrSceneMeshSnapshotANDROID.

Prawidłowe użycie (domyślne)

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 podstawowej specyfikacji 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 tworzenia zrzutu.

Struktura XrSceneMeshSnapshotCreationResultANDROID przechowuje wynik tworzenia zrzutu siatki sceny zwrócony przez funkcję xrCreateSceneMeshSnapshotANDROID .

Prawidłowe użycie (domyślne)

Wyliczenie XrSceneMeshTrackingStateANDROID opisuje stan śledzenia modułu śledzącego siatkę sceny. Każda wartość w tym wyliczeniu reprezentuje stan śledzenia siatki 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 wyliczeniowe mają następujące znaczenia:

Opis typu wyliczeniowego

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Tracker nie jest jeszcze gotowy do udostępniania danych sieci.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Tracker aktywnie śledzi.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Tracker oczekuje na prawidłowe pomiary do zintegrowania od czasu ostatniej aktualizacji sieci.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Tracker nie otrzymał prawidłowych pomiarów w kilku cyklach i jest w stanie błędu.

Ten stan służy tylko jako dodatkowa informacja dla aplikacji. Jeśli nie ma innych źródeł błędów, środowisko wykonawcze musi nadal umożliwiać aplikacji tworzenie migawek i pobieranie z nich danych niezależnie od bieżącego stanu XrSceneMeshTrackingStateANDROID trackera. Jeśli stan nie jest XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , migawki 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ą funkcji xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput to pojemność submeshStates lub 0 , aby pobrać wymaganą pojemność.
  • submeshStateCountOutput to wskaźnik liczby zapisanych bajtów submeshStates lub wskaźnik wymaganej pojemności w przypadku, gdy submeshStateCapacityInput jest niewystarczająca.
  • submeshStates to wskaźnik tablicy struktur XrSceneSubmeshStateANDROID, do której środowisko wykonawcze będzie przekazywać stan wszystkich podsiatek w siatce sceny. Może to być 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 wybieranie podsieci, dla których chce uzyskać dane.

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • submeshId to identyfikator XrUuid identyfikujący podsiatkę.
  • lastUpdatedTime to XrTime reprezentująca czas ostatniej aktualizacji podsiatki.
  • submeshPoseInBaseSpace to XrPosef reprezentujący pozę podsiatki w przestrzeni bazowej użytej do utworzenia zrzutu siatki sceny. Pozycja jest również środkiem ramki ograniczającej podsiatki.
  • bounds to XrExtent3Df opisujący wymiary ramki ograniczającej, która obejmuje podsiatkę. Ten zakres jest zdefiniowany w przestrzeni bazowej, która została użyta do utworzenia uchwytu siatki sceny.

Środowisko wykonawcze dokłada wszelkich starań, aby przypisać submeshId do regionu przestrzeni fizycznej zajmowanego przez podsiatkę. Środowiska wykonawcze mogą w każdej chwili utracić to mapowanie i przypisać nowy identyfikator UUID do dowolnego podzbioru wykrytych podsiatek. 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 (domyślne)

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ć partie podsiatek lub wszystkie podsiatki naraz, przekazując listę XrSceneSubmeshDataANDROID, przy czym każdy element XrSceneSubmeshDataANDROID :: submeshId jest ustawiony na odpowiedni identyfikator podsiatki 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 podsieci jest nieprawidłowy lub więcej niż 1 element w inoutSubmeshData ma ten sam identyfikator podsieci, ś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 2-wywołaniowym idiomie do wysyłania zapytań o liczbę wierzchołków i indeksów dla wszystkich wybranych podsiatek.

Prawidłowe użycie (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • submeshId to identyfikator XrUuid identyfikujący podsiatkę.
  • vertexCapacityInput to pojemność vertexPositions , vertexNormals i vertexSemantics lub 0 , aby pobrać wymaganą pojemność.
  • vertexCountOutput to wskaźnik liczby zapisanych wartości vertexPositions, vertexNormals i vertexSemantics lub wskaźnik wymaganej pojemności w przypadku, gdy vertexCapacityInput jest niewystarczająca.
  • vertexPositions to tablica XrVector3f, do której środowisko wykonawcze będzie przekazywać pozycje wierzchołków podsiatki.
  • vertexNormals to tablica XrVector3f, do której środowisko wykonawcze będzie zapisywać wektory normalne wierzchołków podsiatki. To pole może pozostać NULL, jeśli aplikacja utworzyła tracker z wyłączonymi wektorami normalnymi.
  • vertexSemantics to tablica uint8_t, do której środowisko wykonawcze będzie zapisywać semantykę wierzchołków podsiatki. To pole może pozostać NULL, jeśli aplikacja utworzyła moduł śledzący z XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID ustawioną etykietą semantyczną.
  • indexCapacityInput to pojemność indices lub 0 , aby pobrać wymaganą pojemność.
  • indexCountOutput to wskaźnik liczby zapisanych bajtów indices lub wskaźnik wymaganej pojemności w przypadku, gdy vertexCapacityInput jest niewystarczająca.
  • indices to tablica uint32_t, do której środowisko wykonawcze będzie zapisywać indeksy podsiatki.
  • Szczegółowy opis pobierania wymaganych rozmiarów vertexPositions, vertexNormals, vertexSemantics i indices znajdziesz w rozdziale Parametry rozmiaru bufora.

Prawidłowe użycie (domyślne)

  •  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 równe 0 , vertexPositions musi być wskaźnikiem do tablicy struktur vertexCapacityInput XrVector3f.
  •  Jeśli vertexCapacityInput nie jest równe 0 , vertexNormals musi być wskaźnikiem do tablicy struktur vertexCapacityInput XrVector3f.
  •  Jeśli vertexCapacityInput nie jest równe 0 , vertexSemantics musi być wskaźnikiem do tablicy wartości vertexCapacityInput uint8_t.
  •  Jeśli indexCapacityInput nie jest równe 0 , indices musi być wskaźnikiem do tablicy wartości indexCapacityInput uint32_t.

Wyliczenie XrSceneMeshSemanticLabelANDROID to domyślny zestaw etykiet semantycznych, których można używać do etykietowania wierzchołków siatki w celu opisania, na której powierzchni środowiska fizycznego znajduje się dany wierzchołek. Ten zbiór wyliczeniowy 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;

Wartości wyliczeniowe mają następujące znaczenia:

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 oznacza, ż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żyć funkcji xrDestroySceneMeshSnapshotANDROID, aby usunąć migawkę siatki sceny. Po zniszczeniu uchwytu aplikacja nie może już używać go do uzyskiwania informacji ani danych o podsiatce. Uchwyt jest automatycznie niszczony po zniszczeniu trackera, ponieważ uchwyt trackera jest elementem nadrzędnym uchwytu migawki siatki sceny.

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotne

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 struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

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

    • Wstępny opis rozszerzenia