XR_ANDROID_eye_tracking

String de nome

XR_ANDROID_eye_tracking

Tipo de extensão

Extensão de instância

Número de ramal registrado

457

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2025-01-17

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google

Visão geral

Essa extensão permite que os aplicativos obtenham a posição e a orientação dos olhos do usuário, bem como o status do acompanhamento ocular.

Os dados de acompanhamento ocular são fornecidos em dois modos: aproximado e preciso. O rastreamento aproximado fornece uma estimativa aproximada dos olhos do usuário, enquanto o rastreamento preciso fornece uma estimativa mais precisa. O rastreamento aproximado é destinado a aplicativos que querem fornecer uma representação básica semelhante a um avatar, enquanto o rastreamento preciso é destinado a aplicativos mais precisos.

Para interação, é preciso usar XR_EXT_eye_gaze_interaction.

Permissões

Os apps Android precisam ter a permissão android.permission.EYE_TRACKING_COARSE ou android.permission.EYE_TRACKING_FINE listada no manifesto. Essas permissões são consideradas perigosas. O aplicativo precisa solicitar a permissão no momento da execução para usar estas funções:

(nível de proteção: perigoso)

Inspecionar a capacidade do sistema

A estrutura XrSystemEyeTrackingPropertiesANDROID é definida como:

typedef struct XrSystemEyeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsEyeTracking;
} XrSystemEyeTrackingPropertiesANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • supportsEyeTracking é um XrBool32 que indica se o sistema atual oferece suporte ao acompanhamento ocular.

Um aplicativo pode inspecionar se o sistema é capaz de fazer o acompanhamento ocular estendendo o XrSystemProperties com a estrutura XrSystemEyeTrackingPropertiesANDROID ao chamar xrGetSystemProperties .

Se, e somente se, um ambiente de execução retornar XR_FALSE para supportsEyeTracking, ele precisará retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID .

Uso válido (implícito)

Criar um handle para o acompanhamento ocular

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

O identificador XrEyeTrackerANDROID representa um rastreador de acompanhamento ocular para acompanhar os olhos e mapear com precisão para onde o usuário está olhando.

Os dados de acompanhamento ocular são informações pessoais sensíveis e estão intimamente ligados à privacidade e integridade pessoal. É altamente recomendável que os aplicativos que armazenam ou transferem dados de acompanhamento ocular sempre peçam ao usuário uma aceitação ativa e específica para fazer isso.

O aplicativo usa esse identificador para acessar dados de acompanhamento ocular usando outras funções nessa extensão.

O acompanhamento ocular fornece a pose dos olhos e a representação do status na cena.

A função xrCreateEyeTrackerANDROID é definida como:

XrResult xrCreateEyeTrackerANDROID(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoANDROID*        createInfo,
    XrEyeTrackerANDROID*                        eyeTracker);

Descrições dos parâmetros

Um aplicativo cria um identificador XrEyeTrackerANDROID usando a função xrCreateEyeTrackerANDROID.

Se o sistema não for compatível com o acompanhamento ocular, o ambiente de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrEyeTrackerCreateInfoANDROID é definida como:

typedef struct XrEyeTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrEyeTrackerCreateInfoANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.

A estrutura XrEyeTrackerCreateInfoANDROID descreve as informações para criar um identificador XrEyeTrackerANDROID.

Uso válido (implícito)

A função xrDestroyEyeTrackerANDROID é definida como:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descrições dos parâmetros

A função xrDestroyEyeTrackerANDROID libera o eyeTracker e os recursos relacionados quando as experiências de acompanhamento ocular são concluídas.

Uso válido (implícito)

Concorrência segura

  • O acesso a eyeTracker e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Como receber informações sobre os olhos

A função xrGetCoarseTrackingEyesInfoANDROID é definida como:

XrResult xrGetCoarseTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

Descrições dos parâmetros

A função xrGetCoarseTrackingEyesInfoANDROID recebe as informações sobre os estados e as poses dos olhos de uma forma que preserva a privacidade do usuário.

