XR_ANDROID_spatial_anchor_space

String de nome

XR_ANDROID_spatial_anchor_space

Tipo de extensão

Extensão de instância

Número de ramal registrado

796

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_anchor

Data da última modificação

2025-09-15

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Visão geral

A função xrCreateSpatialAnchorEXT definida na extensão XR_EXT_spatial_anchor permite que os aplicativos criem âncoras espaciais com um identificador XrSpatialEntityEXT para representá-las. Em contraste, essa extensão cria uma âncora espacial representada por um identificador XrSpace. Isso é útil para casos em que o aplicativo quer:

  • Use xrLocateSpaces para encontrar o local da âncora.
  • Localizar outros espaços em relação à âncora.
  • Exporte a âncora usando XR_ANDROID_anchor_sharing_export .
  • O aplicativo colocou âncoras e agora só se importa com a localização delas (para anexar conteúdo virtual) e não se importa com nenhum outro componente de outras entidades descobertas pelo XrSpatialContextEXT usado para criar a âncora, permitindo que o aplicativo destrua o contexto espacial.

As âncoras criadas com essa extensão não podem ser mantidas usando a extensão XR_ANDROID_device_anchor_persistence, e o aplicativo precisa usar XR_EXT_spatial_persistence_operations . O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrPersistAnchorANDROID se XrPersistedAnchorSpaceInfoANDROID :: anchor for criado usando xrCreateSpatialAnchorSpaceANDROID ou xrCreateSpatialAnchorSpaceFromIdANDROID .

Criar um XrSpace para uma âncora espacial

Criar uma âncora espacial e um espaço

A função xrCreateSpatialAnchorSpaceANDROID é definida como:

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

Descrições dos parâmetros

A função xrCreateSpatialAnchorSpaceANDROID cria uma âncora que gera um XrSpatialEntityIdEXT e um identificador XrSpace. xrCreateSpatialAnchorSpaceANDROID tem os mesmos requisitos de validação que xrCreateSpatialAnchorEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialContextEXT transmitido para xrCreateSpatialAnchorSpaceANDROID não tiver sido configurado com XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

Com relação à facilidade de descoberta da âncora criada por xrCreateSpatialAnchorSpaceANDROID , o último parágrafo da especificação xrCreateSpatialAnchorEXT se aplica.

Uso válido (implícito)

  • A extensão XR_ANDROID_spatial_anchor_space precisa ser ativada antes de chamar xrCreateSpatialAnchorSpaceANDROID.
  • session precisa ser um identificador XrSession válido
  • spatialContext precisa ser um identificador XrSpatialContextEXT válido
  • createInfo precisa ser um ponteiro para uma estrutura XrSpatialAnchorCreateInfoEXT válida.
  • anchorEntityId precisa ser um ponteiro para um valor XrSpatialEntityIdEXT
  • anchorSpace precisa ser um ponteiro para um identificador XrSpace.
  • spatialContext precisa ter sido criado, alocado ou recuperado de session

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Criar XrSpace com base em uma âncora espacial atual

A função xrCreateSpatialAnchorSpaceFromIdANDROID é definida como:

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

Descrições dos parâmetros

Em cenários em que as entidades de âncora espacial já existem (por exemplo, devido à persistência), os aplicativos podem criar um XrSpace com base nessas âncoras espaciais, fornecendo os IDs de entidade espacial.

A função xrCreateSpatialAnchorSpaceFromIdANDROID cria um identificador XrSpace fornecendo um XrSpatialEntityIdEXT no campo XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialContextEXT transmitido para xrCreateSpatialAnchorSpaceFromIdANDROID não tiver sido configurado com XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSpatialAnchorSpaceFromIdCreateInfoANDROID é definida como:

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • anchorEntityId é o XrSpatialEntityIdEXT da âncora espacial atual de onde o XrSpace será criado.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT se XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId não for um ID válido para spatialContext .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID se XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId não for um ID de entidade válido para uma âncora.

Uso válido (implícito)

Ciclo de vida da âncora

O pai de um identificador XrSpace é uma XrSession . Isso significa que um identificador XrSpace que representa a âncora permanece válido mesmo depois que xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext ou xrCreateSpatialAnchorSpaceANDROID :: spatialContext são destruídos. Criar um XrSpace para representar uma âncora de entidade espacial permite que o aplicativo destrua o XrSpatialContextEXT que foi configurado com XR_SPATIAL_CAPABILITY_ANCHOR_EXT, mas continue recebendo a pose mais recente da âncora usando o XrSpace com xrLocateSpaces. Ou seja, o ambiente de execução precisa continuar rastreando a âncora até que todos os identificadores XrSpace que a representam sejam destruídos.

Exemplo de código

Criar uma âncora espacial como um XrSpace

O exemplo de código a seguir demonstra como criar uma âncora espacial e retorná-la como um 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));

// ...

Criar XrSpace com base no ID da entidade de âncora

O exemplo de código a seguir demonstra como criar um XrSpace usando um ID de entidade de âncora 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));

// ...

Novos comandos

Novas estruturas

Novas constantes de tipo enumerado

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • Estendendo XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • Estendendo XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 15/09/2025 (YuSheng Chang, Kyle Chen)

    • Descrição inicial da extensão.