XR_ANDROID_raycast OpenXR extension

Ciąg znaków nazwy

XR_ANDROID_raycast

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

464

Wersja

1

Zależności rozszerzeń i wersji

XR_ANDROID_trackables

Data ostatniej modyfikacji

2024-10-02

Stan adresu IP

Brak znanych roszczeń dotyczących praw autorskich do treści objętych ochroną prawną.

Twórcy

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Omówienie

To rozszerzenie umożliwia aplikacji wykonywanie rzutów promieniowych na obiekty śledzenia w środowisku. Promienie mogą być przydatne do wykrywania obiektów w otoczeniu, z którymi się przecinają. Na przykład:

• Aby określić, gdzie spadnie unoszący się obiekt, użyj pionowego rzutowania promieniowego.
• Aby określić, na co patrzy użytkownik, używając skierowanego do przodu promienia.

Zapytanie o obsługiwane funkcje raycast

Funkcja xrEnumerateRaycastSupportedTrackableTypesANDROID jest zdefiniowana w ten sposób:

XrResult xrEnumerateRaycastSupportedTrackableTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

Opisy parametrów

• instance to XrInstance, z którego pobierane są dane systemId.
• systemId to XrSystemId, którego obsługiwane typy śledzonych danych na potrzeby raycastingu są wymieniane.
• trackableTypeCapacityInput to pojemność trackableTypes, a 0 – wymagana pojemność.
• trackableTypeCountOutput to wskaźnik do liczby tablicy lub wskaźnik do wymaganej pojemności w przypadku, gdy trackableTypeCapacityInput jest niewystarczający.
  • trackableTypes to wskaźnik do tablicy XrTrackableTypeANDROID, ale może być NULL, jeśli trackableTypeCapacityInput to 0.
• Szczegółowy opis pobierania wymaganego rozmiaru trackableTypes znajdziesz w sekcji Parametry rozmiaru bufora.

xrEnumerateRaycastSupportedTrackableTypesANDROID wylicza typy śledzonych obiektów, które obsługują rzutowanie promieniowe w ramach bieżącej sesji.

Prawidłowe użycie (domyślne)

• Przed wywołaniem funkcji xrEnumerateRaycastSupportedTrackableTypesANDROID musi być włączona rozszerzenia XR_ANDROID_raycast.
• instance musi być prawidłowym identyfikatorem XrInstance
• trackableTypeCountOutput musi być wskaźnikiem na wartość uint32_t
• Jeśli trackableTypeCapacityInput nie jest 0, trackableTypes musi być wskaźnikiem do tablicy wartości trackableTypeCapacityInput XrTrackableTypeANDROID

Kody zwrotne

Gotowe

• XR_SUCCESS

Błąd

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

Wykonywanie zapytania o przecięciu

Funkcja xrRaycastANDROID jest zdefiniowana w ten sposób:

XrResult xrRaycastANDROID(
    XrSession                                   session,
    const XrRaycastInfoANDROID*                 rayInfo,
    XrRaycastHitResultsANDROID*                 results);

Opisy parametrów

• session to XrSession, która wykonuje rzutowanie promieniowe.
• rayInfo to XrRaycastInfoANDROID, który opisuje promień do prześwietlenia.
• results to wskaźnik do XrRaycastHitResultsANDROID, który odbiera wyniki rzutowania promienia.

Aplikacja może wykonywać rzutowanie promieniowe, wywołując xrRaycastANDROID.

• Jeśli rzutowanie promienia przecina więcej obiektów śledzenia niż XrRaycastHitResultsANDROID::maxResults, środowisko wykonawcze musi zwrócić wyniki uderzenia, które są najbliższe XrRaycastHitResultsANDROID::origin promienia.
• Jeśli rzut promienia przecina obiekt śledzenia typu XR_TRACKABLE_TYPE_ANDROID_PLANE, który jest objęty przez inną płaszczyznę, środowisko uruchomieniowe musi zwrócić wynik trafienia tylko dla płaszczyzny objętej.
• W czasie wykonywania należy zwracać wyniki uderzenia w kolejności od najbliższego do najdalszego od XrRaycastInfoANDROID::origin wzdłuż wektora XrRaycastInfoANDROID::trajectory.
• Na etapie wykonywania kodu trzeba zwrócić XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID, jeśli typ śledzenia odpowiadający XrTrackableTrackerANDROID handle w XrRaycastInfoANDROID::trackers nie jest wyliczany przez xrEnumerateRaycastSupportedTrackableTypesANDROID.