O ambiente de execução precisa retornar XR_ERROR_PERMISSION_INSUFFICIENT se o aplicativo não tiver a permissão android.permission.EYE_TRACKING_COARSE.

As poses dos olhos são expressas em XrEyesGetInfoANDROID :: baseSpace em XrEyesGetInfoANDROID :: time .

A qualquer momento, a posição e a direção da pose dos olhos são rastreadas ou não. Isso significa que o ambiente de execução precisa definir XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ou limpar XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT no XrEyesANDROID :: eyes fornecido e definir XrEyesANDROID :: mode para indicar os estados de rastreamento.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A função xrGetFineTrackingEyesInfoANDROID é definida como:

XrResult xrGetFineTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

Descrições dos parâmetros

A função xrGetFineTrackingEyesInfoANDROID recebe as informações de estados e poses dos olhos com maior precisão do que xrGetCoarseTrackingEyesInfoANDROID .

O ambiente de execução precisa retornar XR_ERROR_PERMISSION_INSUFFICIENT se o aplicativo não tiver a permissão android.permission.EYE_TRACKING_FINE.

As informações dos olhos são resolvidas e relativas ao espaço de base no momento da chamada para xrGetFineTrackingEyesInfoANDROID usando XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . O ambiente de execução precisa resolver o local definido por XrEyesGetInfoANDROID :: baseSpace no momento da chamada.

A qualquer momento, a posição e a direção da pose dos olhos são rastreadas ou não. Isso significa que o ambiente de execução precisa definir XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ou limpar XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT no XrEyesANDROID :: eyes fornecido e definir XrEyesANDROID :: mode para indicar os estados de rastreamento.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrEyesGetInfoANDROID contém as informações necessárias para recuperar as poses e os estados dos olhos.

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
    XrSpace            baseSpace;
} XrEyesGetInfoANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • time é o XrTime em que as coordenadas são avaliadas em relação ao baseSpace .
  • baseSpace é o XrSpace em que as poses dos olhos serão retornadas.

Uso válido (implícito)

A estrutura XrEyesANDROID contém informações sobre os olhos rastreados.

typedef struct XrEyesANDROID {
    XrStructureType             type;
    void*                       next;
    XrEyeANDROID                eyes[XR_EYE_MAX_ANDROID];
    XrEyeTrackingModeANDROID    mode;
} XrEyesANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • eyes é uma matriz de XrEyeANDROID, de tamanho XR_EYE_MAX_ANDROID, para os olhos esquerdo e direito, indexados por XrEyeIndexANDROID .
  • mode é o XrEyeTrackingModeANDROID que indica qual dos olhos está sendo rastreado no momento.

Uso válido (implícito)

A estrutura XrEyeANDROID descreve o estado, a posição e a orientação de um olho.

typedef struct XrEyeANDROID {
    XrEyeStateANDROID    eyeState;
    XrPosef              eyePose;
} XrEyeANDROID;

Descrições dos membros

  • eyeState é o XrEyeStateANDROID de um olho.
  • eyePose é um XrPosef que define a posição e a orientação da pupila de um olho no frame de referência do XrEyesGetInfoANDROID :: baseSpace correspondente. Uma orientação de identidade aqui representa um eixo de coordenadas com +Z nos olhos do usuário, +X à direita e +Y para cima.

Uso válido (implícito)

A enumeração XrEyeStateANDROID identifica os diferentes estados dos olhos rastreados.

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeStateANDROID;

Os tipos enumerados têm os seguintes significados:

Descrição do tipo enumerado

XR_EYE_STATE_INVALID_ANDROID

Indica que o olho está em um estado de erro ou não está presente.

XR_EYE_STATE_GAZING_ANDROID

Indica que o olho está olhando para algo.

XR_EYE_STATE_SHUT_ANDROID

Indica que o olho está fechado devido a uma piscada.

A enumeração XrEyeIndexANDROID identifica o índice do olho esquerdo ou direito.

