XR_ANDROID_spatial_anchor_space
Name String
XR_ANDROID_spatial_anchor_space
Tipo de extensión
Extensión de instancia
Número de extensión registrado
796
Revisión
1
Estado de ratificación
No ratificado
Dependencias de extensiones y versiones
XR_EXT_spatial_anchor
Fecha de la última modificación
2025-09-15
Estado de la IP
No hay reclamos de IP conocidos.
Colaboradores
YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Descripción general
La función xrCreateSpatialAnchorEXT definida en la extensión XR_EXT_spatial_anchor permite que las aplicaciones creen anclajes espaciales con un controlador XrSpatialEntityEXT para representarlo. En cambio, esta extensión crea un ancla espacial que se representa con un controlador XrSpace. Esto es útil en los casos en que la aplicación desea hacer lo siguiente:
- Usa xrLocateSpaces para obtener la ubicación del ancla.
- Ubicar otros espacios en relación con el ancla
- Exporta el ancla con
XR_ANDROID_anchor_sharing_export. - La aplicación colocó anclas y ahora solo le importa la ubicación de las anclas (para adjuntar contenido virtual) y no le importa ningún otro componente de ninguna otra entidad descubierta a través de XrSpatialContextEXT que se usó para crear el ancla, lo que permite que la aplicación destruya el contexto espacial.
Las anclas creadas con esta extensión no se pueden conservar con la extensión XR_ANDROID_device_anchor_persistence, y la aplicación debe usar XR_EXT_spatial_persistence_operations en su lugar. El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrPersistAnchorANDROID si XrPersistedAnchorSpaceInfoANDROID :: anchor se crea con xrCreateSpatialAnchorSpaceANDROID o xrCreateSpatialAnchorSpaceFromIdANDROID .
Crea un XrSpace para un Spatial Anchor
Cómo crear un ancla espacial y un espacio
La función xrCreateSpatialAnchorSpaceANDROID se define de la siguiente manera:
XrResult xrCreateSpatialAnchorSpaceANDROID(
XrSession session,
XrSpatialContextEXT spatialContext,
const XrSpatialAnchorCreateInfoEXT* createInfo,
XrSpatialEntityIdEXT* anchorEntityId,
XrSpace* anchorSpace);
Descripciones de los parámetros
sessiones un controlador para un XrSession creado anteriormente con xrCreateSession.spatialContextes un XrSpatialContextEXT creado anteriormente con xrCreateSpatialContextAsyncEXT .createInfoes un puntero a un XrSpatialAnchorCreateInfoEXT .anchorEntityIdes un puntero a unXrSpatialEntityIdEXT.anchorSpacees un puntero a un XrSpace .
La función xrCreateSpatialAnchorSpaceANDROID crea un ancla que genera un XrSpatialEntityIdEXT y un controlador XrSpace. xrCreateSpatialAnchorSpaceANDROID tiene los mismos requisitos de validación que xrCreateSpatialAnchorEXT .
El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialContextEXT que se pasó a xrCreateSpatialAnchorSpaceANDROID no se configuró con XR_SPATIAL_CAPABILITY_ANCHOR_EXT .
Con respecto a la visibilidad del ancla creada por xrCreateSpatialAnchorSpaceANDROID , se aplica el último párrafo de la especificación xrCreateSpatialAnchorEXT.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_anchor_spacedebe estar habilitada antes de llamar a xrCreateSpatialAnchorSpaceANDROID. -
sessiondebe ser un controlador XrSession válido -
spatialContextdebe ser un controlador XrSpatialContextEXT válido. -
createInfodebe ser un puntero a una estructura XrSpatialAnchorCreateInfoEXT válida -
anchorEntityIddebe ser un puntero a un valorXrSpatialEntityIdEXT -
anchorSpacedebe ser un puntero a un controlador XrSpace. -
spatialContextdebe haberse creado, asignado o recuperado desession
Códigos de retorno
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 un XrSpace a partir de un ancla espacial existente
La función xrCreateSpatialAnchorSpaceFromIdANDROID se define de la siguiente manera:
XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
XrSession session,
XrSpatialContextEXT spatialContext,
const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
XrSpace* anchorSpace);
Descripciones de los parámetros
sessiones un controlador para un XrSession creado anteriormente con xrCreateSession.spatialContextes un XrSpatialContextEXT creado anteriormente con xrCreateSpatialContextAsyncEXT .createInfoes un puntero a un XrSpatialAnchorSpaceFromIdCreateInfoANDROID .anchorSpacees un puntero a un XrSpace .
En situaciones en las que las entidades de anclaje espacial ya existen (p.ej., debido a la persistencia), las aplicaciones pueden crear un XrSpace a partir de estos anclajes espaciales proporcionando sus IDs de entidad espacial.
La función xrCreateSpatialAnchorSpaceFromIdANDROID crea un controlador XrSpace proporcionando un XrSpatialEntityIdEXT en el campo XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.
El entorno de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE si el XrSpatialContextEXT que se pasó a xrCreateSpatialAnchorSpaceFromIdANDROID no se configuró con XR_SPATIAL_CAPABILITY_ANCHOR_EXT .
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_anchor_spacedebe estar habilitada antes de llamar a xrCreateSpatialAnchorSpaceFromIdANDROID. -
sessiondebe ser un controlador XrSession válido -
spatialContextdebe ser un controlador XrSpatialContextEXT válido. -
createInfodebe ser un puntero a una estructura XrSpatialAnchorSpaceFromIdCreateInfoANDROID válida. -
anchorSpacedebe ser un puntero a un controlador XrSpace. -
spatialContextdebe haberse creado, asignado o recuperado desession
Códigos de retorno
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 estructura XrSpatialAnchorSpaceFromIdCreateInfoANDROID se define de la siguiente manera:
typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpatialEntityIdEXT anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;
Descripciones de los miembros
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras.anchorEntityIdes elXrSpatialEntityIdEXTdel ancla espacial existente a partir de la cual se creará el XrSpace .
El entorno de ejecución debe devolver XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT si XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId no es un ID válido para spatialContext .
El entorno de ejecución debe mostrar XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID si XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId no es un ID de entidad válido para un ancla.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_anchor_spacedebe estar habilitada antes de usar XrSpatialAnchorSpaceFromIdCreateInfoANDROID. -
typedebe serXR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras
Ciclo de vida de los anuncios fijos
El elemento superior de un controlador XrSpace es un XrSession . Esto implica que un controlador XrSpace que representa el ancla sigue siendo válido incluso después de que se destruyen xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext o xrCreateSpatialAnchorSpaceANDROID :: spatialContext. Crear un XrSpace para representar un ancla de entidad espacial permite que la aplicación destruya el XrSpatialContextEXT que se configuró con XR_SPATIAL_CAPABILITY_ANCHOR_EXT y, al mismo tiempo, siga obteniendo la pose más reciente del ancla con su XrSpace con xrLocateSpaces, es decir, el entorno de ejecución debe seguir haciendo un seguimiento del ancla hasta que se hayan destruido todos los controladores de XrSpace que la representan.
Ejemplo de código
Crea un ancla espacial como un XrSpace
En el siguiente código de ejemplo, se muestra cómo crear un ancla espacial y devolverla como un 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 un XrSpace a partir del ID de la entidad de anclaje
En el siguiente código de ejemplo, se muestra cómo crear un XrSpace a partir de un ID de entidad de anclaje preexistente.
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));
// ...
Comandos nuevos
Estructuras nuevas
Nuevas constantes de enum
XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAMEXR_ANDROID_spatial_anchor_space_SPEC_VERSIONExtiende XrResult :
XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
Extiende XrStructureType :
XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID
Problemas
Historial de versiones
Revisión 1, 15 de septiembre de 2025 (YuSheng Chang, Kyle Chen)
- Descripción inicial de la extensión.