Prawidłowe użycie (domyślne)

• Przed wywołaniem xrRaycastANDROID musi być włączone rozszerzenie XR_ANDROID_raycast.
• session musi być prawidłowym identyfikatorem XrSession
• rayInfo musi być wskaźnikiem do prawidłowej struktury XrRaycastInfoANDROID
• results musi być wskaźnikiem do struktury XrRaycastHitResultsANDROID

Kody zwrotne

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
• 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_POSE_INVALID
• XR_ERROR_TIME_INVALID
• XR_ERROR_FEATURE_UNSUPPORTED

Struktura XrRaycastInfoANDROID jest zdefiniowana jako:

typedef struct XrRaycastInfoANDROID {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            maxResults;
    uint32_t                            trackerCount;
    const XrTrackableTrackerANDROID*    trackers;
    XrVector3f                          origin;
    XrVector3f                          trajectory;
    XrSpace                             space;
    XrTime                              time;
} XrRaycastInfoANDROID;

Opisy członków

• type to XrStructureType tej struktury.
• next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowej wersji OpenXR ani w tym rozszerzeniu.
• maxResults to maksymalna liczba wyników do zwrócenia (uint32_t).
• trackerCount to liczba elementów uint32_t w tablicy trackers.
• trackers to tablica XrTrackableTrackerANDROID, z którą powinien być testowany za pomocą zastosowanego typu danych.
• origin to wektor XrVector3f, z którego jest rzucany promień.
• trajectory to wektor XrVector3f, na który kierowany jest promień.
• space to XrSpace, w którym pada promień.
• time to XrTime, do którego kierowany jest promień.

Struktura XrRaycastInfoANDROID opisuje promień do prześwietlenia.

• Tablica XrRaycastInfoANDROID::trackers może zawierać śledzenie różnych typów.
• Tablica XrRaycastInfoANDROID::trackers musi nie zawierać wielu śledzenia tego samego typu, w przeciwnym razie środowisko uruchomieniowe musi zwrócić XR_ERROR_VALIDATION_FAILURE.

Prawidłowe użycie (domyślne)

• Zanim użyjesz rozszerzenia XrRaycastInfoANDROID, musisz je włączyć.XR_ANDROID_raycast
• type musi być XR_TYPE_RAYCAST_INFO_ANDROID
• next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktury.
• trackers musi być wskaźnikiem do tablicy trackerCount prawidłowych uchwytów XrTrackableTrackerANDROID.
• space musi być prawidłowym identyfikatorem XrSpace
• Parametr trackerCount musi być większy niż 0.
• Obie wartości space i elementy trackers muszą zostać utworzone, przydzielone lub pobrane z tego samego obiektu XrSession.

Struktura XrRaycastHitResultsANDROID jest zdefiniowana w ten sposób:

typedef struct XrRaycastHitResultsANDROID {
    XrStructureType               type;
    void*                         next;
    uint32_t                      resultsCapacityInput;
    uint32_t                      resultsCountOutput;
    XrRaycastHitResultANDROID*    results;
} XrRaycastHitResultsANDROID;

Opisy członków

• type to XrStructureType tej struktury.
• next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowej wersji OpenXR ani w tym rozszerzeniu.
• resultsCapacityInput to pojemność tablicy results, a 0 oznacza prośbę o pobranie wymaganej pojemności.
• resultsCountOutput to wskaźnik liczby zapisanych elementów results lub wskaźnik wymaganej pojemności w przypadku, gdy resultsCapacityInput jest niewystarczająca.
• results to wskaźnik do tablicy struktur XrRaycastHitResultANDROID. Może ona wynosić NULL, jeśli resultsCapacityInput = 0.
• Szczegółowy opis pobierania wymaganego rozmiaru results znajdziesz w sekcji Parametry rozmiaru bufora.

Obiekt XrRaycastHitResultsANDROID zawiera tablicę uderzeń promienia.

