XR_ANDROID_spatial_anchor_space
Name String
XR_ANDROID_spatial_anchor_space
Tipo di estensione
Estensione dell'istanza
Numero di interno registrato
796
Revisione
1
Stato della ratifica
Non ratificato
Dipendenze di estensioni e versioni
XR_EXT_spatial_anchor
Data ultima modifica
2025-09-15
Stato IP
Nessuna rivendicazione di PI nota.
Collaboratori
YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Panoramica
La funzione xrCreateSpatialAnchorEXT definita nell'estensione XR_EXT_spatial_anchor consente alle applicazioni di creare ancoraggi spaziali con un handle XrSpatialEntityEXT per rappresentarli. Al contrario, questa estensione crea un'ancora spaziale rappresentata da un handle XrSpace. Questo è utile nei casi in cui l'applicazione vuole:
- Utilizza xrLocateSpaces per ottenere la posizione dell'ancoraggio.
- Individuare altri spazi relativi all'ancoraggio.
- Esporta l'ancoraggio utilizzando
XR_ANDROID_anchor_sharing_export. - L'applicazione ha posizionato gli ancoraggi e ora si preoccupa solo della loro posizione (per collegare i contenuti virtuali) e non di altri componenti di altre entità rilevate tramite XrSpatialContextEXT utilizzato per creare l'ancoraggio, consentendo così all'applicazione di distruggere il contesto spaziale.
Le ancora create con questa estensione non possono essere rese persistenti utilizzando l'estensione XR_ANDROID_device_anchor_persistence e l'applicazione deve utilizzare XR_EXT_spatial_persistence_operations . Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrPersistAnchorANDROID se XrPersistedAnchorSpaceInfoANDROID :: anchor viene creato utilizzando xrCreateSpatialAnchorSpaceANDROID o xrCreateSpatialAnchorSpaceFromIdANDROID .
Crea XrSpace per un'ancora spaziale
Crea un'ancora spaziale e uno spazio
La funzione xrCreateSpatialAnchorSpaceANDROID è definita come:
XrResult xrCreateSpatialAnchorSpaceANDROID(
XrSession session,
XrSpatialContextEXT spatialContext,
const XrSpatialAnchorCreateInfoEXT* createInfo,
XrSpatialEntityIdEXT* anchorEntityId,
XrSpace* anchorSpace);
Descrizioni dei parametri
sessionè un handle per un XrSession creato in precedenza con xrCreateSessionspatialContextè un XrSpatialContextEXT creato in precedenza utilizzando xrCreateSpatialContextAsyncEXT .createInfoè un puntatore a un XrSpatialAnchorCreateInfoEXT .anchorEntityIdè un puntatore a unXrSpatialEntityIdEXT.anchorSpaceè un puntatore a un XrSpace .
La funzione xrCreateSpatialAnchorSpaceANDROID crea un'ancora che genera un XrSpatialEntityIdEXT e un handle XrSpace. xrCreateSpatialAnchorSpaceANDROID ha gli stessi requisiti di convalida di xrCreateSpatialAnchorEXT .
Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialContextEXT passato a xrCreateSpatialAnchorSpaceANDROID non è stato configurato con XR_SPATIAL_CAPABILITY_ANCHOR_EXT .
Per quanto riguarda la rilevabilità dell'ancoraggio creato da xrCreateSpatialAnchorSpaceANDROID , si applica l'ultimo paragrafo della specifica xrCreateSpatialAnchorEXT.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_spatial_anchor_spacedeve essere attivata prima di chiamare xrCreateSpatialAnchorSpaceANDROID -
sessiondeve essere un handle XrSession valido -
spatialContextdeve essere un handle XrSpatialContextEXT valido -
createInfodeve essere un puntatore a una struttura XrSpatialAnchorCreateInfoEXT valida -
anchorEntityIddeve essere un puntatore a un valoreXrSpatialEntityIdEXT -
anchorSpacedeve essere un puntatore a un handle XrSpace -
spatialContextdeve essere stato creato, allocato o recuperato dasession
Codici di risposta
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROIDXR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
Crea XrSpace da un'ancora spaziale esistente
La funzione xrCreateSpatialAnchorSpaceFromIdANDROID è definita come:
XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
XrSession session,
XrSpatialContextEXT spatialContext,
const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
XrSpace* anchorSpace);
Descrizioni dei parametri
sessionè un handle per un XrSession creato in precedenza con xrCreateSessionspatialContextè un XrSpatialContextEXT creato in precedenza utilizzando xrCreateSpatialContextAsyncEXT .createInfoè un puntatore a un XrSpatialAnchorSpaceFromIdCreateInfoANDROID .anchorSpaceè un puntatore a un XrSpace .
In scenari in cui le entità di ancoraggio spaziale sono preesistenti (ad es. a causa della persistenza), le applicazioni possono creare un XrSpace da questi ancoraggi spaziali fornendo i relativi ID entità spaziale.
La funzione xrCreateSpatialAnchorSpaceFromIdANDROID crea un handle XrSpace fornendo un XrSpatialEntityIdEXT nel campo XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.
Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialContextEXT passato a xrCreateSpatialAnchorSpaceFromIdANDROID non è stato configurato con XR_SPATIAL_CAPABILITY_ANCHOR_EXT .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_spatial_anchor_spacedeve essere attivata prima di chiamare xrCreateSpatialAnchorSpaceFromIdANDROID -
sessiondeve essere un handle XrSession valido -
spatialContextdeve essere un handle XrSpatialContextEXT valido -
createInfodeve essere un puntatore a una struttura XrSpatialAnchorSpaceFromIdCreateInfoANDROID valida -
anchorSpacedeve essere un puntatore a un handle XrSpace -
spatialContextdeve essere stato creato, allocato o recuperato dasession
Codici di risposta
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROIDXR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXTXR_ERROR_VALIDATION_FAILURE
La struttura XrSpatialAnchorSpaceFromIdCreateInfoANDROID è definita come:
typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpatialEntityIdEXT anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture.anchorEntityIdè ilXrSpatialEntityIdEXTdell'ancoraggio spaziale esistente da cui creare l'XrSpace .
Il runtime deve restituire XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT se XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId non è un ID valido per spatialContext .
Il runtime deve restituire XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID se XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId non è un ID entità valido per un ancoraggio.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_spatial_anchor_spacedeve essere attivata prima di utilizzare XrSpatialAnchorSpaceFromIdCreateInfoANDROID -
typedeve essereXR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture
Ciclo di vita dell'ancoraggio
L'elemento principale di un handle XrSpace è un XrSession . Ciò implica che un handle XrSpace che rappresenta l'ancoraggio rimane valido anche dopo la distruzione di xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext o xrCreateSpatialAnchorSpaceANDROID :: spatialContext. La creazione di un XrSpace per rappresentare un ancoraggio di entità spaziale consente all'applicazione di distruggere l'XrSpatialContextEXT configurato con XR_SPATIAL_CAPABILITY_ANCHOR_EXT, continuando comunque a ottenere la posa più recente dell'ancoraggio utilizzando il relativo XrSpace con xrLocateSpaces, ovvero il runtime deve continuare a monitorare l'ancoraggio finché non vengono distrutti tutti gli handle XrSpace che lo rappresentano.
Esempio di codice
Crea un'ancora spaziale come XrSpace
Il seguente codice di esempio mostra come creare un'ancora spaziale e restituirla come XrSpace .
XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor
// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
.type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
.baseSpace = localSpace,
.time = predictedDisplayTime,
.pose = {{0, 0, 0, 1}, {1, 1, 1}},
};
// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));
// ...
Crea XrSpace dall'ID entità di ancoraggio
Il seguente codice di esempio mostra come creare un XrSpace da un ID entità di ancoraggio preesistente.
XrSpace anchorSpace = XR_NULL_HANDLE;
// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
.type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
.anchorEntityId = spatialAnchorEntityId,
};
// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));
// ...
Nuovi comandi
Nuove strutture
Nuove costanti enum
XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAMEXR_ANDROID_spatial_anchor_space_SPEC_VERSIONEstensione di XrResult :
XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
Estensione di XrStructureType :
XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID
Problemi
Cronologia delle versioni
Revisione 1, 15 settembre 2025 (YuSheng Chang, Kyle Chen)
- Descrizione iniziale dell'estensione.