XR_EXT_spatial_persistence

Name String

XR_EXT_spatial_persistence

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

764

Revisione

1

Stato della ratifica

Ratificato

Dipendenze di estensioni e versioni

XR_EXT_spatial_entity
e
XR_EXT_future

Collaboratori

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Panoramica

Questa estensione consente alle applicazioni di rilevare e correlare le entità spaziali tra sessioni di applicazioni, sessioni OpenXR e più contesti spaziali OpenXR all'interno di una sessione. L'estensione XR_EXT_spatial_entity ha stabilito che un'entità all'interno di un XrSpatialContextEXT è rappresentata da un XrSpatialEntityIdEXT . Questa estensione amplia questo concetto stabilendo che un'entità, se persistente, è rappresentata da un XrUuid tra le sessioni dell'applicazione e di OpenXR, ovvero un'applicazione può utilizzare l'XrUuid fornito da questa estensione per identificare un'entità tra le sessioni. Questa estensione fornisce anche utili sovrapposizioni con l'estensione XR_EXT_spatial_entity per scoprire le entità persistenti nell'ambiente dell'utente e la possibilità di eseguire query sui dati dei relativi componenti.

Contesto di persistenza spaziale

Crea un contesto di persistenza spaziale

XR_DEFINE_HANDLE(XrSpatialPersistenceContextEXT)

L'handle XrSpatialPersistenceContextEXT rappresenta la connessione a uno spazio di archiviazione di entità spaziali persistenti.

La funzione xrCreateSpatialPersistenceContextAsyncEXT è definita come:

XrResult xrCreateSpatialPersistenceContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialPersistenceContextCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Descrizioni dei parametri

  • session è un XrSession in cui sarà attivo il contesto di persistenza spaziale.
  • createInfo è l'oggetto XrSpatialPersistenceContextCreateInfoEXT utilizzato per specificare i parametri del contesto di persistenza spaziale.
  • future è un puntatore a un XrFutureEXT .

Un'applicazione può creare un handle XrSpatialPersistenceContextEXT utilizzando la funzione xrCreateSpatialPersistenceContextAsyncEXT e configurare l'ambito del contesto di persistenza in createInfo .

Il runtime deve restituire XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT se XrSpatialPersistenceContextCreateInfoEXT :: scope non è enumerato da xrEnumerateSpatialPersistenceScopesEXT .

Se un runtime applica un sistema di autorizzazioni per controllare l'accesso dell'applicazione allo spazio di archiviazione permanente rappresentato da XrSpatialPersistenceContextEXT , il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT se queste autorizzazioni non sono state concesse all'applicazione.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

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

La struttura XrSpatialPersistenceContextCreateInfoEXT è definita come:

typedef struct XrSpatialPersistenceContextCreateInfoEXT {
    XrStructureType                 type;
    const void*                     next;
    XrSpatialPersistenceScopeEXT    scope;
} XrSpatialPersistenceContextCreateInfoEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • scope è un XrSpatialPersistenceScopeEXT che definisce l'ambito di archiviazione del contesto di persistenza.

La struttura XrSpatialPersistenceContextCreateInfoEXT descrive le informazioni per creare un handle XrSpatialPersistenceContextEXT.

Utilizzo valido (implicito)

typedef enum XrSpatialPersistenceScopeEXT {
    XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT = 1000781000,
    XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1 = 1000808000,
    XR_SPATIAL_PERSISTENCE_SCOPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceScopeEXT;

L'enumerazione XrSpatialPersistenceScopeEXT identifica i diversi tipi di ambiti del contesto di persistenza.

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT

Fornisce all'applicazione l'accesso di sola lettura (ovvero l'applicazione non può modificare lo store associato a questo ambito) alle entità spaziali persistenti e gestite dal sistema. L'applicazione può utilizzare l'UUID nel componente di persistenza per questo ambito per correlare le entità tra contesti spaziali e riavvii del dispositivo.

XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT

Le operazioni di persistenza e l'accesso ai dati sono limitati alle ancora spaziali, sullo stesso dispositivo, per lo stesso utente e la stessa app (aggiunta dall'estensione XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1

Le operazioni di persistenza e l'accesso ai dati sono limitati agli ancoraggi spaziali, di proprietà e gestiti dallo stesso progetto cloud. (Aggiunto dall'estensione XR_ANDROIDX1_spatial_anchor_cloud_sharing)

La funzione xrEnumerateSpatialPersistenceScopesEXT è definita come segue:

XrResult xrEnumerateSpatialPersistenceScopesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    persistenceScopeCapacityInput,
    uint32_t*                                   persistenceScopeCountOutput,
    XrSpatialPersistenceScopeEXT*               persistenceScopes);

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è l'XrSystemId di cui verranno enumerati gli ambiti di persistenza spaziale.
  • persistenceScopeCapacityInput è la capacità dell'array persistenceScopes o 0 per indicare una richiesta di recupero della capacità richiesta.
  • persistenceScopeCountOutput è il numero di ambiti di persistenza o la capacità richiesta nel caso in cui persistenceScopeCapacityInput non sia sufficiente.
  • persistenceScopes è un array di XrSpatialPersistenceScopeEXT . Può essere NULL se persistenceScopeCapacityInput è 0.
  • Consulta il capitolo Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero della dimensione persistenceScopes richiesta.

