Estensione OpenXR XR_ANDROID_hand_mesh

Stringa del nome

XR_ANDROID_hand_mesh

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

704

Revisione

1

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2024-09-10

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Nihav Jain, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Panoramica

Questa estensione consente il rilevamento delle mani rappresentato come un mesh dinamico della mano.

Questa estensione è progettata per fornire buffer di vertici e indici per la mesh di una representation personalizzata delle mani dell'utente. Può essere utilizzato per occlusione e visualizzazione.

Questa estensione non deve essere utilizzata per altri scopi di monitoraggio delle mani.

I dati del monitoraggio delle mani possono essere informazioni personali sensibili e sono strettamente collegati alla privacy e all'integrità personali. È vivamente consigliato che le applicazioni che archiviano o trasferiscono dati sul rilevamento dei movimenti della mano chiedano sempre all'utente un'accettazione attiva e specifica.

Controlla la funzionalità del sistema

Un'applicazione può verificare se il sistema è in grado di creare mesh di tracciamento delle mani collegando una struttura XrSystemHandMeshTrackingPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties.

typedef struct XrSystemHandMeshTrackingPropertiesANDROID {
  XrStructureType    type;
  void*              next;
  XrBool32           supportsHandMeshTracking;
  XrBool32           supportsTextureUV;
  XrBool32           supportsVertexNormal;
} XrSystemHandMeshTrackingPropertiesANDROID;

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.
  • supportsHandMeshTracking è un XrBool32 che indica se il XrSystemId selezionato supporta il monitoraggio della mesh della mano.
  • supportsTextureUV è un XrBool32 che indica se il selezionato XrSystemId supporta le texture UV per i vertici del mesh.
  • supportsVertexNormal è un XrBool32 che indica se il XrSystemId selezionato supporta le normali dei vertici per i vertici del mesh.

L'applicazione deve evitare di utilizzare le funzionalità di mesh delle mani quando supportsHandMeshTracking è XR_FALSE, poiché ciò significa che il sistema non supporta il monitoraggio del mesh delle mani. In questo caso, xrCreateHandMeshTrackerANDROID restituirà XR_ERROR_FEATURE_UNSUPPORTED.

Se supportsHandMeshTracking restituisce XR_TRUE, il sistema supporta il monitoraggio della mesh della mano. Un'applicazione deve utilizzare XrHandMeshANDROID::indexCount e XrHandMeshANDROID::vertexCount per accedere ai buffer del mesh della mano e riutilizzarli nel proprio loop di rendering quando chiama xrGetHandMeshANDROID ogni frame.

Se supportsTextureUV restituisce XR_FALSE, il sistema non supporta le texture UV per i vertici del mesh e, di conseguenza, un'applicazione riceverebbe XrHandMeshANDROID::textureUVs NULL quando chiama xrGetHandMeshANDROID.

Se supportsVertexNormal restituisce XR_FALSE, il sistema non supporta le normali dei vertici per i vertici del mesh e, di conseguenza, un'applicazione riceverebbe XrHandMeshANDROID::normals NULL quando chiama xrGetHandMeshANDROID.

Utilizzo valido (implicito)

Creare un handle per il tracker mesh da polso

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

L'handle XrHandMeshTrackerANDROID rappresenta un tracker mesh per le mani per il monitoraggio del mesh delle mani e la gestione delle risorse correlate.

Questo handle può essere utilizzato per accedere ai buffer della mesh della mano utilizzando altre funzioni di questa estensione.

Un'applicazione può creare un handle XrHandMeshTrackerANDROID utilizzando la funzione xrCreateHandMeshTrackerANDROID. 

XrResult xrCreateHandMeshTrackerANDROID(
    XrSession                                   session,
    const XrHandMeshTrackerCreateInfoANDROID*   createInfo,
    XrHandMeshTrackerANDROID*                   handMeshTracker);

Descrizioni dei parametri

Se il sistema non supporta il monitoraggio della mesh della mano, xrCreateHandMeshTrackerANDROID restituirà XR_ERROR_FEATURE_UNSUPPORTED.

L'handle XrHandMeshTrackerANDROID possiede tutte le risorse per il monitoraggio del mesh della mano. Al termine delle esperienze di monitoraggio del mesh della mano, l'applicazione deve distruggere l'handle utilizzando la funzione xrDestroyHandMeshTrackerANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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 XrHandMeshTrackerCreateInfoANDROID descrive le informazioni per creare un handle XrHandMeshTrackerANDROID. 

