Extensão OpenXR XR_ANDROID_depth_texture

String de nome

XR_ANDROID_depth_texture

Tipo de extensão

Extensão de instância

Número de extensão registrado

703

Revisão

1

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2024-09-11

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Sushant Kulkarni, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Visão geral

Essa extensão permite que o aplicativo solicite mapas de profundidade do ambiente real ao redor do headset e consulte as resoluções de profundidade compatíveis na criação.

Essa extensão tem como objetivo expor a profundidade bruta e suave para testes de oclusão, hit e outras tarefas específicas que usam a geometria precisa da cena, por exemplo, detecção de rosto falso.

Inspecionar o capability do sistema

A estrutura XrSystemDepthTrackingPropertiesANDROID é definida como:

typedef struct XrSystemDepthTrackingPropertiesANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           supportsDepthTracking;
} XrSystemDepthTrackingPropertiesANDROID;

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.
  • supportsDepthTracking é um XrBool32 que indica se o sistema atual oferece suporte ao rastreamento de profundidade.

Um aplicativo pode inspecionar se o sistema é capaz de rastrear a profundidade estendendo o XrSystemProperties com a estrutura XrSystemDepthTrackingPropertiesANDROID ao chamar xrGetSystemProperties.

Uso válido (implícito)

Resoluções de profundidade da consulta

A função xrEnumerateDepthResolutionsANDROID é definida como:

XrResult xrEnumerateDepthResolutionsANDROID(
    XrSession                                   session,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    XrDepthCameraResolutionANDROID*             resolutions);

Descrições dos parâmetros

  • session é a XrSession que enumera as resoluções de profundidade compatíveis.
  • resolutionCapacityInput é a capacidade do resolutions ou 0 para recuperar a capacidade necessária.
  • resolutionCountOutput é um ponteiro para a contagem de uint64_t resolutions gravada ou um ponteiro para a capacidade necessária caso resolutionCapacityInput seja insuficiente.
  • resolutions é um ponteiro para uma matriz de XrDepthCameraResolutionANDROID, mas pode ser NULL se resolutionCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho resolutions necessário.

xrEnumerateDepthResolutionsANDROID enumera as resoluções de profundidade com suporte à sessão atual. As resoluções de profundidade precisam estar em ordem da preferência de execução mais alta para a mais baixa. O aplicativo precisa usar a preferência mais alta compatível para ter o melhor desempenho e qualidade.

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_SIZE_INSUFFICIENT

O tipo enumerado XrDepthCameraResolutionANDROID descreve as resoluções de profundidade com suporte ao criar um XrDepthSwapchainANDROID. 

typedef enum XrDepthCameraResolutionANDROID {
    XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID = 0,
    XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID = 1,
    XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID = 2
    } XrDepthCameraResolutionANDROID;

Descrições de enumerantes

  • XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID: a resolução das imagens de profundidade e confiança é 80 x 80.
  • XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID: a resolução das imagens de profundidade e confiança é 160 x 160.
  • XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID: a resolução das imagens de profundidade e de confiança é 320 x 320.

Criar uma cadeia de troca de profundidade

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

Um XrDepthSwapchainANDROID é um identificador de swapchain de profundidade.

A função xrCreateDepthSwapchainANDROID é definida como: 

XrResult xrCreateDepthSwapchainANDROID(
    XrSession                                   session,
    const XrDepthSwapchainCreateInfoANDROID*    createInfo,
    XrDepthSwapchainANDROID*                    swapchain);

Descrições dos parâmetros

O aplicativo pode usar a função xrCreateDepthSwapchainANDROID para criar uma cadeia de troca de profundidade que gerencia imagens de profundidade e confiança.

O identificador de swapchain de profundidade retornado pode ser usado posteriormente em chamadas de API. O gerenciador XrDepthSwapchainANDROID precisa ser liberado usando a função xrDestroyDepthSwapchainANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

A estrutura XrDepthSwapchainCreateInfoANDROID é definida como: 