L'applicazione può enumerare l'elenco degli ambiti di persistenza spaziale supportati da un determinato XrSystemId utilizzando xrEnumerateSpatialPersistenceScopesEXT .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_persistence deve essere abilitata prima di chiamare xrEnumerateSpatialPersistenceScopesEXT
  • instance deve essere un handle XrInstance valido
  • persistenceScopeCountOutput deve essere un puntatore a un valore uint32_t
  • Se persistenceScopeCapacityInput non è 0 , persistenceScopes deve essere un puntatore a un array di valori persistenceScopeCapacityInput XrSpatialPersistenceScopeEXT

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La funzione xrCreateSpatialPersistenceContextCompleteEXT è definita come:

XrResult xrCreateSpatialPersistenceContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialPersistenceContextCompletionEXT* completion);

Descrizioni dei parametri

xrCreateSpatialPersistenceContextCompleteEXT completa l'operazione asincrona avviata da xrCreateSpatialPersistenceContextAsyncEXT . Il runtime deve restituire XR_ERROR_FUTURE_PENDING_EXT se future non è in stato Pronto. Il runtime deve restituire XR_ERROR_FUTURE_INVALID_EXT se future è già stato completato o annullato.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrCreateSpatialPersistenceContextCompletionEXT è definita come:

typedef struct XrCreateSpatialPersistenceContextCompletionEXT {
    XrStructureType                         type;
    void*                                   next;
    XrResult                                futureResult;
    XrSpatialPersistenceContextResultEXT    createResult;
    XrSpatialPersistenceContextEXT          persistenceContext;
} XrCreateSpatialPersistenceContextCompletionEXT;

Descrizioni dei membri

Codici di reso futuri

Valori futureResult:

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_PERMISSION_INSUFFICIENT

Se futureResult e createResult sono entrambi codici di operazione riuscita, persistenceContext deve essere valido. Se persistenceContext è valido, deve rimanere tale nel ciclo di vita di xrCreateSpatialPersistenceContextAsyncEXT :: session o finché l'applicazione non utilizza xrDestroySpatialPersistenceContextEXT con persistenceContext , a seconda di quale evento si verifica per primo.

Il runtime deve impostare createResult solo se futureResult è un codice di esito positivo.

Utilizzo valido (implicito)

