Extensão OpenXR XR_ANDROID_eye_tracking

String de nome

XR_ANDROID_eye_tracking

Tipo de extensão

Extensão de instância

Número de extensão registrado

457

Revisão

1

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 IP 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, além do status do rastreamento ocular.

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

Para interação, XR_EXT_eye_gaze_interaction precisa ser usado.

Inspecionar o recurso do sistema

A estrutura XrSystemEyeTrackingPropertiesANDROID é definida como:

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

Descrições dos participantes

  • type é o XrStructureType desta 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.
  • supportsEyeTracking é um XrBool32, que indica se o sistema atual oferece suporte ao rastreamento ocular.

Um aplicativo pode inspecionar se o sistema é capaz de rastrear os olhos encadeando uma estrutura XrSystemEyeTrackingPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties. Se supportsEyeTracking retornar XR_FALSE, um aplicativo vai receber XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

Uso válido (implícito)

Criar uma alça do rastreador ocular

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

O identificador XrEyeTrackerANDROID representa um rastreador ocular para rastrear olhos e mapear com precisão o que o usuário está olhando.

Os dados de rastreamento ocular podem ser 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 rastreamento ocular sempre peçam ao usuário uma aceitação ativa e específica para fazer isso.

Esse identificador pode ser usado para acessar dados de rastreamento ocular usando outras funções nesta extensão.

O rastreamento ocular fornece a representação do status e da pose 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 pode criar um identificador XrEyeTrackerANDROID usando a função xrCreateEyeTrackerANDROID.

Se o sistema não oferecer suporte ao rastreamento ocular, o XR_ERROR_FEATURE_UNSUPPORTED será retornado de xrCreateEyeTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_FEATURE_UNSUPPORTED

A estrutura XrEyeTrackerCreateInfoANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType desta 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.

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 rastreamento ocular são concluídas.

Uso válido (implícito)

Segurança da linha de execução

  • 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 posições dos olhos de uma maneira que preserva a privacidade do usuário.

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

As informações dos olhos são resolvidas e relativas ao espaço base no momento da chamada para xrGetCoarseTrackingEyesInfoANDROID usando XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

Em qualquer momento, a posição e a direção da pose dos olhos são rastreadas ou não. Isso significa que os aplicativos podem esperar que XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sejam definidos ou limpos no XrEyesANDROID::eyes fornecido e que XrEyesANDROID::mode indique 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_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_TIME_INVALID
  • XR_ERROR_PERMISSION_INSUFFICIENT

A função xrGetFineTrackingEyesInfoANDROID é definida como: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Descrições dos parâmetros

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

As informações dos olhos são resolvidas e relativas ao espaço base no momento da chamada para xrGetFineTrackingEyesInfoANDROID usando XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

Em qualquer momento, a posição e a direção da pose dos olhos são rastreadas ou não. Isso significa que os aplicativos podem esperar que XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sejam definidos ou limpos no XrEyesANDROID::eyes fornecido e que XrEyesANDROID::mode indique 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_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_TIME_INVALID
  • XR_ERROR_PERMISSION_INSUFFICIENT

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

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

Descrições dos participantes

  • type é o XrStructureType desta 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.
  • time é o XrTime em que as coordenadas são avaliadas em relação ao baseSpace.
  • baseSpace a pose dos olhos será relativa a esse XrSpace 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 dos participantes

  • type é o XrStructureType desta 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.
  • eyes é uma matriz de XrEyeANDROID para os olhos esquerdo e direito, indexados por XrEyeIndexANDROID.
  • mode é o XrEyeTrackingModeANDROID para indicar se os olhos estão rastreando e quais.

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 participantes

  • eyeState é a XrEyeStateANDROID de um olho.
  • pose é um XrPosef que define a posição e a orientação da origem 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 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
} XrEyeStateANDROID;

Os tipos enumerados têm os seguintes significados:

Tipo enumerado

Descriçã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.

XR_EYE_STATE_SHUT_ANDROID

Indica que o olho está fechado devido a um piscar ou piscar.

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
} XrEyeIndexANDROID;

Os tipos enumerados têm os seguintes significados:

Tipo enumerado

Descrição

XR_EYE_INDEX_LEFT_ANDROID

Olho esquerdo.

XR_EYE_INDEX_RIGHT_ANDROID

Olho direito.

A enumeração XrEyeTrackingModeANDROID identifica os diferentes modos de 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
} XrEyeTrackingModeANDROID;

Os tipos enumerados têm os seguintes significados:

Tipo enumerado

Descrição

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indica que o rastreamento ocular não está ativo.

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 rastreamento ocular

O exemplo de código abaixo demonstra como receber informações de olho 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

Novas constantes de tipo enumerado

  • XR_EYE_MAX_ANDROID

A enumeração XrObjectType foi ampliada com:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

A enumeração XrStructureType foi ampliada com:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 1, 2025-01-17 (Kenny Vercaemer)
    • Descrição inicial da extensão

O OpenXR™ e o logotipo do OpenXR são marcas registradas do The Khronos Group Inc. e estão registrados como marca registrada na China, na União Europeia, no Japão e no Reino Unido.