Extensión OpenXR XR_ANDROID_raycast

Cadena de nombre

XR_ANDROID_raycast

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

464

Revisión

1

Dependencias de extensiones y versiones

XR_ANDROID_trackables

Fecha de última modificación

2024-10-02

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Descripción general

Esta extensión permite que la aplicación realice proyecciones de rayos en elementos rastreables en el entorno. Los Raycasts pueden ser útiles para detectar objetos en el entorno con los que se cruzaría un rayo. Por ejemplo:

• Para determinar dónde caería un objeto flotante cuando se suelta, usa un rayo vertical.
• Para determinar hacia dónde mira un usuario, usa un rayo proyectado hacia adelante.

Precaución:
Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING en su manifiesto, ya que esta extensión depende de XR_ANDROID_trackables y expone la geometría del entorno. El permiso android.permission.SCENE_UNDERSTANDING se considera peligroso. (nivel de protección: peligroso)

Consulta las funciones de proyección de rayos compatibles

La función xrEnumerateRaycastSupportedTrackableTypesANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

• instance es el XrInstance del que se recuperó systemId.
• systemId es el XrSystemId cuyos tipos rastreables compatibles para el raycasting se enumeran.
• trackableTypeCapacityInput es la capacidad de trackableTypes o 0 para recuperar la capacidad requerida.
• trackableTypeCountOutput es un puntero al recuento del array o un puntero a la capacidad requerida en caso de que trackableTypeCapacityInput no sea suficiente.
  • trackableTypes es un puntero a un array de XrTrackableTypeANDROID, pero puede ser NULL si trackableTypeCapacityInput es 0.
• Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño trackableTypes requerido.

xrEnumerateRaycastSupportedTrackableTypesANDROID enumera los tipos rastreables que admiten el raycasting de la sesión actual.

Uso válido (implícito)

• La extensión XR_ANDROID_raycast debe estar habilitada antes de llamar a xrEnumerateRaycastSupportedTrackableTypesANDROID.
• instance debe ser un control XrInstance válido.
• trackableTypeCountOutput debe ser un puntero a un valor uint32_t.
• Si trackableTypeCapacityInput no es 0, trackableTypes debe ser un puntero a un array de valores trackableTypeCapacityInput XrTrackableTypeANDROID.

Códigos de retorno

Correcto

• XR_SUCCESS

Error

• 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

Realiza un raycast

La función xrRaycastANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

• session es la XrSession que realiza el raycast.
• rayInfo es el XrRaycastInfoANDROID que describe el rayo que se proyectará.
• results es un puntero al XrRaycastHitResultsANDROID que recibe los resultados del raycast.

La aplicación puede realizar raycasts llamando a xrRaycastANDROID.

• Si un rayo de rastreo interseca más elementos rastreables que XrRaycastHitResultsANDROID::maxResults, el entorno de ejecución debe mostrar los resultados de los hits más cercanos a XrRaycastHitResultsANDROID::origin del rayo.
• Si un rayo de luz intersecta un elemento rastreable de tipo XR_TRACKABLE_TYPE_ANDROID_PLANE que está incluido en otro plano, el entorno de ejecución debe mostrar solo el resultado del hit para el plano que lo incluye.
• El entorno de ejecución debe mostrar los resultados de los hits en orden de lo más cercano a lo más alejado desde XrRaycastInfoANDROID::origin a lo largo del vector XrRaycastInfoANDROID::trajectory.
• El entorno de ejecución debe mostrar XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID si xrEnumerateRaycastSupportedTrackableTypesANDROID no enumera el tipo rastreable correspondiente a los controladores XrTrackableTrackerANDROID en XrRaycastInfoANDROID::trackers.

Uso válido (implícito)

• La extensión XR_ANDROID_raycast debe estar habilitada antes de llamar a xrRaycastANDROID.
• session debe ser un identificador XrSession válido.
• rayInfo debe ser un puntero a una estructura XrRaycastInfoANDROID válida.
• results debe ser un puntero a una estructura XrRaycastHitResultsANDROID.

Códigos de retorno

Correcto

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Error

• 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 estructura XrRaycastInfoANDROID se define de la siguiente manera:

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;