typedef struct XrHandMeshTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrHandMeshTrackerCreateInfoANDROID;

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.

Utilizzo valido (implicito)

La funzione xrDestroyHandMeshTrackerANDROID rilascia handMeshTracker e le risorse sottostanti al termine delle esperienze di monitoraggio del mesh delle mani. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

Descrizioni dei parametri

Utilizzo valido (implicito)

Coerenza di thread

  • L'accesso a handMeshTracker 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

Individuare i mesh delle mani

L'applicazione può utilizzare la funzione xrGetHandMeshANDROID per recuperare il mesh della mano in un determinato timestamp. La posizione e la normale dei vertici del mesh della mano sono rappresentate nello spazio specificato da XrHandMeshGetInfoANDROID::baseSpace quando viene chiamata xrGetHandMeshANDROID.

XrResult xrGetHandMeshANDROID(
    XrHandMeshTrackerANDROID                    handMeshTracker,
    const XrHandMeshGetInfoANDROID*             getInfo,
    XrHandTrackingMeshesANDROID*                handMeshes);

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrGetHandMeshANDROID per accedere ai buffer della mesh della mano generati dal runtime.

L'applicazione deve chiamare xrBeginFrame almeno una volta durante la sessione prima della prima chiamata a xrGetHandMeshANDROID.

Un'applicazione deve utilizzare XrHandMeshANDROID::indexCount e XrHandMeshANDROID::vertexCount per accedere ai buffer della mesh della mano e riutilizzarli nel proprio loop di rendering quando chiama xrGetHandMeshANDROID ogni frame.

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_HANDLE_INVALID
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID

Un messaggio XrHandMeshGetInfoANDROID descrive le informazioni necessarie per ottenere i dati della mesh della mano. 

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

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.
  • baseSpace è un XrSpace che definisce lo spazio di riferimento in cui collocare la trasformazione per i vertici in time.
  • time è il XrTime che descrive il momento in cui l'applicazione vuole eseguire una query sul mesh della mano.

Utilizzo valido (implicito)

La struttura XrHandTrackingMeshesANDROID contiene i dati del mesh per entrambe le mani. 

typedef struct XrHandTrackingMeshesANDROID {
    XrStructureType      type;
    void*                next;
    XrHandMeshANDROID    leftHandMesh;
    XrHandMeshANDROID    rightHandMesh;
} XrHandTrackingMeshesANDROID;

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.
  • leftHandMesh è XrHandMeshANDROID per la mano sinistra.
  • rightHandMesh è XrHandMeshANDROID per la mano destra.

Utilizzo valido (implicito)

Una struttura XrHandMeshANDROID contiene dati e buffer per ricevere i dati di monitoraggio della mesh della mano dalla funzione xrGetHandMeshANDROID per una mano.

typedef struct XrHandMeshANDROID {
    XrBool32             isActive;
    XrTime               dynamicLastUpdateTime;
    uint32_t             indexCount;
    uint32_t             vertexCount;
    const uint32_t*      indices;
    const XrVector2f*    textureUVs;
    const XrVector3f*    positions;
    const XrVector3f*    normals;
    XrPosef              baseSpaceFromVertexSpace;
} XrHandMeshANDROID;

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.
  • isActive è un XrBool32 che indica se il tracker della maglia della mano attivo è attivo e se i dati della maglia sono validi.
  • dynamicLastUpdateTime è il XrTime che specifica l'ora dell'ultimo aggiornamento dei buffer dinamici.
  • indexCount è un uint32_t che funge da numero di indices della maglia della mano.
  • vertexCount è un uint32_t che funge da numero di positions della maglia della mano. Può essere utilizzato anche per textureUVs o normals se supportati dal sistema.
  • indices è un array di uint32_t che rappresenta gli indici della maglia per i vertici dei triangoli in ordine di avvolgimento antiorario. Il numero di valori indicati è indexCount.
  • textureUVs è NULL o un array di XrVector2f che rappresenta le coordinate della texture del vertice. Il numero di valori a cui si fa riferimento è vertexCount.
  • positions è un array di XrVector3f che rappresenta le posizioni dei vertici in baseSpaceFromVertexSpace. Il numero di valori a cui si fa riferimento è vertexCount.
  • normals è un NULL o un array di XrVector3f che rappresenta le normali dei vertici in baseSpaceFromVertexSpace. Il numero di valori a cui si fa riferimento è vertexCount.
  • baseSpaceFromVertexSpace è il vertice XrSpace situato in XrHandMeshGetInfoANDROID::baseSpace quando viene chiamato xrGetHandMeshANDROID. Le applicazioni possono utilizzarlo per trasformare lo spazio delle coordinate dei vertici e delle normali della mesh durante il rendering.