W czasie wykonywania musi być ustawiona wartość resultsCountOutput nie większa niż XrRaycastInfoANDROID::maxResults.

Prawidłowe użycie (domyślne)

• Przed użyciem rozszerzenia XrRaycastHitResultsANDROID musi być włączone rozszerzenie XR_ANDROID_raycast.
• type musi być XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID
• next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktury.
• results musi być wskaźnikiem do tablicy struktur resultsCapacityInput XrRaycastHitResultANDROID
• Parametr resultsCapacityInput musi być większy niż 0.

Struktura XrRaycastHitResultANDROID jest zdefiniowana w ten sposób:

typedef struct XrRaycastHitResultANDROID {
    XrTrackableTypeANDROID    type;
    XrTrackableANDROID        trackable;
    XrPosef                   pose;
} XrRaycastHitResultANDROID;

Opisy członków

• type to XrTrackableTypeANDROID obiektu śledzenia, który został trafiony przez wiązkę promieni.
• trackable to XrTrackableANDROID, który został znaleziony przez wiązkę promieni, lub XR_NULL_TRACKABLE_ANDROID, jeśli type był śledzony i XR_TRACKABLE_TYPE_DEPTH_ANDROID.
• pose to XrPosef, który został trafiony przez wiązkę promieniowania.

Obiekt XrRaycastHitResultANDROID zawiera szczegóły trafienia promienia.

Wartość XrRaycastHitResultANDROID::pose dla kolizji z płaszczyzną musi być taka, aby X i Z były równoległe do płaszczyzny, a oś Y była prostopadła do płaszczyzny.

Prawidłowe użycie (domyślne)

• Przed użyciem funkcji XrRaycastHitResultANDROID musi być włączone rozszerzenie XR_ANDROID_raycast.
• type musi być prawidłową wartością XrTrackableTypeANDROID

Przykładowy kod do rzutowania promieniowego

Przykładowy kod poniżej pokazuje, jak wykonywać rzuty promieniowe.

XrSession session; // previously initialized
XrTime updateTime; // previously initialized
XrSpace appSpace;  // space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrPosef headPose;  // latest pose of the HMD.
XrTrackableTrackerANDROID planeTracker; // tracker for plane trackables.
XrTrackableTrackerANDROID depthTracker; // tracker for depth trackables.

// Perform a raycast against multiple trackers.
XrTrackableTrackerANDROID trackers[] = {
  &planeTracker,
  &depthTracker,
};
XrRaycastInfoANDROID rayInfo = {XR_TYPE_RAYCAST_INFO_ANDROID};
rayInfo.trackerCount = sizeof(trackers) / sizeof(XrTrackableTrackerANDROID);
rayInfo.trackers = trackers;
rayInfo.origin = headPose.position;
rayInfo.trajectory = CalculateForwardDirectionFromHeadPose(headPose);
rayInfo.space = appSpace;
rayInfo.time = updateTime;

uint32_t totalHitResults = 0;
constexpr uint32 NUM_DESIRED_RESULTS = 2;
XrRaycastHitResultANDROID hitResult[NUM_DESIRED_RESULTS];
XrRaycastHitResultsANDROID hitResults = {XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID};
hitResults.maxResults = NUM_DESIRED_RESULTS;
hitResults.resultsCapacityInput = NUM_DESIRED_RESULTS;
hitResults.results = hitResult;
XrResult result = xrRaycastANDROID(session, &rayInfo, &hitResults);

if (result == XR_SUCCESS && hitResults.resultsCountOutput >= 1) {
  // Hit results are returned in closest-to-farthest order in
  // hitResults.results[0] .. hitResults.results[hitResults.resultsCountOutput - 1]
}

Nowe stałe typu wyliczeniowego

Wyliczenie XrStructureType zostało rozszerzone o:

• XR_TYPE_RAYCAST_INFO_ANDROID
• XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Nowe struktury

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

Nowe funkcje

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

Problemy

Historia wersji

• Wersja 1, 2024-10-02 (Kenny Vercaemer)
  • Początkowy opis rozszerzenia

OpenXR™ i logo OpenXR są znakami towarowymi należącymi do The Khronos Group Inc. i zarejestrowanymi jako znak towarowy w Chinach, Unii Europejskiej, Japonii i Wielkiej Brytanii.