O SDK do Android XR agora está disponível na prévia para desenvolvedores. Queremos saber sua opinião Acesse nossa página de suporte para entrar em contato.

Esta página foi traduzida pela API Cloud Translation.

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

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 deve ser usado.

Inspecionar o capability 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)

A extensão XR_ANDROID_eye_tracking precisa ser ativada antes de usar XrSystemEyeTrackingPropertiesANDROID.
type precisa ser XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID
next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas

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

session é um identificador XrSession em que o rastreamento ocular vai estar ativo.
createInfo é o XrEyeTrackerCreateInfoANDROID usado para especificar o rastreamento ocular.
eyeTracker é o identificador XrEyeTrackerANDROID retornado.

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)

A extensão XR_ANDROID_eye_tracking precisa ser ativada antes de chamar xrCreateEyeTrackerANDROID.
session precisa ser um identificador XrSession válido
createInfo precisa ser um ponteiro para uma estrutura XrEyeTrackerCreateInfoANDROID válida.
eyeTracker precisa ser um ponteiro para um identificador XrEyeTrackerANDROID

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 extensão XR_ANDROID_eye_tracking precisa ser ativada antes de usar XrEyeTrackerCreateInfoANDROID.
type precisa ser XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas

A função xrDestroyEyeTrackerANDROID é definida como:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descrições dos parâmetros

eyeTracker é um XrEyeTrackerANDROID criado anteriormente por xrCreateEyeTrackerANDROID.

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)

A extensão XR_ANDROID_eye_tracking precisa ser ativada antes de chamar xrDestroyEyeTrackerANDROID.
eyeTracker precisa ser um identificador XrEyeTrackerANDROID válido.

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

eyeTracker é um XrEyeTrackerANDROID criado anteriormente por xrCreateEyeTrackerANDROID.
getInfo é um ponteiro para XrEyesGetInfoANDROID usado para especificar qual saída é necessária.
infoOutput é um ponteiro para XrEyesANDROID que contém as informações dos olhos retornadas, incluindo poses e estados.

A função xrGetCoarseTrackingEyesInfoANDROID recebe as informações de estados e posições 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 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)

A extensão XR_ANDROID_eye_tracking precisa ser ativada antes de chamar xrGetCoarseTrackingEyesInfoANDROID.
eyeTracker precisa ser um identificador XrEyeTrackerANDROID válido
getInfo precisa ser um ponteiro para uma estrutura XrEyesGetInfoANDROID válida.
eyesOutput precisa ser um ponteiro para uma estrutura XrEyesANDROID

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

eyeTracker é um XrEyeTrackerANDROID criado anteriormente por xrCreateEyeTrackerANDROID.
getInfo é um ponteiro para XrEyesGetInfoANDROID usado para especificar qual saída é necessária.
infoOutput é um ponteiro para XrEyesANDROID que contém as informações dos olhos retornadas, incluindo poses e estados. A função xrGetFineTrackingEyesInfoANDROID extrai as informações de estados e posições dos olhos com maior precisão do que xrGetCoarseTrackingEyesInfoANDROID.

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.

Uso válido (implícito)

A extensão XR_ANDROID_eye_tracking precisa ser ativada antes de chamar xrGetFineTrackingEyesInfoANDROID.
eyeTracker precisa ser um identificador XrEyeTrackerANDROID válido
getInfo precisa ser um ponteiro para uma estrutura XrEyesGetInfoANDROID válida.
eyesOutput precisa ser um ponteiro para uma estrutura XrEyesANDROID

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 extensão XR_ANDROID_eye_tracking precisa ser ativada antes de usar XrEyesGetInfoANDROID.
type precisa ser XR_TYPE_EYES_GET_INFO_ANDROID
next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
baseSpace precisa ser um identificador XrSpace válido

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 extensão XR_ANDROID_eye_tracking precisa ser ativada antes de usar XrEyesANDROID.
type precisa ser XR_TYPE_EYES_ANDROID
next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
Qualquer elemento de eyes precisa ser uma estrutura XrEyeANDROID válida
mode precisa ser um valor XrEyeTrackingModeANDROID válido

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 extensão XR_ANDROID_eye_tracking precisa ser ativada antes de usar XrEyeANDROID.
eyeState precisa ser um valor XrEyeStateANDROID válido

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));