Descripciones de los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
• maxResults es la cantidad máxima de resultados uint32_t que se mostrarán.
• trackerCount es el recuento de uint32_t del array trackers.
• trackers es el array de XrTrackableTrackerANDROID con el que se debe probar el rayo proyectado.
• origin es el XrVector3f desde el que se proyecta el rayo.
• trajectory es el XrVector3f al que se orienta el rayo.
• space es el XrSpace en el que se proyecta el rayo.
• time es el XrTime al que se proyecta el rayo.

La estructura XrRaycastInfoANDROID describe el rayo que se proyectará.

• El array XrRaycastInfoANDROID::trackers puede contener rastreadores de diferentes tipos.
• El array XrRaycastInfoANDROID::trackers no debe contener varios rastreadores del mismo tipo; de lo contrario, el entorno de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE.

Uso válido (implícito)

• La extensión XR_ANDROID_raycast debe estar habilitada antes de usar XrRaycastInfoANDROID.
• type debe ser XR_TYPE_RAYCAST_INFO_ANDROID.
• next debe ser NULL o un puntero válido a la próxima estructura en una cadena de estructuras.
• trackers debe ser un puntero a un array de controles XrTrackableTrackerANDROID trackerCount válidos.
• space debe ser un identificador de XrSpace válido.
• El parámetro trackerCount debe ser mayor que 0.
• Tanto space como los elementos de trackers deben haberse creado, asignado o recuperado desde la misma XrSession.

La estructura XrRaycastHitResultsANDROID se define de la siguiente manera:

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

Descripciones de los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
• resultsCapacityInput es la capacidad del array results, o 0 para indicar una solicitud para recuperar la capacidad requerida.
• resultsCountOutput es un puntero al recuento de results escrito o un puntero a la capacidad requerida en caso de que resultsCapacityInput sea insuficiente.
• results es un puntero a un array de estructuras XrRaycastHitResultANDROID. Puede ser NULL si resultsCapacityInput es 0.
• Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño results requerido.

XrRaycastHitResultsANDROID contiene el array de hits de un rayo de luz.

El entorno de ejecución debe establecer resultsCountOutput como menor o igual que XrRaycastInfoANDROID::maxResults.

Uso válido (implícito)

• La extensión XR_ANDROID_raycast debe estar habilitada antes de usar XrRaycastHitResultsANDROID.
• type debe ser XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID.
• next debe ser NULL o un puntero válido a la próxima estructura en una cadena de estructuras.
• results debe ser un puntero a un array de estructuras resultsCapacityInput basadas en XrRaycastHitResultANDROID.
• El parámetro resultsCapacityInput debe ser mayor que 0.

La estructura XrRaycastHitResultANDROID se define de la siguiente manera:

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

Descripciones de los miembros

• type es el XrTrackableTypeANDROID del elemento rastreable que golpeó el rayo.
• trackable es el XrTrackableANDROID que golpeó el rayo de luz o XR_NULL_TRACKABLE_ANDROID si el type rastreable era XR_TRACKABLE_TYPE_DEPTH_ANDROID.
• pose es el XrPosef que golpeó el rayo.

XrRaycastHitResultANDROID contiene los detalles de un hit de raycast.

XrRaycastHitResultANDROID::pose para un impacto de plano debe ser tal que X y Z sean paralelos al plano, y el eje Y sea normal al plano.

Tipo de hit rastreable	Descripción
XR_TRACKABLE_TYPE_PLANE_ANDROID	Detecta superficies horizontales o verticales para determinar la profundidad y orientación correctas de un punto.
XR_TRACKABLE_TYPE_DEPTH_ANDROID	Usa la información de profundidad de toda la escena para determinar la profundidad y la orientación correctas de un punto.

Uso válido (implícito)

• La extensión XR_ANDROID_raycast debe estar habilitada antes de usar XrRaycastHitResultANDROID.
• type debe ser un valor válido de XrTrackableTypeANDROID.

Código de ejemplo para el raycasting

En el siguiente ejemplo de código, se muestra cómo realizar 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]
}

Nuevas constantes de enum

La enumeración XrStructureType se extiende con lo siguiente:

• XR_TYPE_RAYCAST_INFO_ANDROID
• XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Nuevas estructuras

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

Funciones nuevas

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

Problemas

Historial de versiones

• Revisión 1, 2024-10-02 (Kenny Vercaemer)
  • Descripción inicial de la extensión