Das Android XR SDK ist jetzt in der Entwicklervorschau verfügbar. Wir freuen uns über Ihr Feedback! Auf unserer Supportseite können Sie sich an uns wenden.

Diese Seite wurde von der Cloud Translation API übersetzt.

OpenXR-Erweiterung „XR_ANDROID_raycast“

Namensstring

XR_ANDROID_raycast

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

464

Revision

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 mithilfe eines nach vorne gerichteten Strahls ermittelt, wo ein Nutzer gerade 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)

Die Erweiterung XR_ANDROID_raycast muss aktiviert sein, bevor xrEnumerateRaycastSupportedTrackableTypesANDROID aufgerufen wird.
instance muss ein gültiger XrInstance-Alias sein
trackableTypeCountOutput muss ein Verweis auf einen uint32_t-Wert sein
Wenn trackableTypeCapacityInput nicht 0 ist, muss trackableTypes ein Verweis auf ein Array von trackableTypeCapacityInput-Werten vom Typ XrTrackableTypeANDROID sein.

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

session ist die XrSession, die den Raycast ausführt.
rayInfo ist die XrRaycastInfoANDROID, die den zu werfenden Strahl beschreibt.
results ist ein Verweis auf die XrRaycastHitResultsANDROID, die die Ergebnisse des Raycasts empfängt.

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

Wenn ein Raycast mehr Trackables als XrRaycastHitResultsANDROID::maxResults schneidet, muss die Laufzeit die Trefferergebnisse zurückgeben, die dem Ursprung XrRaycastHitResultsANDROID::origin des Strahls am nächsten sind.
Wenn ein Raycast ein Trackable vom Typ XR_TRACKABLE_TYPE_ANDROID_PLANE schneidet, das von einer anderen Ebene überdeckt wird, muss die Laufzeit nur das Trefferergebnis für die überdeckende Ebene zurückgeben.
Die Laufzeit muss die Trefferergebnisse in der Reihenfolge von „am nächsten“ bis „am weitesten entfernt“ von XrRaycastInfoANDROID::origin entlang des Vektors XrRaycastInfoANDROID::trajectory zurückgeben.
Die Laufzeit muss XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID zurückgeben, wenn der Trackable-Typ, der den XrTrackableTrackerANDROID-Handles in XrRaycastInfoANDROID::trackers entspricht, nicht von xrEnumerateRaycastSupportedTrackableTypesANDROID aufgelistet wird.

Gültige Verwendung (implizit)

Die Erweiterung XR_ANDROID_raycast muss aktiviert sein, bevor xrRaycastANDROID aufgerufen wird.
session muss ein gültiger XrSession-Alias sein.
rayInfo muss ein Verweis auf eine gültige XrRaycastInfoANDROID-Struktur sein
results muss ein Verweis auf eine XrRaycastHitResultsANDROID-Struktur sein

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 ausgerichtet 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.

Das Array XrRaycastInfoANDROID::trackers kann Tracker verschiedener Typen enthalten.
Das Array XrRaycastInfoANDROID::trackers darf nicht mehrere Tracker desselben Typs enthalten. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Gültige Verwendung (implizit)

Die Erweiterung XR_ANDROID_raycast muss aktiviert sein, bevor XrRaycastInfoANDROID verwendet werden kann.
type muss XR_TYPE_RAYCAST_INFO_ANDROID sein.
next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
trackers muss ein Verweis auf ein Array von trackerCount gültigen XrTrackableTrackerANDROID-Handlen sein.
space muss ein gültiger XrSpace-Handle sein
Der Parameter trackerCount muss größer als 0 sein.
Sowohl space als auch die Elemente von trackers müssen in derselben XrSession erstellt, zugewiesen oder abgerufen worden sein.

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 Erweiterung XR_ANDROID_raycast muss aktiviert sein, bevor XrRaycastHitResultsANDROID verwendet werden kann.
type muss XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID sein.
next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
results muss ein Verweis auf ein Array von resultsCapacityInput XrRaycastHitResultANDROID-basierten Strukturen sein.
Der Parameter resultsCapacityInput muss größer als 0 sein.

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 normal zur Fläche ist.

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)

Die Erweiterung XR_ANDROID_raycast muss aktiviert sein, bevor XrRaycastHitResultANDROID verwendet werden kann.
type muss ein gültiger Wert für XrTrackableTypeANDROID sein

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

XrRaycastInfoANDROID
XrRaycastHitResultANDROID
XrRaycastHitResultsANDROID

Neue Funktionen

xrEnumerateRaycastSupportedTrackableTypesANDROID
xrRaycastANDROID

Probleme

Versionsverlauf

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