Extensión OpenXR XR_ANDROID_device_anchor_persistence

Cadena de nombre

XR_ANDROID_device_anchor_persistence

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

458

Revisión

1

Dependencias de extensiones y versiones

XR_EXT_uuid y XR_ANDROID_trackables

Fecha de la última modificación

2024-10-10

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Nihav Jain, Google

Levana Chen, Google

Spencer Quin, Google

Kenny Vercaemer, Google

Descripción general

Esta extensión permite que la aplicación conserve, recupere y cancele las anclas en el dispositivo actual para el usuario actual, en todas las aplicaciones y sesiones del dispositivo.

Cómo inspeccionar la capacidad del sistema

La estructura XrSystemDeviceAnchorPersistencePropertiesANDROID se define de la siguiente manera:

typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportsAnchorPersistence es un XrBool32 que indica si el sistema actual admite la persistencia de anclas para anclas espaciales.

Una aplicación puede inspeccionar si el sistema es capaz de conservar las anclas espaciales (consulta xrCreateAnchorSpaceANDROID) extendiendo XrSystemProperties con la estructura XrSystemDeviceAnchorPersistencePropertiesANDROID cuando se llama a xrGetSystemProperties. Para los anclas rastreables compatibles, una aplicación puede usar xrEnumerateSupportedPersistenceAnchorTypesANDROID para consultar los tipos compatibles.

Si se muestra XR_FALSE para supportsAnchorPersistence, se mostrará XR_ERROR_FEATURE_UNSUPPORTED desde las funciones de persistencia de la ancla del dispositivo que operan en una ancla espacial.

Uso válido (implícito)

La función xrEnumerateSupportedPersistenceAnchorTypesANDROID se define de la siguiente manera: 

XrResult xrEnumerateSupportedPersistenceAnchorTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

Descripciones de los parámetros

  • session es la XrSession que crea XrDeviceAnchorPersistenceANDROID.
  • trackableTypeCapacityInput es la capacidad de trackableTypes, o 0 para recuperar la capacidad requerida.
  • trackableTypeCountOutput es un puntero al recuento del array o un puntero a la capacidad requerida en caso de que trackableTypeCapacityInput no sea suficiente.
  • trackableTypes es un puntero a un array de XrTrackableTypeANDROID, pero puede ser NULL si trackableTypeCapacityInput es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño trackableTypes requerido.

La aplicación puede usar xrEnumerateSupportedPersistenceAnchorTypesANDROID para verificar la compatibilidad con la persistencia de anclas en otros elementos rastreables XrTrackableTypeANDROID.

Si no se muestra un XrTrackableTypeANDROID determinado en el array trackableTypes, se mostrará XR_ERROR_FEATURE_UNSUPPORTED desde las funciones de persistencia del ancla del dispositivo que operan en un ancla de ese tipo.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS

Error

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

Crea un control de persistencia de ancla de dispositivo

Un XrDeviceAnchorPersistenceANDROID es un identificador que representa los recursos necesarios para conservar y hacer un seguimiento de los anclas persistentes. 

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

La función xrCreateDeviceAnchorPersistenceANDROID se define de la siguiente manera: 

XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);

Descripciones de los parámetros

Una aplicación puede crear un control XrDeviceAnchorPersistenceANDROID llamando a xrCreateDeviceAnchorPersistenceANDROID. XrDeviceAnchorPersistenceANDROID se puede usar en llamadas posteriores a la API para conservar o anular la conservación de los ejes. El control XrDeviceAnchorPersistenceANDROID debe liberarse con la función xrDestroyDeviceAnchorPersistenceANDROID.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

La estructura XrDeviceAnchorPersistenceCreateInfoANDROID se define de la siguiente manera: 

typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.

La estructura XrDeviceAnchorPersistenceCreateInfoANDROID proporciona opciones de creación para XrDeviceAnchorPersistenceANDROID cuando se pasa a xrCreateDeviceAnchorPersistenceANDROID.

Uso válido (implícito)

La función xrDestroyDeviceAnchorPersistenceANDROID se define de la siguiente manera: 

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Descripciones de los parámetros

La función xrDestroyDeviceAnchorPersistenceANDROID destruye el control de persistencia del ancla del dispositivo.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a handle y a cualquier controlador secundario debe sincronizarse de forma externa.

Códigos de retorno

Correcto

  • XR_SUCCESS

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cómo conservar un ancla