typedef enum XrEyeIndexANDROID {
    XR_EYE_INDEX_LEFT_ANDROID = 0,
    XR_EYE_INDEX_RIGHT_ANDROID = 1,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeIndexANDROID;

Os tipos enumerados têm os seguintes significados:

Descrição do tipo enumerado

XR_EYE_INDEX_LEFT_ANDROID

Olho esquerdo.

XR_EYE_INDEX_RIGHT_ANDROID

Olho direito.

A enumeração XrEyeTrackingModeANDROID identifica os diferentes estados dos olhos rastreados.

typedef enum XrEyeTrackingModeANDROID {
    XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID = 0,
    XR_EYE_TRACKING_MODE_RIGHT_ANDROID = 1,
    XR_EYE_TRACKING_MODE_LEFT_ANDROID = 2,
    XR_EYE_TRACKING_MODE_BOTH_ANDROID = 3,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeTrackingModeANDROID;

Os tipos enumerados têm os seguintes significados:

Descrição do tipo enumerado

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indica que o acompanhamento ocular não está ativo no momento.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Indica que apenas o olho direito está sendo rastreado.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Indica que apenas o olho esquerdo está sendo rastreado.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Indica que os olhos esquerdo e direito estão sendo rastreados.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID é o número máximo de olhos para os quais os dados de XrEyeANDROID são informados.

Exemplo de código para acompanhamento ocular

O exemplo de código a seguir demonstra como receber informações sobre os olhos em relação a um espaço de visualização.

XrSession session; // previously initialized, e.g. created at app startup.
XrSpace viewSpace; // space created for XR_REFERENCE_SPACE_TYPE_VIEW.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateEyeTrackerANDROID xrCreateEyeTrackerANDROID; // previously initialized
PFN_xrDestroyEyeTrackerANDROID xrDestroyEyeTrackerANDROID; // previously initialized
PFN_xrGetCoarseTrackingEyesInfoANDROID xrGetCoarseTrackingEyesInfoANDROID; // previously initialized
PFN_xrGetFineTrackingEyesInfoANDROID xrGetFineTrackingEyesInfoANDROID; // previously initialized

// This will use the XrSession that is bound to the eye tracker done at time of creation.
XrEyeTrackerANDROID eyeTracker;
XrEyeTrackerCreateInfoANDROID createInfo{
    .type = XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID,
    .next = nullptr};
CHK_XR(xrCreateEyeTrackerANDROID(session, &createInfo, &eyeTracker));

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;
    XrEyesANDROID fineEyesInfo{.type = XR_TYPE_EYES_ANDROID,
                               .next = nullptr,
                               .mode = XR_EYE_TRACKING_MODE_BOTH_ANDROID};
    XrEyesANDROID coarseEyesInfo{.type = XR_TYPE_EYES_ANDROID,
                                 .next = nullptr,
                                 .mode = XR_EYE_TRACKING_MODE_BOTH_ANDROID};
    XrEyesGetInfoANDROID eyesGetInfo{.type = XR_TYPE_EYES_GET_INFO_ANDROID,
                                     .next = nullptr,
                                     .time = time,
                                     .baseSpace = viewSpace};
    CHK_XR(xrGetCoarseTrackingEyesInfoANDROID(eyeTracker, &eyesGetInfo, &coarseEyesInfo));
    CHK_XR(xrGetFineTrackingEyesInfoANDROID(eyeTracker, &eyesGetInfo, &fineEyesInfo));

    // eyes tracking information is now available:
    // drawLeftEye(eyesInfo.eyes[XR_EYE_INDEX_LEFT_ANDROID].eyePose);
    // drawRightEye(eyesInfo.eyes[XR_EYE_INDEX_RIGHT_ANDROID].eyePose);

    // ...
    // Finish frame loop
    // ...
}

// after usage
CHK_XR(xrDestroyEyeTrackerANDROID(eyeTracker));

Novos tipos de objeto

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Estendendo XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Estendendo XrStructureType :

    • XR_TYPE_EYES_ANDROID
    • XR_TYPE_EYES_GET_INFO_ANDROID
    • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 17/01/2025 (Kenny Vercaemer)

    • Descrição inicial da extensão