typedef struct XrDepthSwapchainCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrDepthCameraResolutionANDROID        resolution;
    XrDepthSwapchainCreateFlagsANDROID    createFlags;
} XrDepthSwapchainCreateInfoANDROID;

Descrições dos participantes

A estrutura XrDepthSwapchainCreateInfoANDROID oferece opções de criação para o XrDepthSwapchainANDROID quando transmitida para xrCreateDepthSwapchainANDROID.

Uso válido (implícito)

O XrDepthSwapchainCreateFlagsANDROID especifica as opções de criação para XrDepthSwapchainANDROID. 

typedef XrFlags64 XrDepthSwapchainCreateFlagsANDROID;

Os bits válidos para XrDepthSwapchainCreateFlagsANDROID são definidos por XrDepthSwapchainCreateFlagBitsANDROID, que é especificado como: 

// Flag bits for XrDepthSwapchainCreateFlagsANDROID
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID = 0x00000001;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000002;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID = 0x00000004;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000008;

A função xrDestroyDepthSwapchainANDROID é definida como: 

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

Descrições dos parâmetros

A função xrDestroyDepthSwapchainANDROID destrói a cadeia de troca de profundidade.

Uso válido (implícito)

Segurança da linha de execução

  • O acesso a swapchain 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

Acessar texturas de profundidade

A função xrEnumerateDepthSwapchainImagesANDROID é definida como: 

XrResult xrEnumerateDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    uint32_t                                    depthImageCapacityInput,
    uint32_t*                                   depthImageCountOutput,
    XrDepthSwapchainImageANDROID*               depthImages);

Descrições dos parâmetros

  • depthSwapchain é o XrDepthSwapchainANDROID para receber imagens.
  • depthImageCapacityInput é a capacidade da matriz depthImages ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • depthImageCountOutput é um ponteiro para a contagem de depthImages gravada ou um ponteiro para a capacidade necessária caso depthImageCapacityInput seja insuficiente.
  • depthImages é um ponteiro para uma matriz de estruturas XrDepthSwapchainImageANDROID. Ele pode ser NULL se depthImageCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho depthImages necessário.

xrEnumerateDepthSwapchainImagesANDROID preenche uma matriz de estruturas XrDepthSwapchainImageANDROID. Os recursos serão constantes e válidos durante a vida útil do XrDepthSwapchainANDROID. Essa função se comporta de maneira análoga a xrEnumerateSwapchainImages.

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_SIZE_INSUFFICIENT

A estrutura XrDepthSwapchainImageANDROID é definida como: 

typedef struct XrDepthSwapchainImageANDROID {
    XrStructureType    type;
    void*              next;
    const float*       rawDepthImage;
    const uint8_t*     rawDepthConfidenceImage;
    const float*       smoothDepthImage;
    const uint8_t*     smoothDepthConfidenceImage;
} XrDepthSwapchainImageANDROID;

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.
  • rawDepthImage é NULL ou o ponteiro para imagens de profundidade bruta para as visualizações esquerda e direita. Os valores têm unidades em metros. Valores especiais: 0.0 indica um pixel de profundidade inválido ou vazio na profundidade bruta. Inf indica a profundidade conhecida que está infinitamente distante.
  • rawDepthConfidenceImage é NULL ou o ponteiro para imagens de confiança de profundidade bruta para as visualizações esquerda e direita.
  • smoothDepthImage é NULL ou o ponteiro para suavizar imagens de profundidade para as visualizações esquerda e direita. Os valores têm unidades em metros. Valores especiais: 0.0 indica um pixel de profundidade inválido ou vazio na profundidade suave, Inf indica a profundidade conhecida que está infinitamente distante.
  • smoothDepthConfidenceImage é NULL ou o ponteiro para imagens de confiança de profundidade suave para as visualizações esquerda e direita.

XrDepthSwapchainImageANDROID representa as imagens de profundidade de um XrDepthSwapchainANDROID legível, alocado conforme descrito em XrDepthSwapchainCreateInfoANDROID::resolution e XrDepthSwapchainCreateInfoANDROID::createFlags ao chamar xrCreateDepthSwapchainANDROID. Para cada imagem de profundidade:

