Extensão OpenXR XR_ANDROID_raycast

String de nome

XR_ANDROID_raycast

Tipo de extensão

Extensão de instância

Número de extensão registrado

464

Revisão

1

Dependências de extensão e versão

XR_ANDROID_trackables

Data da última modificação

2024-10-02

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Visão geral

Essa extensão permite que o aplicativo execute raycasts contra rastreáveis no ambiente. Os raycasts podem ser úteis para detectar objetos no ambiente com que um raio se cruzaria. Exemplo:

  • Para determinar onde um objeto flutuante cairia quando lançado, use um raycast vertical.
  • Para determinar para onde um usuário está olhando, use um raycast voltado para a frente.

Consultar recursos de raycast compatíveis

A função xrEnumerateRaycastSupportedTrackableTypesANDROID é definida como:

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

Descrições dos parâmetros

  • instance é a XrInstance de onde systemId foi extraído.
  • systemId é o XrSystemId cujos tipos rastreáveis com suporte para raycasting estão sendo enumerados.
  • trackableTypeCapacityInput é a capacidade do trackableTypes ou 0 para recuperar a capacidade necessária.
  • trackableTypeCountOutput é um ponteiro para a contagem da matriz ou um ponteiro para a capacidade necessária caso trackableTypeCapacityInput seja insuficiente.
    • trackableTypes é um ponteiro para uma matriz de XrTrackableTypeANDROID, mas pode ser NULL se trackableTypeCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para conferir uma descrição detalhada de como recuperar o tamanho trackableTypes necessário.

xrEnumerateRaycastSupportedTrackableTypesANDROID enumera os tipos rastreáveis que oferecem suporte a raycasting pela sessão atual.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • 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

Realizar um raycast

A função xrRaycastANDROID é definida como:

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

Descrições dos parâmetros

O aplicativo pode executar raycasts chamando xrRaycastANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrRaycastInfoANDROID é definida como: 

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;

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • maxResults é o número máximo de resultados a serem retornados pela uint32_t.
  • trackerCount é a contagem de uint32_t da matriz trackers.
  • trackers é a matriz de XrTrackableTrackerANDROID que o raio fundido deve ser testado.
  • origin é o XrVector3f de onde o raio é lançado.
  • trajectory é o XrVector3f em que o raio é direcionado.
  • space é o XrSpace em que o raio é lançado.
  • time é o XrTime em que o raio é lançado.

A estrutura XrRaycastInfoANDROID descreve o feixe a ser transmitido.

Uso válido (implícito)

A estrutura XrRaycastHitResultsANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • resultsCapacityInput é a capacidade da matriz results ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • resultsCountOutput é um ponteiro para a contagem de results gravada ou um ponteiro para a capacidade necessária caso resultsCapacityInput seja insuficiente.
  • results é um ponteiro para uma matriz de estruturas XrRaycastHitResultANDROID. Ele pode ser NULL se resultsCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para conferir uma descrição detalhada de como recuperar o tamanho results necessário.

O XrRaycastHitResultsANDROID contém a matriz de acertos de um raycast.

O ambiente de execução precisa definir resultsCountOutput para ser menor ou igual a XrRaycastInfoANDROID::maxResults.

Uso válido (implícito)

A estrutura XrRaycastHitResultANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrTrackableTypeANDROID do rastreável que o raycast atingiu.
  • trackable é o XrTrackableANDROID que o raycast atingiu ou XR_NULL_TRACKABLE_ANDROID se o type rastreável foi XR_TRACKABLE_TYPE_DEPTH_ANDROID.
  • pose é o XrPosef que o raycast atingiu.

O XrRaycastHitResultANDROID contém os detalhes de um hit de raycast.

O XrRaycastHitResultANDROID::pose para um acerto de plano precisa ser de modo que X e Z sejam paralelos ao plano, e o eixo Y seja normal ao plano.

Tipo de hit rastreável

Descrição

XR_TRACKABLE_TYPE_PLANE_ANDROID

Bate em superfícies horizontais e/ou verticais para determinar a profundidade e a orientação corretas de um ponto.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Usa informações de profundidade de toda a cena para determinar a profundidade e a orientação corretas de um ponto.

Uso válido (implícito)

Exemplo de código para raycasting

O exemplo de código a seguir demonstra como 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]
}

Novas constantes de tipo enumerado

A enumeração XrStructureType foi ampliada com:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 1, 02/10/2024 (Kenny Vercaemer)
    • Descrição inicial da extensão