XR_ANDROID_eye_tracking

String de nome

XR_ANDROID_eye_tracking

Tipo de extensão

Extensão de instância

Número da extensão registrada

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

Não há reivindicações de IP conhecidas.

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 acompanhamento aproximado fornece uma estimativa aproximada dos olhos do usuário, enquanto o acompanhamento preciso oferece 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, XR_EXT_eye_gaze_interaction deve ser usado.

Permissões

Os aplicativos 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 da seguinte maneira:

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

Descrições de membros

  • 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 OpenXR principal ou nesta extensão.
  • supportsEyeTracking é um XrBool32 que indica se o sistema atual é compatível com o acompanhamento ocular.

Um aplicativo pode inspecionar se o sistema é capaz de 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 , o ambiente de execução deverá retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID .

Uso válido (implícito)

Como criar um handle para rastreador ocular

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

O identificador XrEyeTrackerANDROID representa um rastreador ocular para rastrear os olhos e mapeia 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 recomendado 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 postura e a representação do status dos olhos 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 tempo de execução deverá 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 de membros

  • 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 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 subjacentes 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

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 de estados e poses dos olhos de uma forma que preserva a privacidade do usuário.

O tempo 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 .

Em qualquer momento, a posição e a direção da postura dos olhos são rastreadas ou não rastreadas. 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 informações sobre estados e poses dos olhos com mais precisão do que xrGetCoarseTrackingEyesInfoANDROID .

O tempo 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 tempo de execução precisa resolver o local definido por XrEyesGetInfoANDROID :: baseSpace no momento da chamada.

Em qualquer momento, a posição e a direção da postura dos olhos são rastreadas ou não rastreadas. 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 poses e estados dos olhos.

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

Descrições de membros

  • 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 OpenXR principal ou nesta extensão.
  • time é o XrTime em que as coordenadas são avaliadas em relação ao baseSpace .
  • baseSpace é o XrSpace a que as poses dos olhos serão relativas em time .

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 de membros

  • 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 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 quais olhos estão sendo rastreados 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 de 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 correspondente :: baseSpace . Uma orientação de identidade aqui representa um eixo de coordenadas com +Z para os olhos do usuário, +X para a 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 da enumeração

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 no momento.

XR_EYE_STATE_SHUT_ANDROID

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

A enumeração XrEyeIndexANDROID identifica o índice dos olhos 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 da enumeração

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 da enumeração

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 rastreando.

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 enumeração

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Extensão de XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Extensão de 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