Estensione OpenXR XR_ANDROID_raycast

Stringa del nome

XR_ANDROID_raycast

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

464

Revisione

1

Dipendenze di estensioni e versioni

XR_ANDROID_trackables

Data ultima modifica

2024-10-02

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Panoramica

Questa estensione consente all'applicazione di eseguire raycast sui rilevabili nell'ambiente. I raycast possono essere utili per rilevare gli oggetti nell'ambiente con cui un raggio si intersecherà. Ad esempio:

• Per determinare dove cadrà un oggetto galleggiante quando viene rilasciato, utilizzando un raycast verticale.
• Per determinare dove sta guardando un utente, utilizzando un raggio di ricerca in avanti.

Attenzione:
Autorizzazioni

Le applicazioni Android devono avere l'autorizzazione android.permission.SCENE_UNDERSTANDING elencata nel file manifest perché questa estensione dipende da XR_ANDROID_trackables ed espone la geometria dell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING è considerata pericolosa. (livello di protezione: pericoloso)

Esegui query sulle funzionalità di raycast supportate

La funzione xrEnumerateRaycastSupportedTrackableTypesANDROID è definita come segue:

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

Descrizioni dei parametri

• instance è l'XrInstance da cui è stato recuperato systemId.
• systemId è l'XrSystemId di cui vengono enumerati i tipi tracciabili supportati per il raycasting.
• trackableTypeCapacityInput è la capacità del trackableTypes o 0 per recuperare la capacità richiesta.
• trackableTypeCountOutput è un puntatore al conteggio dell'array o un puntatore alla capacità richiesta nel caso in cui trackableTypeCapacityInput sia insufficiente.
  • trackableTypes è un puntatore a un array di XrTrackableTypeANDROID, ma può essere NULL se trackableTypeCapacityInput è 0.
• Per una descrizione dettagliata del recupero della dimensione trackableTypes richiesta, consulta la sezione Parametri di dimensione del buffer.

xrEnumerateRaycastSupportedTrackableTypesANDROID enumera i tipi di elementi tracciabili che supportano il raycasting dalla sessione corrente.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_raycast deve essere attivata prima di chiamare xrEnumerateRaycastSupportedTrackableTypesANDROID
• instance deve essere un handle XrInstance valido
• trackableTypeCountOutput deve essere un puntatore a un valore uint32_t
• Se trackableTypeCapacityInput non è 0, trackableTypes deve essere un puntatore a un array di valori trackableTypeCapacityInput XrTrackableTypeANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS

Errore

• 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

Esegui un raycast

La funzione xrRaycastANDROID è definita come:

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

Descrizioni dei parametri

• session è la XrSession che esegue il raycast.
• rayInfo è l'oggetto XrRaycastInfoANDROID che descrive il raggio da emettere.
• results è un puntatore a XrRaycastHitResultsANDROID che riceve i risultati del raycast.

L'applicazione può eseguire raycast chiamando xrRaycastANDROID.

• Se un raycast interseca più elementi tracciabili rispetto a XrRaycastHitResultsANDROID::maxResults, il runtime deve restituire i risultati relativi agli hit più vicini a XrRaycastHitResultsANDROID::origin del raggio.
• Se un raycast interseca un elemento tracciabile di tipo XR_TRACKABLE_TYPE_ANDROID_PLANE, che è incluso in un altro piano, il runtime deve restituire il risultato di hit solo per il piano di inclusione.
• Il runtime deve restituire i risultati degli hit in ordine dal più vicino al più lontano da XrRaycastInfoANDROID::origin lungo il vettore XrRaycastInfoANDROID::trajectory.
• Il runtime deve restituire XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID se il tipo di rilevabile corrispondente agli handle XrTrackableTrackerANDROID in XrRaycastInfoANDROID::trackers non è enumerato da xrEnumerateRaycastSupportedTrackableTypesANDROID.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_raycast deve essere attivata prima di chiamare xrRaycastANDROID
• session deve essere un handle XrSession valido
• rayInfo deve essere un puntatore a una struttura XrRaycastInfoANDROID valida
• results deve essere un puntatore a una struttura XrRaycastHitResultsANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

• 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

La struttura XrRaycastInfoANDROID è definita come:

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;

