Extension OpenXR XR_ANDROID_raycast

Chaîne de nom

XR_ANDROID_raycast

Type d'extension

Extension d'instance

Numéro d'extension enregistré

464

Révision

1

Dépendances d'extension et de version

XR_ANDROID_trackables

Date de dernière modification

2024-10-02

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Présentation

Cette extension permet à l'application d'effectuer des raycasts sur les éléments de suivi de l'environnement. Les rayons peuvent être utiles pour détecter les objets de l'environnement avec lesquels un rayon intersecterait. Exemple :

  • Pour déterminer où un objet flottant tomberait lorsqu'il est lâché, utilisez un rayon vertical.
  • Pour déterminer où un utilisateur regarde, utilisez un rayon de projection orienté vers l'avant.

Interroger les fonctionnalités de raycast compatibles

La fonction xrEnumerateRaycastSupportedTrackableTypesANDROID est définie comme suit:

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

Descriptions des paramètres

  • instance est l'instance Xr à partir de laquelle systemId a été récupéré.
  • systemId est l'XrSystemId dont les types de suivi compatibles pour le raycasting sont énumérés.
  • trackableTypeCapacityInput correspond à la capacité de trackableTypes, ou à 0 pour récupérer la capacité requise.
  • trackableTypeCountOutput est un pointeur vers le nombre de l'array ou un pointeur vers la capacité requise si trackableTypeCapacityInput est insuffisant.
    • trackableTypes est un pointeur vers un tableau de XrTrackableTypeANDROID, mais peut être NULL si trackableTypeCapacityInput est 0.
  • Pour obtenir une description détaillée de la récupération de la taille trackableTypes requise, consultez la section Paramètres de taille de la mémoire tampon.

xrEnumerateRaycastSupportedTrackableTypesANDROID énumère les types de traceurs compatibles avec le traçage par rayon de la session en cours.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • 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

Effectuer un raycast

La fonction xrRaycastANDROID est définie comme suit:

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

Descriptions des paramètres

L'application peut effectuer des raycasts en appelant xrRaycastANDROID.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 structure XrRaycastInfoANDROID est définie comme suit: 

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;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • maxResults est le nombre maximal de résultats à renvoyer pour uint32_t.
  • trackerCount correspond au nombre uint32_t du tableau trackers.
  • trackers est le tableau de XrTrackableTrackerANDROID contre lequel le rayon projeté doit être testé.
  • origin est le XrVector3f à partir duquel le rayon est lancé.
  • trajectory correspond au XrVector3f ciblé par le rayon.
  • space est l'espace Xr dans lequel le rayon est lancé.
  • time correspond à l'XrTime sur lequel le rayon est lancé.

La structure XrRaycastInfoANDROID décrit le rayon à lancer.

Utilisation valide (implicite)

La structure XrRaycastHitResultsANDROID est définie comme suit: 

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • resultsCapacityInput correspond à la capacité du tableau results, ou à 0 pour indiquer une requête visant à récupérer la capacité requise.
  • resultsCountOutput est un pointeur vers le nombre d'results écrits, ou un pointeur vers la capacité requise si resultsCapacityInput est insuffisant.
  • results est un pointeur vers un tableau de structures XrRaycastHitResultANDROID. Il peut être NULL si resultsCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille results requise, consultez la section Paramètres de taille de la mémoire tampon.

XrRaycastHitResultsANDROID contient le tableau des résultats d'un rayon de balayage.

L'environnement d'exécution doit définir resultsCountOutput comme inférieur ou égal à XrRaycastInfoANDROID::maxResults.

Utilisation valide (implicite)

La structure XrRaycastHitResultANDROID est définie comme suit: 

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

Descriptions des membres

  • type correspond au XrTrackableTypeANDROID de l'objet trackable touché par le raycast.
  • trackable correspond à l'élément XrTrackableANDROID que le raycast a touché, ou à XR_NULL_TRACKABLE_ANDROID si l'élément type traçable était XR_TRACKABLE_TYPE_DEPTH_ANDROID.
  • pose est l'XrPosef que le raycast a touché.

XrRaycastHitResultANDROID contient les détails d'un contact de raycast.

La XrRaycastHitResultANDROID::pose pour une collision avec un plan doit être telle que X et Z soient parallèles au plan, et que l'axe Y soit normal au plan.

Type d'appel traçable

Description

XR_TRACKABLE_TYPE_PLANE_ANDROID

Frappe des surfaces horizontales et/ou verticales pour déterminer la profondeur et l'orientation correctes d'un point.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Utilise les informations de profondeur de l'ensemble de la scène pour déterminer la profondeur et l'orientation correctes d'un point.

Utilisation valide (implicite)

Exemple de code pour le raycasting

L'exemple de code suivant montre comment effectuer des raycasts.

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

Nouvelles constantes d'énumération

L'énumération XrStructureType est étendue avec:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 1, 02/10/2024 (Kenny Vercaemer)
    • Description initiale de l'extension