typedef enum XrSpatialPersistenceContextResultEXT {
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT = 0,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT = -1000781001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT = -1000781002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1 = -1000808000,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1 = -1000808001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1 = -1000808002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1 = -1000808003,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceContextResultEXT;

L'enumerazione XrSpatialPersistenceContextResultEXT identifica i diversi tipi di codici di risultato per un'operazione di persistenza. Gli errori durante le operazioni di persistenza non sono sempre sotto il controllo dell'applicazione e questa enumerazione viene utilizzata per comunicare questi casi. Analogamente a XrResult , i codici di esito positivo nell'enumerazione XrSpatialPersistenceContextResultEXT sono valori non negativi, mentre i codici di errore sono valori negativi.

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT

L'operazione del contesto di persistenza è riuscita.

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT

L'operazione di persistenza non è riuscita perché l'entità non è stata monitorata dal runtime. (Aggiunto dall'estensione XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT

L'UUID di persistenza fornito non è stato trovato nello spazio di archiviazione. (Aggiunto dall'estensione XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1

L'operazione di persistenza non è riuscita perché la localizzazione non è riuscita. (Aggiunto dall'estensione XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1

L'operazione di persistenza non è riuscita perché la funzionalità della mappa di localizzazione non è sufficiente. (Aggiunto dall'estensione XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1

L'operazione di persistenza non è riuscita perché la connessione di rete non è riuscita. (Aggiunto dall'estensione XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1

L'operazione di persistenza non è riuscita a causa del timeout della rete. (Aggiunto dall'estensione XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Elimina il contesto di persistenza spaziale

La funzione xrDestroySpatialPersistenceContextEXT è definita come:

XrResult xrDestroySpatialPersistenceContextEXT(
    XrSpatialPersistenceContextEXT              persistenceContext);

Descrizioni dei parametri

L'applicazione può utilizzare xrDestroySpatialPersistenceContextEXT per rilasciare l'handle persistenceContext al termine delle attività di persistenza spaziale.

Il runtime non deve distruggere le risorse sottostanti per persistenceContext quando viene chiamato xrDestroySpatialPersistenceContextEXT se sono presenti handle XrSpatialContextEXT validi a cui persistenceContext è stato collegato tramite XrSpatialContextPersistenceConfigEXT . Questo perché le risorse del contesto di persistenza sono ancora utilizzate dal contesto spaziale per rilevare le entità persistenti. In questo caso, l'eliminazione dell'handle del contesto di persistenza rimuove solo l'accesso dell'applicazione a queste risorse.

Le risorse per un XrSpatialPersistenceContextEXT eliminato devono essere liberate quando vengono eliminati tutti gli handle XrSpatialContextEXT a cui era collegato il contesto di persistenza.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a persistenceContext e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Scopri le entità persistenti

Componente di persistenza

Le entità spaziali persistenti hanno il componente di persistenza che il runtime deve includere negli snapshot di rilevamento e aggiornamento se XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT è abilitato durante la creazione di XrSpatialContextEXT e incluso in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes o XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Dati dei componenti

La struttura XrSpatialPersistenceDataEXT è definita come:

typedef struct XrSpatialPersistenceDataEXT {
    XrUuid                          persistUuid;
    XrSpatialPersistenceStateEXT    persistState;
} XrSpatialPersistenceDataEXT;

Descrizioni dei membri

Utilizzo valido (implicito)

typedef enum XrSpatialPersistenceStateEXT {
    XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT = 2,
    XR_SPATIAL_PERSISTENCE_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceStateEXT;

L'enumerazione XrSpatialPersistenceStateEXT identifica i diversi stati dell'UUID persistente.

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT

L'UUID persistente è stato caricato correttamente dallo spazio di archiviazione.

XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT

L'UUID persistente non è stato trovato nello spazio di archiviazione ed è stato rimosso o non è mai stato presente.

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentPersistenceListEXT è definita come:

typedef struct XrSpatialComponentPersistenceListEXT {
    XrStructureType                 type;
    void*                           next;
    uint32_t                        persistDataCount;
    XrSpatialPersistenceDataEXT*    persistData;
} XrSpatialComponentPersistenceListEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • persistDataCount è un uint32_t che descrive il conteggio degli elementi nell'array persistData.
  • persistData è un array di XrSpatialPersistenceDataEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentPersistenceListEXT si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se persistDataCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

A differenza degli altri componenti, il runtime deve impostare i dati per XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT indipendentemente da XrSpatialEntityTrackingStateEXT .

Utilizzo valido (implicito)

Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, l'applicazione può attivarla includendo l'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena successiva di XrSpatialCapabilityConfigurationBaseHeaderEXT . Se l'applicazione include XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT nell'elenco dei componenti abilitati, deve includere anche XrSpatialContextPersistenceConfigEXT nella catena successiva di XrSpatialContextCreateInfoEXT, altrimenti il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT da xrCreateSpatialContextAsyncEXT .

Configura il contesto spaziale con i contesti di persistenza

La struttura XrSpatialContextPersistenceConfigEXT è definita come:

typedef struct XrSpatialContextPersistenceConfigEXT {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 persistenceContextCount;
    const XrSpatialPersistenceContextEXT*    persistenceContexts;
} XrSpatialContextPersistenceConfigEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • persistenceContextCount è un uint32_t che descrive il conteggio degli elementi nell'array persistenceContexts.
  • persistenceContexts è un array di XrSpatialPersistenceContextEXT .

Un'applicazione può aggiungere XrSpatialContextPersistenceConfigEXT alla catena successiva di XrSpatialContextCreateInfoEXT . In questo modo, l'oggetto XrSpatialContextEXT creato verrà configurato con persistenceContexts e l'applicazione potrà rilevare le entità spaziali persistenti nello spazio di archiviazione rappresentato dagli handle XrSpatialPersistenceContextEXT in persistenceContexts .

Utilizzo valido (implicito)

Crea snapshot di rilevamento

Scopri le entità con UUID specifici

La struttura XrSpatialDiscoveryPersistenceUuidFilterEXT è definita come:

typedef struct XrSpatialDiscoveryPersistenceUuidFilterEXT {
    XrStructureType    type;
    const void*        next;
    uint32_t           persistedUuidCount;
    const XrUuid*      persistedUuids;
} XrSpatialDiscoveryPersistenceUuidFilterEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • persistedUuidCount è un uint32_t che descrive il conteggio degli elementi nell'array persistedUuids
  • persistedUuids è un array di XrUuid .

L'applicazione può utilizzare XrSpatialDiscoveryPersistenceUuidFilterEXT nella catena successiva di XrSpatialDiscoverySnapshotCreateInfoEXT per limitare l'operazione di rilevamento solo alle entità i cui UUID persistenti si trovano nell'insieme di UUID forniti in persistedUuids .

Se l'applicazione aggiunge XrSpatialDiscoveryPersistenceUuidFilterEXT nella catena successiva di XrSpatialDiscoverySnapshotCreateInfoEXT, ma xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext non è stato configurato con alcun XrSpatialPersistenceContextEXT utilizzando XrSpatialContextPersistenceConfigEXT, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrCreateSpatialDiscoverySnapshotAsyncEXT .

Il runtime deve trattare il filtro XrSpatialDiscoveryPersistenceUuidFilterEXT come una condizione "AND" con qualsiasi altro filtro fornito in XrSpatialDiscoverySnapshotCreateInfoEXT o nella catena successiva. Il runtime deve trattare l'array persistedUuids stesso come una condizione "OR", ovvero filtrare le entità che hanno uno degli UUID forniti nell'array.

Il runtime deve includere una voce nello snapshot creato per ciascuno degli UUID in persistedUuids per i quali è stato in grado di determinare lo stato XrSpatialPersistenceStateEXT in questo momento.

  • Se il runtime ha trovato l'UUID nello spazio di archiviazione:

    • Il runtime deve impostare XrSpatialPersistenceStateEXT in XrSpatialPersistenceDataEXT di questa entità su XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT .
    • Il runtime deve includere un XrSpatialEntityIdEXT valido per questa entità nello snapshot creato.
    • Il runtime deve impostare XrSpatialEntityTrackingStateEXT di quell'entità su XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT se sta monitorando attivamente l'entità e dispone di dati validi per i suoi componenti. In caso contrario, il runtime deve impostare XrSpatialEntityTrackingStateEXT su XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT .

  • Se il runtime ha stabilito che l'UUID non è presente nel suo spazio di archiviazione (indipendentemente dal fatto che l'UUID non sia mai stato presente nello spazio di archiviazione o che sia stato presente una volta, ma non sia più persistente), allora:

  • Se il runtime non è stato in grado di determinare se l'UUID è presente o meno nel suo spazio di archiviazione, non deve includerlo nello snapshot.

L'applicazione può anche utilizzare XrSpatialDiscoveryPersistenceUuidFilterEXT nella catena successiva di XrSpatialComponentDataQueryConditionEXT per eseguire query su entità di UUID specifici negli snapshot esistenti. Se utilizzato con XrSpatialComponentDataQueryConditionEXT , se XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids contiene un XrUuid che non è presente in XrSpatialSnapshotEXT , il runtime non deve includere una voce per quell'XrUuid nel risultato della query. Inoltre, l'ordine (sequenza) delle entità nel risultato della query potrebbe non corrispondere all'ordine degli UUID forniti in XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids . L'applicazione deve includere XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes e XrSpatialComponentPersistenceListEXT nella catena successiva di XrSpatialComponentDataQueryResultEXT, quindi controllare XrSpatialPersistenceDataEXT :: persistUuid di ogni indice dei risultati della query per capire a quale UUID corrisponde l'indice dei risultati corrente.

Utilizzo valido (implicito)

Scopri tutte le entità persistenti

Se l'applicazione utilizza xrCreateSpatialDiscoverySnapshotAsyncEXT senza XrSpatialDiscoveryPersistenceUuidFilterEXT e con un XrSpatialContextEXT configurato con un XrSpatialPersistenceContextEXT , il runtime deve includere nello snapshot creato le entità persistenti nello spazio di archiviazione rappresentato da XrSpatialPersistenceContextEXT e soddisfare i filtri forniti in XrSpatialDiscoverySnapshotCreateInfoEXT . Per queste entità:

  • Il runtime deve impostare XrSpatialPersistenceStateEXT in XrSpatialPersistenceDataEXT di questa entità su XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT .
  • Il runtime deve includere un XrSpatialEntityIdEXT valido per questa entità nello snapshot creato.
  • Il runtime deve impostare XrSpatialEntityTrackingStateEXT di quell'entità su XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT se sta monitorando attivamente l'entità e dispone di dati validi per i suoi componenti. In caso contrario, il runtime deve impostare XrSpatialEntityTrackingStateEXT su XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT .

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_EXT_SPATIAL_PERSISTENCE_EXTENSION_NAME
  • XR_EXT_spatial_persistence_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_PERSISTENCE_CONTEXT_EXT

  • Estensione di XrResult :

    • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT

  • Estensione di XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

  • Estensione di XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT
    • XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT

Esempio di codice

Crea contesto di persistenza

// Check if the required persistence scope supported
uint32_t scopeCount;
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, 0, &scopeCount, nullptr));
std::vector<XrSpatialPersistenceScopeEXT> persistenceScopes(scopeCount);
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, scopeCount, &scopeCount, persistenceScopes.data()));

