Extensão OpenXR XR_ANDROID_avatar_eyes

String de nome

XR_ANDROID_avatar_eyes

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

2024-09-30

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Spencer Quin, Google

Jared Finder, Google

Levana Chen, 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.

Essa extensão tem como objetivo tornar a representação de status e pose dos olhos dos avatares mais realistas. Para isso:

  • Ele permite estados não rastreados, como piscar.
  • Ele permite o rastreamento monocular ou binocular.

Essa extensão não pode ser usada para outros fins de rastreamento ocular. Para interação, XR_EXT_eye_gaze_interaction deve ser usado.

Rastreador ocular

Um rastreador ocular é um dispositivo de detecção que rastreia os olhos e mapeia com precisão para onde o usuário está olhando. O principal objetivo dessa extensão é mapear os olhares dos usuários para os avatares deles em uma cena virtual.

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.

  • Um aplicativo vai receber XR_ERROR_PERMISSION_INSUFFICIENT ao tentar criar um eye tracker ativo até que o acesso ao eye tracker seja permitido.

Inspecionar o capability do sistema

Um aplicativo pode inspecionar se o sistema oferece suporte aos olhos do avatar agrupando uma estrutura XrSystemAvatarEyesPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties. Se supportsAvatarEyes retornar XR_FALSE, um aplicativo vai receber XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

Descrições dos participantes

  • 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 núcleo do OpenXR ou nesta extensão.
  • supportsAvatarEyes é um XrBool32, indicando se o sistema atual oferece suporte aos olhos do avatar.

Uso válido (implícito)

Criar uma alça do rastreador ocular

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

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

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

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

Se o sistema não oferecer suporte ao rastreamento ocular, XR_ERROR_FEATURE_UNSUPPORTED será retornado por 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

A estrutura XrEyeTrackerCreateInfoANDROID é definida como: 

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

Descrições dos participantes

  • 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 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 xrGetEyesInfoANDROID é definida como:

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

Descrições dos parâmetros

A função xrGetEyesInfoANDROID recebe as informações de estados e posições dos olhos.

As informações dos olhos são resolvidas e relativas ao espaço base no momento da chamada para xrGetEyesInfoANDROID 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

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

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

Descrições dos participantes

  • 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 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 dessa 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 sendo rastreados 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 é o 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 visão em relação a um espaço de visualização.

XrSession session; // previously initialized, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // 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 é estendida 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_AVATAR_EYES_PROPERTIES_ANDROID

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 1, 04/09/2024 (Levana Chen)
    • Descrição inicial da extensão