Uso válido (implícito)

A função xrAcquireDepthSwapchainImagesANDROID é definida como: 

XrResult xrAcquireDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    const XrDepthAcquireInfoANDROID*            acquireInfo,
    XrDepthAcquireResultANDROID*                acquireResult);

Descrições dos parâmetros

Os aplicativos podem usar a função xrAcquireDepthSwapchainImagesANDROID para adquirir o índice de imagem de swapchain mais recente disponível, como XrDepthAcquireResultANDROID::acquiredIndex, na matriz XrDepthSwapchainImageANDROID enumerada por xrEnumerateDepthSwapchainImagesANDROID. O XrDepthAcquireResultANDROID retornado também contém outras informações, como o campo de visão e a pose, que são necessárias para interpretar os dados de profundidade. É seguro ler do slot adquirido na matriz de imagens até a próxima chamada para xrAcquireDepthSwapchainImagesANDROID.

Não pode haver mais de uma chamada para xrAcquireDepthSwapchainImagesANDROID entre qualquer par de chamadas xrBeginFrame e xrEndFrame correspondentes em uma sessão.

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_DEPTH_NOT_AVAILABLE_ANDROID
  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID

A estrutura XrDepthAcquireInfoANDROID é definida como: 

typedef struct XrDepthAcquireInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             displayTime;
} XrDepthAcquireInfoANDROID;

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.
  • space é um XrSpace que define o frame de referência da pose retornada em XrDepthAcquireResultANDROID::views.
  • displayTime é um XrTime que especifica o tempo usado para calcular a pose retornada em XrDepthAcquireResultANDROID::views. Os aplicativos precisam transmitir o tempo de exibição previsto para o frame atual.

Uso válido (implícito)

A estrutura XrDepthAcquireResultANDROID é definida como: 

typedef struct XrDepthAcquireResultANDROID {
    XrStructureType       type;
    const void*           next;
    uint32_t              acquiredIndex;
    XrTime                exposureTimestamp;
    XrDepthViewANDROID    views[2];
} XrDepthAcquireResultANDROID;

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.
  • acquiredIndex é o índice da textura adquirida na matriz XrDepthSwapchainImageANDROID enumerada por xrEnumerateDepthSwapchainImagesANDROID.
  • exposureTimestamp é o XrTime que especifica o momento em que o mapa de profundidade foi capturado.
  • views é uma matriz de dois XrDepthViewANDROID, um para cada olho, em que o índice 0 é o olho esquerdo e o índice 1 é o olho direito.

Uso válido (implícito)

A estrutura XrDepthViewANDROID é definida como: 

typedef struct XrDepthViewANDROID {
    XrStructureType    type;
    const void*        next;
    XrFovf             fov;
    XrPosef            pose;
} XrDepthViewANDROID;

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.
  • fov é um XrFovf que especifica o campo de visão usado para gerar essa visualização. A visualização nunca é invertida horizontalmente nem verticalmente.
  • pose é um XrPosef que especifica a pose em que o mapa de profundidade foi renderizado. A moldura de referência é especificada em XrDepthAcquireInfoANDROID.

Uso válido (implícito)

Exemplo de código para rastreamento de profundidade

O exemplo de código abaixo demonstra como adquirir imagens de profundidade.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session; // previously initialized
XrSpace stageSpace; // space created for XR_REFERENCE_SPACE_TYPE_STAGE.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateDepthSwapchainANDROID xrCreateDepthSwapchainANDROID; // previously initialized
PFN_xrDestroyDepthSwapchainANDROID xrDestroyDepthSwapchainANDROID; // previously initialized
PFN_xrEnumerateDepthSwapchainImagesANDROID xrEnumerateDepthSwapchainImagesANDROID; // previously initialized
PFN_xrEnumerateDepthResolutionsANDROID xrEnumerateDepthResolutionsANDROID; // previously initialized
PFN_xrAcquireDepthSwapchainImagesANDROID xrAcquireDepthSwapchainImagesANDROID; // previously initialized

