Extensão OpenXR XR_ANDROID_device_anchor_persistence

String de nome

XR_ANDROID_device_anchor_persistence

Tipo de extensão

Extensão de instância

Número de extensão registrado

458

Revisão

1

Dependências de extensão e versão

XR_EXT_uuid e XR_ANDROID_trackables

Data da última modificação

2024-10-10

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Nihav Jain, Google

Levana Chen, Google

Spencer Quin, Google

Kenny Vercaemer, Google

Visão geral

Essa extensão permite que o aplicativo mantenha, recupere e remova âncoras no dispositivo atual para o usuário atual, em aplicativos e sessões do dispositivo.

Inspecionar o recurso do sistema

A estrutura XrSystemDeviceAnchorPersistencePropertiesANDROID é definida como:

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • supportsAnchorPersistence é um XrBool32 que indica se o sistema atual oferece suporte à persistência de âncoras para âncoras espaciais.

Um aplicativo pode inspecionar se o sistema é capaz de manter âncoras espaciais (consulte xrCreateAnchorSpaceANDROID) estendendo o XrSystemProperties com a estrutura XrSystemDeviceAnchorPersistencePropertiesANDROID ao chamar xrGetSystemProperties. Para os âncoras rastreáveis com suporte, um aplicativo pode usar xrEnumerateSupportedPersistenceAnchorTypesANDROID para consultar os tipos com suporte.

Se XR_FALSE for retornado para supportsAnchorPersistence, XR_ERROR_FEATURE_UNSUPPORTED será retornado das funções de persistência de âncora do dispositivo que operam em uma âncora espacial.

Uso válido (implícito)

A função xrEnumerateSupportedPersistenceAnchorTypesANDROID é definida como: 

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

Descrições dos parâmetros

  • session é a XrSession que cria a XrDeviceAnchorPersistenceANDROID.
  • trackableTypeCapacityInput é a capacidade do trackableTypes ou 0 para recuperar a capacidade necessária.
  • trackableTypeCountOutput é um ponteiro para a contagem da matriz ou um ponteiro para a capacidade necessária caso trackableTypeCapacityInput seja insuficiente.
  • trackableTypes é um ponteiro para uma matriz de XrTrackableTypeANDROID, mas pode ser NULL se trackableTypeCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho trackableTypes necessário.

O aplicativo pode usar xrEnumerateSupportedPersistenceAnchorTypesANDROID para verificar o suporte à persistência de âncoras em outros rastreáveis XrTrackableTypeANDROID.

Se um determinado XrTrackableTypeANDROID não for retornado na matriz trackableTypes, XR_ERROR_FEATURE_UNSUPPORTED será retornado das funções de persistência de âncora do dispositivo que operam em uma âncora desse tipo.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • 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

Criar um identificador de persistência de âncora do dispositivo

Um XrDeviceAnchorPersistenceANDROID é um identificador que representa os recursos necessários para persistir e acompanhar as âncoras persistidas. 

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

A função xrCreateDeviceAnchorPersistenceANDROID é definida como: 

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

Descrições dos parâmetros

Um aplicativo pode criar um handle XrDeviceAnchorPersistenceANDROID chamando xrCreateDeviceAnchorPersistenceANDROID. O XrDeviceAnchorPersistenceANDROID pode ser usado em chamadas de API subsequentes para manter ou remover âncoras. O gerenciador XrDeviceAnchorPersistenceANDROID precisa ser liberado usando a função xrDestroyDeviceAnchorPersistenceANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrDeviceAnchorPersistenceCreateInfoANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.

A estrutura XrDeviceAnchorPersistenceCreateInfoANDROID oferece opções de criação para o XrDeviceAnchorPersistenceANDROID quando transmitido para xrCreateDeviceAnchorPersistenceANDROID.

Uso válido (implícito)

A função xrDestroyDeviceAnchorPersistenceANDROID é definida como: 

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Descrições dos parâmetros

A função xrDestroyDeviceAnchorPersistenceANDROID destrói o identificador de persistência de âncora do dispositivo.

Uso válido (implícito)

Segurança da linha de execução

  • O acesso a handle e a qualquer identificador filho precisa ser sincronizado externamente

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Manter uma âncora

A função xrPersistAnchorANDROID é definida como:

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

Descrições dos parâmetros

