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

Os dados de rastreamento 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 refinado é destinado a aplicativos mais precisos.

Para interação, XR_EXT_eye_gaze_interaction precisa ser usado.

Inspecionar a capacidade do sistema

A estrutura XrSystemEyeTrackingPropertiesANDROID é definida como:

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, indicando se o sistema atual é compatível com o rastreamento ocular.

Um aplicativo pode inspecionar se o sistema é capaz de fazer rastreamento ocular encadeando uma estrutura XrSystemEyeTrackingPropertiesANDROID às 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 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 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 representação de postura e 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 pode criar um identificador XrEyeTrackerANDROID usando a função xrCreateEyeTrackerANDROID.

Se o sistema não for compatível com o rastreamento ocular, 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 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 rastreamento 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 sobre estados e 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 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 postura dos olhos são rastreadas ou não rastreadas. 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 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_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: 

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 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 base no momento da chamada para xrGetFineTrackingEyesInfoANDROID usando XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

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

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    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, a postura dos olhos será relativa a este 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 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 para os olhos esquerdo e direito, indexada por XrEyeIndexANDROID.
  • mode é o XrEyeTrackingModeANDROID para indicar se os olhos estão acompanhando 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 de membros

  • eyeState é a XrEyeStateANDROID de um olho.
  • pose é uma XrPosef que define a posição e a orientação da origem de um olho no sistema de referência do XrEyesGetInfoANDROID::baseSpace correspondente. Uma orientação de identidade aqui representa eixos 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
} XrEyeStateANDROID;

Os tipos enumerados têm os seguintes significados:

Enum

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 olhar está fixo.

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

Os tipos enumerados têm os seguintes significados:

Enum

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:

Enum

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 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 objetos

Novas constantes de enumeração

  • XR_EYE_MAX_ANDROID

A enumeração XrObjectType foi estendida com:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

A enumeração XrStructureType foi estendida 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 enums

Novas estruturas

Novas funções

Problemas

Histórico de versões

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

OpenXR™ e o logotipo OpenXR são marcas registradas de propriedade da Khronos Group Inc. e estão registradas como marcas comerciais na China, na União Europeia, no Japão e no Reino Unido.