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 raycasts 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)

• L'extension XR_ANDROID_raycast doit être activée avant d'appeler xrEnumerateRaycastSupportedTrackableTypesANDROID.
• instance doit être un identifiant XrInstance valide.
• trackableTypeCountOutput doit être un pointeur vers une valeur uint32_t
• Si trackableTypeCapacityInput n'est pas 0, trackableTypes doit être un pointeur vers un tableau de valeurs trackableTypeCapacityInput XrTrackableTypeANDROID.

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

• session est l'XrSession qui effectue le raycast.
• rayInfo est l'XrRaycastInfoANDROID qui décrit le rayon à lancer.
• results est un pointeur vers XrRaycastHitResultsANDROID, qui reçoit les résultats du raycast.

L'application peut effectuer des raycasts en appelant xrRaycastANDROID.

• Si un raycast intersecte plus de traceurs que XrRaycastHitResultsANDROID::maxResults, l'environnement d'exécution doit renvoyer les résultats des intersections les plus proches de l'origine de rayon XrRaycastHitResultsANDROID.
• Si un raycast intersecte un élément traçable de type XR_TRACKABLE_TYPE_ANDROID_PLANE, qui est subsumé par un autre plan, l'environnement d'exécution doit renvoyer le résultat de la collision uniquement pour le plan subsumant.
• L'environnement d'exécution doit renvoyer les résultats des intersections dans l'ordre des plus proches aux plus éloignées à partir de XrRaycastInfoANDROID::origin le long du vecteur XrRaycastInfoANDROID::trajectory.
• L'environnement d'exécution doit renvoyer XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID si le type de suivi correspondant aux poignées XrTrackableTrackerANDROID dans XrRaycastInfoANDROID::trackers n'est pas énuméré par xrEnumerateRaycastSupportedTrackableTypesANDROID.

Utilisation valide (implicite)

• L'extension doit être activée avant d'appeler xrRaycastANDROID.XR_ANDROID_raycast
• session doit être un identifiant XrSession valide.
• rayInfo doit être un pointeur vers une structure XrRaycastInfoANDROID valide.
• results doit être un pointeur vers une structure XrRaycastHitResultsANDROID.

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.

• Le tableau XrRaycastInfoANDROID::trackers peut contenir des traceurs de différents types.
• Le tableau XrRaycastInfoANDROID::trackers ne doit pas contenir plusieurs traceurs du même type, sinon l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE.

Utilisation valide (implicite)

• L'extension XR_ANDROID_raycast doit être activée avant d'utiliser XrRaycastInfoANDROID.
• type doit être XR_TYPE_RAYCAST_INFO_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante d'une chaîne de structures.
• trackers doit être un pointeur vers un tableau de poignées XrTrackableTrackerANDROID trackerCount valides.
• space doit être un gestionnaire XrSpace valide.
• Le paramètre trackerCount doit être supérieur à 0.
• space et les éléments de trackers doivent avoir été créés, alloués ou récupérés à partir de la même XrSession.

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 écrites 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.

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

Utilisation valide (implicite)

• L'extension XR_ANDROID_raycast doit être activée avant d'utiliser XrRaycastHitResultsANDROID.
• type doit être XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
• results doit être un pointeur vers un tableau de structures resultsCapacityInput basées sur XrRaycastHitResultANDROID.
• Le paramètre resultsCapacityInput doit être supérieur à 0.

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.

Utilisation valide (implicite)

• L'extension XR_ANDROID_raycast doit être activée avant d'utiliser XrRaycastHitResultANDROID.
• type doit être une valeur XrTrackableTypeANDROID valide.

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

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

Nouvelles fonctions

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

Problèmes

Historique des versions

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

OpenXR™ et le logo OpenXR sont des marques appartenant à The Khronos Group Inc. et sont enregistrés en tant que marques en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.