Estensione OpenXR XR_ANDROID_depth_texture

Stringa del nome

XR_ANDROID_depth_texture

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

703

Revisione

1

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2024-09-11

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Sushant Kulkarni, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Panoramica

Questa estensione consente all'applicazione di richiedere mappe di profondità dell'ambiente reale intorno al visore e di eseguire query sulle risoluzioni di profondità supportate al momento della creazione.

Questa estensione ha lo scopo di esporre una profondità non elaborata e uniforme per l'occlusione, i test di corrispondenza e altre attività specifiche che utilizzano una geometria della scena accurata, ad esempio il rilevamento di volti contraffatti.

Controlla la funzionalità del sistema

La struttura XrSystemDepthTrackingPropertiesANDROID è definita come segue:

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • supportsDepthTracking è un XrBool32 che indica se il sistema attuale supporta il rilevamento della profondità.

Un'applicazione può verificare se il sistema è in grado di rilevare la profondità estendendo XrSystemProperties con la struttura XrSystemDepthTrackingPropertiesANDROID quando chiama xrGetSystemProperties.

Utilizzo valido (implicito)

Risoluzioni della profondità delle query

La funzione xrEnumerateDepthResolutionsANDROID è definita come:

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

Descrizioni dei parametri

  • session è la XrSession che enumera le risoluzioni di profondità supportate.
  • resolutionCapacityInput è la capacità del resolutions o 0 per recuperare la capacità richiesta.
  • resolutionCountOutput è un puntatore al conteggio di uint64_t resolutions scritti o un puntatore alla capacità richiesta nel caso in cui resolutionCapacityInput sia insufficiente.
  • resolutions è un puntatore a un array di XrDepthCameraResolutionANDROID, ma può essere NULL se resolutionCapacityInput è 0.
  • Per una descrizione dettagliata del recupero della dimensione resolutions richiesta, consulta la sezione Parametri di dimensione del buffer.

xrEnumerateDepthResolutionsANDROID enumera le risoluzioni di profondità supportate dalla sessione corrente. Le risoluzioni di profondità devono essere elencate in ordine dalla preferenza di runtime più alta a quella più bassa. L'applicazione deve utilizzare la preferenza più alta supportata per un rendimento e una qualità ottimali.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

L'enum XrDepthCameraResolutionANDROID descrive le risoluzioni di profondità supportate durante la creazione di 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;

Descrizioni degli enumeranti

  • XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID: la risoluzione delle immagini di profondità e confidenza è 80 x 80.
  • XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID: la risoluzione delle immagini di profondità e di confidenza è 160 x 160.
  • XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID: la risoluzione delle immagini di profondità e di confidenza è 320 x 320.

Crea una swapchain di profondità

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

Un XrDepthSwapchainANDROID è un handle della swapchain di profondità.

La funzione xrCreateDepthSwapchainANDROID è definita come: 

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

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrCreateDepthSwapchainANDROID per creare una swapchain di profondità che gestisce sia le immagini di profondità sia quelle di confidenza.

L'handle della swapchain di profondità restituito può essere utilizzato successivamente nelle chiamate API. L'handle XrDepthSwapchainANDROID deve essere eventualmente liberato utilizzando la funzione xrDestroyDepthSwapchainANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrDepthSwapchainCreateInfoANDROID è definita come segue: 

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

Descrizioni dei membri

La struttura XrDepthSwapchainCreateInfoANDROID fornisce opzioni di creazione per XrDepthSwapchainANDROID quando viene passata a xrCreateDepthSwapchainANDROID.

Utilizzo valido (implicito)

XrDepthSwapchainCreateFlagsANDROID specifica le opzioni di creazione per XrDepthSwapchainANDROID. 

typedef XrFlags64 XrDepthSwapchainCreateFlagsANDROID;

I bit validi per XrDepthSwapchainCreateFlagsANDROID sono definiti da XrDepthSwapchainCreateFlagBitsANDROID, che è specificato come: 

// 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 funzione xrDestroyDepthSwapchainANDROID è definita come: 

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

Descrizioni dei parametri

La funzione xrDestroyDepthSwapchainANDROID distrugge la swapchain di profondità.

Utilizzo valido (implicito)

Coerenza di thread

  • L'accesso a swapchain e a eventuali handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Accedere alle texture di profondità

La funzione xrEnumerateDepthSwapchainImagesANDROID è definita come segue: 

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

Descrizioni dei parametri

  • depthSwapchain è la XrDepthSwapchainANDROID da cui recuperare le immagini.
  • depthImageCapacityInput è la capacità dell'array depthImages o 0 per indicare una richiesta di recupero della capacità richiesta.
  • depthImageCountOutput è un puntatore al conteggio di depthImages scritto o un puntatore alla capacità richiesta nel caso in cui depthImageCapacityInput sia insufficiente.
  • depthImages è un puntatore a un array di strutture XrDepthSwapchainImageANDROID. Può essere NULL se depthImageCapacityInput è 0.
  • Per una descrizione dettagliata del recupero della dimensione depthImages richiesta, consulta la sezione Parametri di dimensione del buffer.