La función xrPersistAnchorANDROID se define de la siguiente manera:

XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);

Descripciones de los parámetros

La aplicación puede solicitar que se conserven las anclas llamando a xrPersistAnchorANDROID. La aplicación no debe suponer que un valor que se muestra como correcto significa que el ancla se conserva de inmediato. La aplicación debe usar xrGetAnchorPersistStateANDROID para verificar el estado de persistencia del ancla con el ancla que se muestra XrUuidEXT. La aplicación puede usar xrUnpersistAnchorANDROID para anular la persistencia del ancla.

  • Se mostrará XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID si no se está haciendo un seguimiento del ancla en el momento de la llamada.
  • Se mostrará XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID si los datos persistedos no están listos.
  • Se mostrará XR_SUCCESS una vez que el ancla se haya puesto en cola para la persistencia.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

La estructura XrPersistedAnchorSpaceInfoANDROID se define de la siguiente manera: 

typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • anchor es un XrSpace de ancla que xrCreateAnchorSpaceANDROID creó anteriormente para que persista.

Uso válido (implícito)

La función xrGetAnchorPersistStateANDROID se define de la siguiente manera: 

XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);

Descripciones de los parámetros

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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_ANCHOR_ID_NOT_FOUND_ANDROID

La enumeración XrAnchorPersistStateANDROID se define de la siguiente manera: 

typedef enum XrAnchorPersistStateANDROID {
    XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID = 0,
    XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID = 1,
    XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID = 2
} XrAnchorPersistStateANDROID;

Enum

Descripción

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

La app no solicitó que se conservara el ancla.

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

Se solicitó que el ancla se mantenga, pero aún no se conserva.

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

El entorno de ejecución persistió correctamente el ancla.

Crea un ancla a partir de datos persistentes

La función xrCreatePersistedAnchorSpaceANDROID se define de la siguiente manera: 

XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);

Descripciones de los parámetros

La aplicación puede crear un ancla XrSpace a partir de una ancla persistente anterior llamando a xrCreatePersistedAnchorSpaceANDROID con el mismo XrUuidEXT. Esta es otra forma de crear anclas como se define en XR_ANDROID_trackables.

  • Se mostrará XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID si no se encuentra el ancla XrUuidEXT.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

La estructura XrPersistedAnchorSpaceCreateInfoANDROID se define de la siguiente manera: 

typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • anchorId es el XrUuidEXT del ancla persistente desde el que se crea un XrSpace de ancla.

La estructura XrPersistedAnchorSpaceCreateInfoANDROID proporciona opciones de creación para el ancla cuando se pasa a xrCreateDeviceAnchorPersistenceANDROID.

Uso válido (implícito)

Cómo enumerar anclas persistentes

La función xrEnumeratePersistedAnchorsANDROID se define de la siguiente manera: 

XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);

Descripciones de los parámetros

  • handle es XrDeviceAnchorPersistenceANDROID.
  • anchorIdsCapacityInput es la capacidad del array anchorIds, o 0 para indicar una solicitud para recuperar la capacidad requerida.
  • anchorIdsCountOutput es un puntero al recuento de anchorIds escrito o un puntero a la capacidad requerida en caso de que anchorIdsCapacityInput sea insuficiente.
  • anchorIds es un puntero a un array de estructuras XrUuidEXT. Puede ser NULL si anchorIdsCapacityInput es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño anchorIds requerido.

La aplicación puede enumerar todas las anclas persistentes actuales llamando a xrEnumeratePersistedAnchorsANDROID. anchorIds retendrá los UUID de los anclajes persistentes hasta la capacidad del array. Si la capacidad es insuficiente, las aplicaciones no tienen garantías sobre qué anclas se muestran.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID
  • 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

Cómo anular la persistencia de un ancla persistente

La función xrUnpersistAnchorANDROID se define de la siguiente manera: 

XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);

Descripciones de los parámetros

La aplicación puede anular la persistencia de un ancla persistente llamando a xrUnpersistAnchorANDROID y pasando el ancla XrUuidEXT del ancla que se anulará.

  • Se mostrará XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID si los datos persistentes no están listos.
  • Se mostrará XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID si no se encuentra el ancla XrUuidEXT.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

Ejemplo de código para la persistencia de anuncios fijos

En el siguiente código de ejemplo, se muestra cómo inspeccionar la capacidad del sistema, conservar, enumerar y anular la persistencia de los anclajes, además de crear un ancla a partir del ancla conservada XrUuidEXT.

