Extensión XR_ANDROID_depth_texture de OpenXR

Cadena de nombre

XR_ANDROID_depth_texture

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

703

Revisión

1

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de última modificación

2024-09-11

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Sushant Kulkarni, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Descripción general

Esta extensión permite que la aplicación solicite mapas de profundidad del entorno real alrededor de los auriculares y consulte las resoluciones de profundidad compatibles durante la creación.

El objetivo de esta extensión es exponer una profundidad sin procesar y suave para la oclusión, las pruebas de hit y otras tareas específicas que usan una geometría de escena precisa, por ejemplo, la detección de rostros falsos.

Cómo inspeccionar la capacidad del sistema

La estructura XrSystemDepthTrackingPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportsDepthTracking es un XrBool32 que indica si el sistema actual admite el seguimiento de profundidad.

Una aplicación puede inspeccionar si el sistema es capaz de realizar el seguimiento de profundidad extendiendo XrSystemProperties con la estructura XrSystemDepthTrackingPropertiesANDROID cuando se llama a xrGetSystemProperties.

Uso válido (implícito)

Resoluciones de profundidad de la consulta

La función xrEnumerateDepthResolutionsANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • session es la XrSession que enumera las resoluciones de profundidad compatibles.
  • resolutionCapacityInput es la capacidad de resolutions, o 0 para recuperar la capacidad requerida.
  • resolutionCountOutput es un puntero al recuento de resolutions uint64_t escrito o un puntero a la capacidad requerida en caso de que resolutionCapacityInput sea insuficiente.
  • resolutions es un puntero a un array de XrDepthCameraResolutionANDROID, pero puede ser NULL si resolutionCapacityInput es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño resolutions requerido.

xrEnumerateDepthResolutionsANDROID enumera las resoluciones de profundidad que admite la sesión actual. Las resoluciones de profundidad deben estar en orden de preferencia de tiempo de ejecución más alta a más baja. La aplicación debe usar la preferencia más alta que admita para obtener un rendimiento y una calidad óptimos.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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

La enumeración XrDepthCameraResolutionANDROID describe las resoluciones de profundidad compatibles cuando se crea un 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;

Descripciones de enumeradores

  • XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID: La resolución de las imágenes de profundidad y confianza es de 80 × 80.
  • XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID: La resolución de las imágenes de profundidad y confianza es de 160 × 160.
  • XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID: La resolución de las imágenes de profundidad y confianza es de 320 × 320.

Crea un grupo de intercambio de profundidad

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

Un XrDepthSwapchainANDROID es un identificador de cadena de intercambio de profundidad.

La función xrCreateDepthSwapchainANDROID se define de la siguiente manera: 

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

Descripciones de los parámetros

La aplicación puede usar la función xrCreateDepthSwapchainANDROID para crear un intercambio de profundidad que administre las imágenes de profundidad y confianza.

El control de intercambio de profundidad que se muestra puede usarse posteriormente en llamadas a la API. El control XrDepthSwapchainANDROID debe liberarse con la función xrDestroyDepthSwapchainANDROID.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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

La estructura XrDepthSwapchainCreateInfoANDROID se define de la siguiente manera: 

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

Descripciones de los miembros

La estructura XrDepthSwapchainCreateInfoANDROID proporciona opciones de creación para XrDepthSwapchainANDROID cuando se pasa a xrCreateDepthSwapchainANDROID.

Uso válido (implícito)

XrDepthSwapchainCreateFlagsANDROID especifica las opciones de creación para XrDepthSwapchainANDROID. 

typedef XrFlags64 XrDepthSwapchainCreateFlagsANDROID;

Los bits válidos para XrDepthSwapchainCreateFlagsANDROID se definen en XrDepthSwapchainCreateFlagBitsANDROID, que se especifica de la siguiente manera: 

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

La función xrDestroyDepthSwapchainANDROID se define de la siguiente manera: 

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

Descripciones de los parámetros

La función xrDestroyDepthSwapchainANDROID destruye el intercambio de profundidad.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a swapchain y a cualquier controlador secundario debe sincronizarse de forma externa.

Códigos de retorno

Correcto

  • XR_SUCCESS

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cómo acceder a las texturas de profundidad

La función xrEnumerateDepthSwapchainImagesANDROID se define de la siguiente manera: 

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

Descripciones de los parámetros

  • depthSwapchain es el XrDepthSwapchainANDROID del que se obtienen las imágenes.
  • depthImageCapacityInput es la capacidad del array depthImages, o 0 para indicar una solicitud para recuperar la capacidad requerida.
  • depthImageCountOutput es un puntero al recuento de depthImages escrito o un puntero a la capacidad requerida en caso de que depthImageCapacityInput no sea suficiente.
  • depthImages es un puntero a un array de estructuras XrDepthSwapchainImageANDROID. Puede ser NULL si depthImageCapacityInput es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño depthImages requerido.