xrEnumerateDepthSwapchainImagesANDROID riempie un array di strutture XrDepthSwapchainImageANDROID. Le risorse saranno costanti e valide per tutta la durata di XrDepthSwapchainANDROID. Questa funzione si comporta in modo analogo a xrEnumerateSwapchainImages.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrDepthSwapchainImageANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • rawDepthImage è NULL o il puntatore alle immagini di profondità non elaborate sia per la visualizzazione a sinistra che per quella a destra. I valori sono in metri. Valori speciali: 0.0 indica un pixel di profondità non valido o vuoto nella profondità non elaborata, Inf indica la profondità nota che è effettivamente infinitamente lontana,
  • rawDepthConfidenceImage è NULL o il puntatore alle immagini di confidenza della profondità non elaborata sia per la visualizzazione a sinistra che a destra.
  • smoothDepthImage è NULL o il cursore per levigare le immagini di profondità sia per la vista sinistra che per quella destra. I valori sono in metri. Valori speciali: 0.0 indica un pixel di profondità non valido o vuoto nella profondità uniforme, Inf indica una profondità nota che è praticamente infinitamente lontana.
  • smoothDepthConfidenceImage è NULL o il cursore per smussare le immagini di confidenza della profondità sia per le visualizzazioni a sinistra che a destra.

XrDepthSwapchainImageANDROID rappresenta le immagini di profondità di un XrDepthSwapchainANDROID leggibile, allocata come descritto in XrDepthSwapchainCreateInfoANDROID::resolution e XrDepthSwapchainCreateInfoANDROID::createFlags durante la chiamata xrCreateDepthSwapchainANDROID. Per ogni immagine di profondità:

Utilizzo valido (implicito)

La funzione xrAcquireDepthSwapchainImagesANDROID è definita come segue: 

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

Descrizioni dei parametri

Le applicazioni possono utilizzare la funzione xrAcquireDepthSwapchainImagesANDROID per acquisire l'indice immagine della serie di scambi più recente disponibile, ad esempio XrDepthAcquireResultANDROID::acquiredIndex, nell'array XrDepthSwapchainImageANDROID enumerato da xrEnumerateDepthSwapchainImagesANDROID. L'oggetto XrDepthAcquireResultANDROID restituito contiene anche altre informazioni, come il campo visivo e la posa, necessarie per interpretare i dati di profondità. È possibile leggere dallo slot acquisito nell'array di immagini fino alla successiva chiamata a xrAcquireDepthSwapchainImagesANDROID.

Non deve essere presente più di una chiamata a xrAcquireDepthSwapchainImagesANDROID tra qualsiasi coppia di chiamate xrBeginFrame e xrEndFrame corrispondenti in una sessione.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrDepthAcquireInfoANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • space è un XrSpace che definisce il frame di riferimento della posa restituita in XrDepthAcquireResultANDROID::views.
  • displayTime è un XrTime che specifica il tempo utilizzato per calcolare la posa per la posa restituita in XrDepthAcquireResultANDROID::views. Le applicazioni devono trasmettere il tempo di visualizzazione previsto per il frame corrente.

Utilizzo valido (implicito)

La struttura XrDepthAcquireResultANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • acquiredIndex è l'indice della texture acquisita nell'array XrDepthSwapchainImageANDROID enumerato da xrEnumerateDepthSwapchainImagesANDROID.
  • exposureTimestamp è il XrTime che specifica l'ora in cui è stata acquisita la mappa di profondità.
  • views è un array di due XrDepthViewANDROID, uno per ciascun occhio, dove l'indice 0 è l'occhio sinistro e l'indice 1 è l'occhio destro.

Utilizzo valido (implicito)

La struttura XrDepthViewANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • fov è un XrFovf che specifica il campo visivo utilizzato per generare questa visualizzazione. La visualizzazione non viene mai capovolta orizzontalmente né verticalmente.
  • pose è un XrPosef che specifica la posa da cui è stata visualizzata la mappa di profondità. Il frame di riferimento è specificato in XrDepthAcquireInfoANDROID.

Utilizzo valido (implicito)

Codice di esempio per il rilevamento della profondità

Il seguente codice di esempio mostra come acquisire immagini di profondità.

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

Nuovi tipi di oggetti

Nuove costanti enum

L'enumerazione XrObjectType è estesa con:

  • XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID

L'enumerazione XrResult è stata estesa con:

  • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID

L'enumerazione XrStructureType è stata estesa con:

  • 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

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

  • Revisione 1, 09-09-2024 (Levana Chen)
    • Descrizione iniziale dell'estensione