if (std::find(persistenceScopes.begin(), persistenceScopes.end(), XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT) == persistenceScopes.end()) {
  return;
}

XrSpatialPersistenceContextEXT persistenceContext{};

XrSpatialPersistenceContextCreateInfoEXT persistenceContextCreateInfo{XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT};
persistenceContextCreateInfo.scope = XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT;
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialPersistenceContextAsyncEXT(session, &persistenceContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialPersistenceContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialPersistenceContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS || completion.createResult != XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT) {
  return;
}

persistenceContext = completion.persistenceContext;

// ...
// Connect persistence context to a spatial context and discover persisted entities.
// ...

CHK_XR(xrDestroySpatialPersistenceContextEXT(persistenceContext));

Collega il contesto di persistenza a un contesto spaziale

// Note: Anchor capability is just used as an example here. Persistence can be
// supported by other capabilities too. xrEnumerateSpatialCapabilityComponentTypesEXT() can
// be used to check if a certain capability supports persistence.
if (!isSpatialCapabilitySupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT)) {
  return;
}

const bool supportsPersistenceComponent = isSpatialComponentSupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  if (supportsPersistenceComponent) {
    enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);
  }

  XrSpatialCapabilityConfigurationAnchorEXT anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrSpatialContextPersistenceConfigEXT persistenceConfig{XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT};
  persistenceConfig.persistenceContextCount = 1;
  persistenceConfig.persistenceContexts = &persistenceContext;

  if (supportsPersistenceComponent) {
    spatialContextCreateInfo.next = &persistenceConfig;
  }

  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