O aplicativo pode solicitar que as âncoras sejam mantidas chamando xrPersistAnchorANDROID. O aplicativo não pode presumir que um valor de retorno de sucesso significa que a âncora é mantida imediatamente. O aplicativo precisa usar xrGetAnchorPersistStateANDROID para verificar o estado de persistência da âncora usando a âncora XrUuidEXT retornada. O aplicativo pode usar xrUnpersistAnchorANDROID para remover a âncora.

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID será retornado se o âncor não estiver sendo rastreado no momento da chamada.
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID será retornado se os dados persistidos não estiverem prontos.
  • XR_SUCCESS será retornado quando a âncora for enfileirada para persistência.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrPersistedAnchorSpaceInfoANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • anchor é um XrSpace de âncora criado anteriormente por xrCreateAnchorSpaceANDROID para persistir.

Uso válido (implícito)

A função xrGetAnchorPersistStateANDROID é definida como: 

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

Descrições dos parâmetros

  • handle é a XrDeviceAnchorPersistenceANDROID.
  • anchorId é o XrUuidEXT da âncora.
  • persistState é um ponteiro para um XrAnchorPersistStateANDROID em que o estado da âncora é retornado.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID será retornado se o âncor XrUuidEXT não for encontrado.
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID será retornado se os dados persistidos de anchorId não estiverem prontos.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

O tipo enumerado XrAnchorPersistStateANDROID é definido como: 

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;

Tipo enumerado

Descrição

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

A âncora não foi solicitada para ser mantida pelo app.

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

A âncora foi solicitada para ser mantida, mas ainda não foi.

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

A âncora foi mantida pelo ambiente de execução.

Criar uma âncora com dados persistentes

A função xrCreatePersistedAnchorSpaceANDROID é definida como: 

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

Descrições dos parâmetros

O aplicativo pode criar uma âncora XrSpace de uma âncora persistida anteriormente chamando xrCreatePersistedAnchorSpaceANDROID com o mesmo XrUuidEXT. Essa é outra maneira de criar âncoras, conforme definido em XR_ANDROID_trackables.

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID será retornado se o âncor XrUuidEXT não for encontrado.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrPersistedAnchorSpaceCreateInfoANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • anchorId é o XrUuidEXT da âncora persistente para criar um XrSpace.

A estrutura XrPersistedAnchorSpaceCreateInfoANDROID fornece opções de criação para a âncora quando transmitida para xrCreateDeviceAnchorPersistenceANDROID.

Uso válido (implícito)

Enumerar âncoras persistentes

A função xrEnumeratePersistedAnchorsANDROID é definida como: 

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

Descrições dos parâmetros

  • handle é a XrDeviceAnchorPersistenceANDROID.
  • anchorIdsCapacityInput é a capacidade da matriz anchorIds ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • anchorIdsCountOutput é um ponteiro para a contagem de anchorIds gravada ou um ponteiro para a capacidade necessária caso anchorIdsCapacityInput seja insuficiente.
  • anchorIds é um ponteiro para uma matriz de estruturas XrUuidEXT. Pode ser NULL se anchorIdsCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho anchorIds necessário.

O aplicativo pode enumerar todas as âncoras persistentes atuais chamando xrEnumeratePersistedAnchorsANDROID. anchorIds vai armazenar os UUIDs dos âncoras persistentes até a capacidade da matriz. Se a capacidade for insuficiente, os aplicativos não terão garantias sobre quais âncoras serão retornadas.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

Remover a persistência de uma âncora

A função xrUnpersistAnchorANDROID é definida como: 

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

Descrições dos parâmetros

O aplicativo pode remover a âncora persistente chamando xrUnpersistAnchorANDROID e transmitindo a âncora XrUuidEXT para remover a persistência.

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID será retornado se os dados persistidos não estiverem prontos.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID será retornado se o âncor XrUuidEXT não for encontrado.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

Exemplo de código para a persistência de âncora

O exemplo de código abaixo demonstra como inspecionar o capability do sistema, permitir, enumerar e remover âncoras, além de criar uma âncora a partir da âncora persistente 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));

Novos tipos de objeto

Novas constantes de tipo enumerado

A enumeração XrObjectType é estendida com:

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

A enumeração XrResult foi estendida com:

  • 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

A enumeração XrStructureType é ampliada com:

  • 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

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 1, 10/10/2024 (Kenny Vercaemer)
    • Descrição inicial da extensão

O OpenXR™ e o logotipo do OpenXR são marcas registradas do The Khronos Group Inc. e estão registrados como marca registrada na China, na União Europeia, no Japão e no Reino Unido.