Descrizioni dei membri

• type è il XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
• maxResults è il numero massimo di risultati da restituire uint32_t.
• trackerCount è il conteggio uint32_t dell'array trackers.
• trackers è l'array di XrTrackableTrackerANDROID rispetto al quale deve essere testato il raggio proiettato.
• origin è il XrVector3f da cui viene lanciato il raggio.
• trajectory è il XrVector3f a cui è indirizzato il raggio.
• space è lo spazio XrSpace in cui viene lanciato il raggio.
• time è il XrTime a cui viene lanciato il raggio.

La struttura XrRaycastInfoANDROID descrive il raggio da lanciare.

• L'array XrRaycastInfoANDROID::trackers può contenere tracker di tipi diversi.
• L'array XrRaycastInfoANDROID::trackers non deve contenere più tracker dello stesso tipo, altrimenti il runtime deve restituire XR_ERROR_VALIDATION_FAILURE.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_raycast deve essere attivata prima di utilizzare XrRaycastInfoANDROID
• type deve essere XR_TYPE_RAYCAST_INFO_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• trackers deve essere un puntatore a un array di trackerCount handle XrTrackableTrackerANDROID validi
• space deve essere un handle XrSpace valido
• Il parametro trackerCount deve essere maggiore di 0
• Sia space sia gli elementi di trackers devono essere stati creati, assegnati o recuperati dalla stessa XrSession

La struttura XrRaycastHitResultsANDROID è definita come:

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

Descrizioni dei membri

• type è il XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
• resultsCapacityInput è la capacità dell'array results o 0 per indicare una richiesta di recupero della capacità richiesta.
• resultsCountOutput è un puntatore al conteggio di results scritto o un puntatore alla capacità richiesta nel caso in cui resultsCapacityInput sia insufficiente.
• results è un puntatore a un array di strutture XrRaycastHitResultANDROID. Può essere NULL se resultsCapacityInput è 0.
• Per una descrizione dettagliata del recupero della dimensione results richiesta, consulta la sezione Parametri di dimensione del buffer.

XrRaycastHitResultsANDROID contiene l'array di hit di un raycast.

Il runtime deve impostare resultsCountOutput su un valore inferiore o uguale a XrRaycastInfoANDROID::maxResults.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_raycast deve essere attivata prima di utilizzare XrRaycastHitResultsANDROID
• type deve essere XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• results deve essere un puntatore a un array di strutture resultsCapacityInput XrRaycastHitResultANDROID-based
• Il parametro resultsCapacityInput deve essere maggiore di 0

La struttura XrRaycastHitResultANDROID è definita come:

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

Descrizioni dei membri

• type è il XrTrackableTypeANDROID del rilevabile colpito dal raycast.
• trackable è il XrTrackableANDROID colpito dal raycast o XR_NULL_TRACKABLE_ANDROID se il type tracciabile era XR_TRACKABLE_TYPE_DEPTH_ANDROID.
• pose è l'XrPosef colpito dal raycast.

XrRaycastHitResultANDROID contiene i dettagli di un rilevamento di un raggio.

XrRaycastHitResultANDROID::pose per un impatto con un piano deve essere tale che X e Z siano paralleli al piano e l'asse Y sia normale al piano.

Tipo di hit tracciabile	Descrizione
XR_TRACKABLE_TYPE_PLANE_ANDROID	Colpisce superfici orizzontali e/o verticali per determinare la profondità e l'orientamento corretti di un punto.
XR_TRACKABLE_TYPE_DEPTH_ANDROID	Utilizza le informazioni sulla profondità dell'intera scena per determinare la profondità e l'orientamento corretti di un punto.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_raycast deve essere attivata prima di utilizzare XrRaycastHitResultANDROID
• type deve essere un valore XrTrackableTypeANDROID valido

Codice di esempio per il raycasting

Il seguente codice di esempio mostra come eseguire raycast.

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

Nuove costanti enum

L'enumerazione XrStructureType è stata estesa con:

• XR_TYPE_RAYCAST_INFO_ANDROID
• XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Nuove strutture

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

Nuove funzioni

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

Problemi

Cronologia delle versioni

• Revisione 1, 02/10/2024 (Kenny Vercaemer)
  • Descrizione iniziale dell'estensione