// ...
// Discover persisted anchors.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Scopri tutte le entità persistenti

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      // persistenceData[i].persistUuid is the UUID of the persisted entity whose entity ID is entityIds[i].
      // The persistenceData array is essentially the uuids persisted in the scope that the current
      // XrSpatialPersistenceContextEXT is configured with.
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

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

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

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

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

Scopri le entità con UUID specifici

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// Load up the uuids that the app has stored on its own i.e. the uuids it is interested in.
std::vector<XrUuid> uuidsStoredByApp = loadPersistedUuids();

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoveryPersistenceUuidFilterEXT persistenceFilter{XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT};
  persistenceFilter.persistedUuidCount = uuidsStoredByApp.size();
  persistenceFilter.persistedUuids = uuidsStoredByApp.data();

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  snapshotCreateInfo.next = &persistenceFilter;

  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is present in the persistence scope
        // and its corresponding entity ID and state are entityIds[i] & entityStates[i] respectively.
      } else if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is NOT present in the persistence scope
        // and its corresponding entity ID (entityIds[i]) would be XR_NULL_SPATIAL_ENTITY_ID_EXT
        // and tracking state (entityStates[i]) would be XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

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

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

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

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

Problemi

Cronologia delle versioni

  • Revisione 1, 29/08/2024 (Nihav Jain, Google)

    • Descrizione iniziale dell'estensione