OpenXR-Erweiterung „XR_ANDROID_raycast“

Namensstring

XR_ANDROID_raycast

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

464

Revision

1

Erweiterungs- und Versionsabhängigkeiten

XR_ANDROID_trackables

Datum der letzten Änderung

2024-10-02

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Mitwirkende

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Übersicht

Mit dieser Erweiterung kann die Anwendung Raycasts auf Tracker in der Umgebung ausführen. Raycasts können nützlich sein, um Objekte in der Umgebung zu erkennen, die von einem Strahl geschnitten werden. Beispiel:

  • Mit einem vertikalen Raycast wird ermittelt, wohin ein schwebendes Objekt fallen würde, wenn es losgelassen wird.
  • Hier wird mit einem nach vorne gerichteten Strahlensatz ermittelt, wo ein Nutzer hinsieht.

Unterstützte Raycast-Funktionen abfragen

Die Funktion xrEnumerateRaycastSupportedTrackableTypesANDROID ist so definiert:

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

Parameterbeschreibungen

  • instance ist die XrInstance, aus der systemId abgerufen wurde.
  • systemId ist die XrSystemId, deren unterstützte trackbare Typen für das Raytracing aufgezählt werden.
  • trackableTypeCapacityInput ist die Kapazität der trackableTypes oder 0, um die erforderliche Kapazität abzurufen.
  • trackableTypeCountOutput ist ein Verweis auf die Anzahl der Elemente im Array oder ein Verweis auf die erforderliche Kapazität, falls trackableTypeCountOutput nicht ausreicht.trackableTypeCapacityInput
    • trackableTypes ist ein Verweis auf ein Array von XrTrackableTypeANDROID, kann aber auch NULL sein, wenn trackableTypeCapacityInput 0 ist.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen trackableTypes-Größe findest du im Abschnitt Parameter für die Puffergröße.

xrEnumerateRaycastSupportedTrackableTypesANDROID listet die Trackable-Typen auf, die das Raytracing durch die aktuelle Sitzung unterstützen.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • 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

Raycast ausführen

Die Funktion xrRaycastANDROID ist so definiert:

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

Parameterbeschreibungen

Die Anwendung kann Raycasts ausführen, indem xrRaycastANDROID aufgerufen wird.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrRaycastInfoANDROID ist so definiert: 

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;

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • maxResults ist die maximale Anzahl von uint32_t zurückzugebenden Ergebnissen.
  • trackerCount ist die uint32_t-Anzahl des trackers-Arrays.
  • trackers ist das Array von XrTrackableTrackerANDROID, an dem der gestreamte Strahl geprüft werden sollte.
  • origin ist der XrVector3f, von dem aus der Strahl gesendet wird.
  • trajectory ist der XrVector3f, auf den der Strahl gerichtet ist.
  • space ist der XrSpace, in dem der Strahl geworfen wird.
  • time ist der XrTime, auf den der Strahl geworfen wird.

Die Struktur XrRaycastInfoANDROID beschreibt den zu werfenden Strahl.

Gültige Verwendung (implizit)

Die Struktur XrRaycastHitResultsANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • resultsCapacityInput ist die Kapazität des results-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
  • resultsCountOutput ist ein Verweis auf die Anzahl der geschriebenen results oder ein Verweis auf die erforderliche Kapazität, falls resultsCapacityInput nicht ausreicht.
  • results ist ein Verweis auf ein Array von XrRaycastHitResultANDROID-Strukturen. Es kann NULL sein, wenn resultsCapacityInput 0 ist.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen results-Größe findest du im Abschnitt Parameter für die Puffergröße.

XrRaycastHitResultsANDROID enthält das Array der Treffer eines Raycasts.

Die Laufzeit muss resultsCountOutput auf einen Wert festlegen, der kleiner oder gleich XrRaycastInfoANDROID::maxResults ist.

Gültige Verwendung (implizit)

Die Struktur XrRaycastHitResultANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

  • type ist der XrTrackableTypeANDROID des Objekts, das vom Raycast getroffen wurde.
  • trackable ist die XrTrackableANDROID, auf die der Raycast trifft, oder XR_NULL_TRACKABLE_ANDROID, wenn die trackbare type XR_TRACKABLE_TYPE_DEPTH_ANDROID war.
  • pose ist die XrPosef, auf die der Raycast trifft.

XrRaycastHitResultANDROID enthält die Details eines Raycast-Treffers.

Die XrRaycastHitResultANDROID::pose für einen Flächeneinschlag muss so sein, dass X und Z parallel zur Fläche und die Y-Achse senkrecht zur Fläche sind.

Art des trackbaren Treffers

Beschreibung

XR_TRACKABLE_TYPE_PLANE_ANDROID

Trifft auf horizontale und/oder vertikale Oberflächen, um die richtige Tiefe und Ausrichtung eines Punkts zu bestimmen.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Es werden Tiefeninformationen aus der gesamten Szene verwendet, um die richtige Tiefe und Ausrichtung eines Punkts zu bestimmen.

Gültige Verwendung (implizit)

Beispielcode für Raytracing

Im folgenden Beispielcode wird gezeigt, wie Sie Raycasts ausführen.

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]
}

Neue Enum-Konstanten

Die Aufzählung XrStructureType wurde um folgende Elemente erweitert:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Revision 1, 02.10.2024 (Kenny Vercaemer)
    • Erste Beschreibung der Erweiterung

OpenXR™ und das OpenXR-Logo sind Marken der Khronos Group Inc. und sind als Marke in China, der Europäischen Union, Japan und dem Vereinigten Königreich eingetragen.