// Inspect system capability
XrSystemProperties properties{XR_TYPE_SYSTEM_PROPERTIES};
XrSystemDepthTrackingPropertiesANDROID depthTrackingProperties{XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID};
properties.next = &depthTrackingProperties;
CHK_XR(xrGetSystemProperties(instance, systemId, &properties));
if (!depthTrackingProperties.supportsDepthTracking) {
  // depth tracking is not supported.
  return;
}

// Query the supported depth resolution.
XrDepthCameraResolutionANDROID supportedDepthResolution;
uint32_t supportedResolutionCount = 0;
CHK_XR(xrEnumerateDepthResolutionsANDROID(
    session, 1, &supportedResolutionCount, &supportedDepthResolution));

// Define metadata to access the raw and smooth depth along with confidences.
XrDepthSwapchainCreateInfoANDROID swapchainCreateInfo = {
  .type = XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID,
  .next = nullptr,
  .createFlags =
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID,

  // Use the resolution supported by the runtime.
  .resolution = supportedDepthResolution,
};

XrDepthSwapchainANDROID depthSwapchain;
CHK_XR(xrCreateDepthSwapchainANDROID(
    session, &swapchainCreateInfo, &depthSwapchain));

// Enumerate depth images.
uint32_t imageCountOutput = 0;
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
    depthSwapchain, 0, &imageCountOutput, nullptr));
std::vector<XrDepthSwapchainImageANDROID> depthImages(imageCountOutput);
for (int i = 0; i < imageCountOutput; i++) {
  depthImages[i].type = XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID;
}
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
  depthSwapchain, imageCountOutput, &imageCountOutput, depthImages.data()));

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    XrDepthAcquireInfoANDROID acquireInfo = {
        .type = XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID,
        .space = stageSpace,
        .time = time};
    XrDepthAcquireResultANDROID acquireResult = {
        .type = XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID,
    };
    CHK_XR(xrAcquireDepthImagesANDROID(
        depthSwapchain, &acquireInfo, &acquireResult));

    // Each value in a depth image corresponds to a point in the real world.
    // The sample code in this section shows how to find the stageSpace position
    // of the point corresponding to a particular value in the depth image.

    // For this sample code, assume we are using a right handed coordinate system
    // with +X to the right, +Y up and -Z forward.

    XrDepthSwapchainImageANDROID *image =
        &depthImages[acquireResult.acquireIndex];

    // Assume supported resolution is XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID.
    const int imageResolution = 160;
    int imageY = // value in [0, imageResolution)
    int imageX = // value in [0, imageResolution)

    // Get depth value from left eye.
    // A right depth value would be obtained with the following expression:
    // depthR = image->rawDepthImage[imageResolution*imageResolution+i*imageResolution+j]
    float depthL = image->rawDepthImage[imageY*imageResolution + imageX];
    XrDepthViewANDROID viewL = acquireResult.views[0];

    float tanL = tanf(viewL.fov.angleLeft);
    float tanR = tanf(viewL.fov.angleRight);
    float tanU = tanf(viewL.fov.angleUp);
    float tanD = tanf(viewL.fov.angleDown);

    float s = (imageX + 0.5f) / (float)imageResolution;
    float t = (imageY + 0.5f) / (float)imageResolution;

    // Calculate the depth camera space position of the point
    // corresponding to this depth value.
    XrVector3f posInCameraSpace;
    posInCameraSpace.z = -depthL;
    posInCameraSpace.x = (tanL + (tanR - tanL)*s)*depthL;
    posInCameraSpace.y = (tanB + (tanU - tanB)*t)*depthL;

    XrPosef depthCameraPoseL = viewL.pose;
    // Transform posInCameraSpace by depthCameraPoseL

    // ...
    // Finish frame loop
    // ...
}

Novos tipos de objeto

Novas constantes de tipo enumerado

A enumeração XrObjectType é estendida com:

  • XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID

A enumeração XrResult foi ampliada com:

  • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID

A enumeração XrStructureType foi ampliada com:

  • XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
  • XR_TYPE_DEPTH_VIEW_ANDROID
  • XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID
  • XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
  • XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

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