XR_ANDROID_raycast OpenXR extension

Ciąg znaków nazwy

XR_ANDROID_raycast

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

464

Weryfikacja

1

Zależności rozszerzenia i wersji

XR_ANDROID_trackables

Data ostatniej modyfikacji

2024-10-02

Stan adresu IP

Brak znanych roszczeń dotyczących adresu IP.

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ą. 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 promienia rzutowania do przodu.

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ąca.
    • 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)

Kody zwrotu

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ęcie

Funkcja xrRaycastANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

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

Prawidłowe użycie (domyślne)

Kody zwrotu

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 struktur. Nie ma żadnych takich struktur zdefiniowanych w podstawowym 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ą przekształconego strumienia.
  • 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, w którego kierunku pada promień.

Struktura XrRaycastInfoANDROID opisuje promień do prześwietlenia.

Prawidłowe użycie (domyślne)

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 struktur. Nie ma żadnych takich struktur zdefiniowanych w podstawowym 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 mniejsza lub równa XrRaycastInfoANDROID::maxResults.

Prawidłowe użycie (domyślne)

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.

Typ mierzalnego działania

Opis

XR_TRACKABLE_TYPE_PLANE_ANDROID

Dotyka poziomych lub pionowych powierzchni, aby określić prawidłową głębokość i orientację punktu.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Korzysta z informacji o głębi z całej sceny, aby określić prawidłową głębię i orientację punktu.

Prawidłowe użycie (domyślne)

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

Nowe funkcje

Problemy

Historia wersji

  • Wersja 1, 2024-10-02 (Kenny Vercaemer)
    • Wstępny opis rozszerzenia