xrEnumerateDepthSwapchainImagesANDROID completa un array de estructuras XrDepthSwapchainImageANDROID. Los recursos serán constantes y válidos durante toda la vida útil de XrDepthSwapchainANDROID. Esta función se comporta de manera análoga a xrEnumerateSwapchainImages.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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

La estructura XrDepthSwapchainImageANDROID se define de la siguiente manera: 

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • rawDepthImage es NULL o el puntero a las imágenes de profundidad sin procesar para las vistas izquierda y derecha. Los valores tienen unidades de metros. Valores especiales: 0.0 indica un píxel de profundidad no válido o vacío en la profundidad sin procesar, Inf indica una profundidad conocida que está infinitamente lejos.
  • rawDepthConfidenceImage es NULL o el puntero a las imágenes de confianza de profundidad sin procesar para las vistas izquierda y derecha.
  • smoothDepthImage es NULL o el puntero para suavizar las imágenes de profundidad para las vistas izquierda y derecha. Los valores tienen unidades de metros. Valores especiales: 0.0 indica un píxel de profundidad no válido o vacío en la profundidad suave, Inf indica una profundidad conocida que está infinitamente lejos.
  • smoothDepthConfidenceImage es NULL o el puntero para suavizar las imágenes de confianza de profundidad para las vistas izquierda y derecha.

XrDepthSwapchainImageANDROID representa las imágenes de profundidad de un XrDepthSwapchainANDROID legible, asignado como se describe en XrDepthSwapchainCreateInfoANDROID::resolution y XrDepthSwapchainCreateInfoANDROID::createFlags mientras se llama a xrCreateDepthSwapchainANDROID. Para cada imagen de profundidad, haz lo siguiente:

Uso válido (implícito)

La función xrAcquireDepthSwapchainImagesANDROID se define de la siguiente manera: 

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

Descripciones de los parámetros

Las aplicaciones pueden usar la función xrAcquireDepthSwapchainImagesANDROID para adquirir el índice de imagen de intercambio disponible más reciente, como XrDepthAcquireResultANDROID::acquiredIndex, en el array XrDepthSwapchainImageANDROID enumerado por xrEnumerateDepthSwapchainImagesANDROID. El XrDepthAcquireResultANDROID que se muestra también contiene otra información, como el campo de visión y la postura que son necesarios para interpretar los datos de profundidad. Es seguro leer desde el espacio adquirido en el array de imágenes hasta la próxima llamada a xrAcquireDepthSwapchainImagesANDROID.

Debe haber una sola llamada a xrAcquireDepthSwapchainImagesANDROID entre cualquier par de llamadas correspondientes a xrBeginFrame y xrEndFrame en una sesión.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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

La estructura XrDepthAcquireInfoANDROID se define de la siguiente manera: 

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • space es un XrSpace que define el marco de referencia de la pose que se muestra en XrDepthAcquireResultANDROID::views.
  • displayTime es un XrTime que especifica el tiempo que se usa para calcular la pose de la pose que se muestra en XrDepthAcquireResultANDROID::views. Las aplicaciones deben pasar su tiempo de visualización previsto para el fotograma actual.

Uso válido (implícito)

La estructura XrDepthAcquireResultANDROID se define de la siguiente manera: 

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • acquiredIndex es el índice de la textura adquirida en el array XrDepthSwapchainImageANDROID enumerado por xrEnumerateDepthSwapchainImagesANDROID.
  • exposureTimestamp es el XrTime que especifica la hora en la que se capturó el mapa de profundidad.
  • views es un array de dos XrDepthViewANDROID, uno para cada ojo, en el que el índice 0 es el ojo izquierdo y el índice 1 es el ojo derecho.

Uso válido (implícito)

La estructura XrDepthViewANDROID se define de la siguiente manera: 

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • fov es un XrFovf que especifica el campo de visión que se usa para generar esta vista. La vista nunca se invierte horizontal ni verticalmente.
  • pose es un XrPosef que especifica la pose desde la que se renderizó el mapa de profundidad. El marco de referencia se especifica en XrDepthAcquireInfoANDROID.

Uso válido (implícito)

Ejemplo de código para el seguimiento de profundidad

En el siguiente código de ejemplo, se muestra cómo adquirir imágenes de profundidad.

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
    // ...
}

Nuevos tipos de objetos

Nuevas constantes de enum

La enumeración XrObjectType se extiende con lo siguiente:

  • XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID

La enumeración XrResult se extiende con lo siguiente:

  • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID

La enumeración XrStructureType se extiende con lo siguiente:

  • 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

Nuevas enumeraciones

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

  • Revisión 1, 9 de septiembre de 2024 (Levana Chen)
    • Descripción inicial de la extensión