La mesh della mano è rappresentata in elenchi di triangoli e i vertici di ogni triangolo sono in ordine antiorario se guardi la mano dall'esterno.

Quando il valore isActive restituito è XR_FALSE, indica che la mano non è monitorata attivamente; ad esempio, la mano è al di fuori dell'intervallo del sensore, il lo stato attivo dell'input viene rimosso dall'applicazione o l'applicazione non ha le autorizzazioni per accedere ai dati del monitoraggio della mano.

Quando il valore isActive restituito è XR_TRUE, il mesh di monitoraggio delle mani rappresentato in indices e positions, inclusi textureUVs e normals se supportati dal sistema, viene aggiornato con i dati più recenti di XrHandMeshGetInfoANDROID::time specificato alla funzione xrGetHandMeshANDROID.

La memoria a cui fanno riferimento i buffer del mesh della mano restituiti in XrHandMeshANDROID è di proprietà del runtime e condivisa con l'applicazione. È possibile accedere in sicurezza alla memoria da qualsiasi thread fino alla successiva chiamata a xrBeginFrame, purché l'handle XrHandMeshTrackerANDROID sia valido.

  • I valori a cui fanno riferimento indices e textureUVs non sono dinamici
  • Il puntatore e i valori a cui fanno riferimento positions e normals sono dinamici e possono cambiare tra le chiamate a xrBeginFrame. L'applicazione può utilizzare dynamicLastUpdateTime per verificare se i valori sono cambiati dall'ultimo frame ed evitare l'elaborazione non necessaria dei dati quando non ci sono modifiche.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_hand_mesh deve essere attivata prima di utilizzare XrHandMeshANDROID
  • indices deve essere un puntatore a un valore uint32_t valido
  • textureUVs deve essere un puntatore a una struttura XrVector2f valida
  • positions deve essere un puntatore a una struttura XrVector3f valida
  • normals deve essere un puntatore a una struttura XrVector3f valida

Codice di esempio per il monitoraggio della mesh della mano

Il seguente codice di esempio mostra come accedere ai buffer della mesh della mano per il rendering.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup.
XrSpace appPlaySpace; // Created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateHandMeshTrackerANDROID xrCreateHandMeshTrackerANDROID; // previously initialized
PFN_xrDestroyHandMeshTrackerANDROID xrDestroyHandMeshTrackerANDROID; // previously initialized
PFN_xrGetHandMeshANDROID xrGetHandMeshANDROID; // previously initialized

// Inspect system capability
XrSystemHandMeshTrackingPropertiesANDROID handMeshTrackingProps = {
  .type = XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &handMeshTrackingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!handMeshTrackingProps.supportsHandMeshTracking) {
  // hand mesh tracking is not supported.
  return;
}

XrHandMeshTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
};
XrHandMeshTrackerANDROID handMeshTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateHandMeshTrackerANDROID(
    session, &trackerCreateInfo, &handMeshTracker));
// app update loop
while (true) {
    // ...
    // For every frame in frame loop
    // ...

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

    // ...
    XrHandMeshGetInfoANDROID getInfo = {
        .type = XR_TYPE_HAND_MESH_GET_INFO_ANDROID,
        .baseSpace = appPlaySpace,
        .time = time,
    };
    XrHandTrackingMeshesANDROID handMeshes = {
        .type = XR_TYPE_HAND_TRACKING_MESHES_ANDROID
    };
    CHK_XR(xrGetHandMeshANDROID(handMeshTracker, &getInfo, &handMeshes));

    if (handMeshes.leftHandMesh.isActive) {
        // access vertex/index buffers for rendering.
    }

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

CHECK_XR(xrDestroyHandMeshTracker(handMeshTracker));

Nuovi tipi di oggetti

Nuove costanti enum

L'enumerazione XrObjectType è estesa con:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

L'enumerazione XrStructureType è stata estesa con:

  • XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_HAND_MESH_GET_INFO_ANDROID
  • XR_TYPE_HAND_TRACKING_MESHES_ANDROID

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

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