XrSession session; // previously initialized
XrSpace anchor; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedPersistenceAnchorTypesANDROID xrEnumerateSupportedPersistenceAnchorTypesANDROID; // previously initialized
PFN_xrCreateDeviceAnchorPersistenceANDROID xrCreateDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrDestroyDeviceAnchorPersistenceANDROID xrDestroyDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrPersistAnchorANDROID xrPersistAnchorANDROID; // previously initialized
PFN_xrGetAnchorPersistStateANDROID xrGetAnchorPersistStateANDROID; // previously initialized
PFN_xrCreatePersistedAnchorSpaceANDROID xrCreatePersistedAnchorSpaceANDROID; // previously initialized
PFN_xrEnumeratePersistedAnchorsANDROID xrEnumeratePersistedAnchorsANDROID; // previously initialized
PFN_xrUnpersistAnchorANDROID xrUnpersistAnchorANDROID; // previously initialized

// Create a device anchor persistence handle
XrDeviceAnchorPersistenceCreateInfoANDROID persistenceHandleCreateInfo;
persistenceHandleCreateInfo.type = XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID;
persistenceHandleCreateInfo.next = nullptr;

XrDeviceAnchorPersistenceANDROID persistenceHandle;
CHK_XR(xrCreateDeviceAnchorPersistenceANDROID(session, &persistenceHandleCreateInfo, &persistenceHandle));

/// Persist an anchor
XrPersistedAnchorSpaceInfo anchorSpaceInfo;
anchorSpaceInfo.type = XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID;
anchorSpaceInfo.next = nullptr;
anchorSpaceInfo.anchor = anchor;

XrUuidEXT anchorId;
do {
  XrResult result = xrPersistAnchorANDROID(
    persistenceHandle, &anchorSpaceInfo, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID ||
         result == XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}


// ... Update loop ...
// Poll for anchor persist state to confirm if it was successfully persisted
XrAnchorPersistStateANDROID persistState;
CHK_XR(xrGetAnchorPersistStateANDROID(persistenceHandle, &anchorId, &persistState));
if (persistState == XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID)  {
  // The anchor was persisted successfully
}

// Enumerate all persisted anchors
uint32_t anchorCountOutput = 0;
std::vector<XrUuidEXT> allAnchors;

CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  nullptr
));
allAnchors.resize(anchorCountOutput, XR_NULL_HANDLE);

// Fetch the actual anchors in an appropriately resized array.
CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  allAnchors.data()
));

// Creating an anchor from a previously persisted anchor using its UUID
XrTime updateTime; // Time used for the current frame's simulation update.
XrUuidEXT anchorId = allAnchors[0];

XrPersistedAnchorSpaceCreateInfo createInfo;
createInfo.type = XR_TYPE_PERSISTED_ANCHOR_CREATE_INFO_ANDROID;
createInfo.next = nullptr;
createInfo.anchorId = anchorId;

XrSpace anchorSpace = XR_NULL_HANDLE;
CHK_XR(xrCreatePersistedAnchorSpaceANDROID(
  persistenceHandle,
  &createInfo,
  &anchorSpace
));

// The anchor was found and retrieved from the local device successfully.
XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
CHK_XR(xrLocateSpace(anchorSpace, appSpace, updateTime, &anchorLocation));
XrPosef pose = anchorLocation.pose;

// Unpersist the anchor
do {
  XrResult result = xrUnpersistAnchorANDROID(persistenceHandle, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}

// Once app is done with all persistence related tasks
CHK_XR(xrDestroySpace(anchorSpace));
CHK_XR(xrDestroyDeviceAnchorPersistenceANDROID(persistenceHandle));

Nuevos tipos de objetos

Nuevas constantes de enum

La enumeración XrObjectType se extiende con lo siguiente:

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

La enumeración XrResult se extiende con lo siguiente:

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_ANCHOR_ALREADY_PERSISTED_ANDROID
  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

La enumeración XrStructureType se extiende con lo siguiente:

  • XR_TYPE_PERSISTED_ANCHOR_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
  • XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID

Enumeraciones nuevas

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

  • Revisión 1, 10/10/2024 (Kenny Vercaemer)
    • Descripción inicial de la extensión

OpenXR™ y el logotipo de OpenXR son marcas comerciales de The Khronos Group Inc. y están registradas como marca comercial en China, la Unión Europea, Japón y el Reino Unido.