XR_EXT_spatial_object_tracking

String de nome

XR_EXT_spatial_object_tracking

Tipo de extensão

Extensão de instância

Número de ramal registrado

745

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_entity

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance
Andy Biar, Unity Technologies
Rebecca Nordhauser, Unity Technologies

Visão geral

Essa extensão se baseia em XR_EXT_spatial_entity e define um recurso espacial para rastrear um conjunto de objetos predefinidos sem exigir um conjunto de dados de entrada do aplicativo.

Suporte ao ambiente de execução

Se o ambiente de execução for compatível com o rastreamento de objetos, ele precisa indicar isso enumerando XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT em xrEnumerateSpatialCapabilitiesEXT .

Configuração

A estrutura XrSpatialCapabilityConfigurationObjectTrackingEXT é definida como:

typedef struct XrSpatialCapabilityConfigurationObjectTrackingEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationObjectTrackingEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• capability é um XrSpatialCapabilityEXT e precisa ser XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT .
• enabledComponentCount é um uint32_t que descreve a contagem de elementos na matriz enabledComponents.
• enabledComponents é um ponteiro para uma matriz de XrSpatialComponentTypeEXT .

Os aplicativos podem ativar o recurso espacial XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT adicionando um ponteiro à estrutura XrSpatialCapabilityConfigurationObjectTrackingEXT em XrSpatialContextCreateInfoEXT :: capabilityConfigs .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se capability não for XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT .

Uso válido (implícito)

• A extensão XR_EXT_spatial_object_tracking precisa ser ativada antes de usar XrSpatialCapabilityConfigurationObjectTrackingEXT.
• type precisa ser XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas . Consulte também: XrSpatialFeatureObjectSemanticLabelSubsetEXT
• capability precisa ser um valor XrSpatialCapabilityEXT válido
• enabledComponents precisa ser um ponteiro para uma matriz de valores enabledComponentCount válidos de XrSpatialComponentTypeEXT
• O parâmetro enabledComponentCount precisa ser maior que 0.

Componentes garantidos

Um ambiente de execução compatível com XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT precisa oferecer suporte aos seguintes componentes espaciais como componentes garantidos das entidades descobertas por esse recurso e precisa enumerá-los em xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
• Pelo menos um tipo de componente que fornece um conjunto de rótulos semânticos para os objetos rastreados. Um recurso de rastreamento de objetos não tem sentido sem um componente de rótulo semântico. Embora essa extensão defina XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT e XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT como possíveis componentes de rótulo semântico para ambientes de execução, outras extensões podem definir novos tipos de componentes para fornecer diferentes classes de rótulos semânticos que descrevem um objeto rastreado. Consulte [ext_spatial_semantic_labels_guidelines] para saber mais sobre os conjuntos de rótulos semânticos e o design dos tipos de componentes. Os ambientes de execução podem não oferecer suporte a XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT ou XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT para o recurso de faixa de objeto, mas precisam oferecer suporte a pelo menos um tipo de componente que forneça um rótulo semântico.

Componente 3D limitado

O componente 3D limitado fornece o centro e as extensões do objeto representado pela entidade em que ele está. Consulte 3D limitado para mais detalhes.

Componentes opcionais

Um ambiente de execução compatível com XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT pode aceitar componentes espaciais além dos listados na seção Componentes garantidos. O aplicativo pode usar xrEnumerateSpatialCapabilityComponentTypesEXT para receber a lista completa de componentes compatíveis com um ambiente de execução e pode configurar os componentes de interesse ao criar o contexto espacial.

Rótulo semântico do objeto

Dados do componente

typedef enum XrSpatialObjectSemanticLabelEXT {
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT = 2,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT = 3,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT = 4,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT = 6,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT = 7,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT = 8,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT = 9,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT = 10,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialObjectSemanticLabelEXT;

A enumeração XrSpatialObjectSemanticLabelEXT descreve um conjunto de rótulos semânticos para objetos.

Para entidades com o rótulo XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT, o eixo +Z do componente Bounded 3D precisa corresponder aproximadamente à superfície normal da tela.

Para entidades com o rótulo XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT, o eixo +Z do componente Bounded 3D precisa corresponder à superfície normal da parede em que a arte foi descoberta.

Para entidades com o rótulo XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT, o eixo +Z do componente Bounded 3D precisa corresponder à superfície normal da tabela.

Para todos os outros rótulos em XrSpatialObjectSemanticLabelEXT , o aplicativo não pode fazer suposições sobre como o XrBoxf :: center :: orientation fornecido pelo componente Bounded 3D na entidade se alinha aos atributos físicos desse objeto.

Os valores de enumeração têm os seguintes significados:

Descrição do tipo enumerado

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT

O ambiente de execução não conseguiu classificar essa entidade.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT

A entidade é um sofá.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT

A entidade é uma cama.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT

A entidade é uma cadeira.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT

A entidade é uma tabela.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT

A entidade é uma lâmpada.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT

A entidade é uma planta.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT

A entidade é uma tela, como um monitor ou uma TV.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT

A entidade é uma arte de parede.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT

A entidade é um gabinete.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentObjectSemanticLabelListEXT é definida como:

typedef struct XrSpatialComponentObjectSemanticLabelListEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            semanticLabelCount;
    XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentObjectSemanticLabelListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
• semanticLabelCount é um uint32_t que descreve a contagem de elementos na matriz semanticLabels.
• semanticLabels é uma matriz de XrSpatialObjectSemanticLabelEXT .

Para consultar o componente de rótulo semântico de objeto das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentObjectSemanticLabelListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentObjectSemanticLabelListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se semanticLabelCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

• A extensão XR_EXT_spatial_object_tracking precisa ser ativada antes de usar XrSpatialComponentObjectSemanticLabelListEXT.
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• semanticLabels precisa ser um ponteiro para uma matriz de valores semanticLabelCount XrSpatialObjectSemanticLabelEXT
• O parâmetro semanticLabelCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next, mas oferece uma configuração opcional para os aplicativos.

A estrutura XrSpatialFeatureObjectSemanticLabelSubsetEXT é definida como:

typedef struct XrSpatialFeatureObjectSemanticLabelSubsetEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  semanticLabelCount;
    const XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialFeatureObjectSemanticLabelSubsetEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• semanticLabelCount é um uint32_t que descreve a contagem de elementos na matriz semanticLabels.
• semanticLabels é uma matriz de XrSpatialObjectSemanticLabelEXT .

Se o ambiente de execução enumerar XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT de xrEnumerateSpatialCapabilityComponentTypesEXT para um determinado recurso, ele precisará também enumerar XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT de xrEnumerateSpatialCapabilityFeaturesEXT para o mesmo recurso. Se um aplicativo ativar XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT ao configurar essa capability, ele poderá encadear XrSpatialFeatureObjectSemanticLabelSubsetEXT à estrutura de configuração correspondente dessa capability para fornecer ao ambiente de execução um subconjunto de rótulos definidos em XrSpatialObjectSemanticLabelEXT . O ambiente de execução pode usar esse subconjunto de rótulos para otimizar os pipelines de rastreamento.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrCreateSpatialContextAsyncEXT se semanticLabels tiver algum rótulo que não esteja definido em XrSpatialObjectSemanticLabelEXT ou se semanticLabels tiver XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT de xrCreateSpatialContextAsyncEXT se o aplicativo fornecer uma lista válida de rótulos em semanticLabels, mas XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT não estiver incluído na matriz enabledComponents de XrSpatialCapabilityConfigurationBaseHeaderEXT :: da estrutura de configuração à qual XrSpatialFeatureObjectSemanticLabelSubsetEXT está encadeado.

Se o aplicativo configurar um recurso com um XrSpatialFeatureObjectSemanticLabelSubsetEXT válido, o ambiente de execução não poderá incluir entidades que tenham rótulos semânticos que não estejam listados em semanticLabels em qualquer snapshot de descoberta criado para o contexto espacial configurado.

Uso válido (implícito)

• A extensão XR_EXT_spatial_object_tracking precisa ser ativada antes de usar XrSpatialFeatureObjectSemanticLabelSubsetEXT.
• type precisa ser XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• semanticLabels precisa ser um ponteiro para uma matriz de valores semanticLabelCount válidos de XrSpatialObjectSemanticLabelEXT
• O parâmetro semanticLabelCount precisa ser maior que 0.

Rótulo semântico do teclado

Dados do componente

typedef enum XrSpatialKeyboardSemanticLabelEXT {
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT = 2,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialKeyboardSemanticLabelEXT;

A enumeração XrSpatialKeyboardSemanticLabelEXT descreve um rótulo semântico para um teclado.

As extensões e a orientação de XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT representadas pelo componente Bounded 3D na mesma entidade são mostradas na imagem a seguir (com xyz = rgb) originadas no centro do objeto.

Figura 30. Orientação do teclado.

Descrição do tipo enumerado

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT

O ambiente de execução não conseguiu classificar essa entidade.

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT

A entidade é um teclado.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentKeyboardSemanticLabelListEXT é definida como:

typedef struct XrSpatialComponentKeyboardSemanticLabelListEXT {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              semanticLabelCount;
    XrSpatialKeyboardSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentKeyboardSemanticLabelListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
• semanticLabelCount é um uint32_t que descreve a contagem de elementos na matriz semanticLabels.
• semanticLabels é uma matriz de XrSpatialKeyboardSemanticLabelEXT .

Para consultar o componente de rótulo semântico do teclado das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentKeyboardSemanticLabelListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentKeyboardSemanticLabelListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se semanticLabelCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

• A extensão XR_EXT_spatial_object_tracking precisa ser ativada antes de usar XrSpatialComponentKeyboardSemanticLabelListEXT.
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• semanticLabels precisa ser um ponteiro para uma matriz de valores semanticLabelCount XrSpatialKeyboardSemanticLabelEXT
• O parâmetro semanticLabelCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Rótulo semântico do mouse

Dados do componente

typedef enum XrSpatialMouseSemanticLabelEXT {
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT = 2,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMouseSemanticLabelEXT;

A enumeração XrSpatialMouseSemanticLabelEXT descreve um rótulo semântico para um mouse.

Descrição do tipo enumerado

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

O ambiente de execução não conseguiu classificar essa entidade.

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT

A entidade é um mouse.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentMouseSemanticLabelListEXT é definida como:

typedef struct XrSpatialComponentMouseSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialMouseSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentMouseSemanticLabelListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
• semanticLabelCount é um uint32_t que descreve a contagem de elementos na matriz semanticLabels.
• semanticLabels é uma matriz de XrSpatialMouseSemanticLabelEXT .

Para consultar o componente de rótulo semântico do mouse das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentMouseSemanticLabelListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentMouseSemanticLabelListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se semanticLabelCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

• A extensão XR_EXT_spatial_object_tracking precisa ser ativada antes de usar XrSpatialComponentMouseSemanticLabelListEXT.
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• semanticLabels precisa ser um ponteiro para uma matriz de valores semanticLabelCount XrSpatialMouseSemanticLabelEXT
• O parâmetro semanticLabelCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Exemplo de código

Configurar o recurso de rastreamento de objetos

O exemplo de código a seguir demonstra como configurar o recurso de rastreamento de objetos ao criar um contexto espacial.

// Check if object tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Enumerate supported components for object tracking capability
XrSpatialCapabilityComponentTypesEXT objectComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));
std::vector<XrSpatialComponentTypeEXT> objectCapabilityComponents(objectComponents.componentTypeCountOutput);
objectComponents.componentTypeCapacityInput = objectCapabilityComponents.size();
objectComponents.componentTypes = objectCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));

// Check if the object & keyboard semantic labels component is supported
const auto supportsComponent = [&objectCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(objectCapabilityComponents.begin(), objectCapabilityComponents.end(), component) != objectCapabilityComponents.end();
};

const bool supportsObjectSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
const bool supportsKeyboardSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);

// Enumerate supported features for object tracking capability
uint32_t featureCount;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> features(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, featureCount, &featureCount, features.data()));

const bool supportsObjectSemanticLabelSubsetFeature = std::find(features.begin(), features.end(), XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT) != features.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the guaranteed components of the object tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
// Optionally enable the supported semantic labels
if (supportsObjectSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
}
if (supportsKeyboardSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

// We only want to track sofa and table.
std::vector<XrSpatialObjectSemanticLabelEXT> objectSemanticLabelSubset = {
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT,
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT
};
XrSpatialFeatureObjectSemanticLabelSubsetEXT subsetFeature{XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT};
subsetFeature.semanticLabelCount = objectSemanticLabelSubset.size();
subsetFeature.semanticLabels = objectSemanticLabelSubset.data();

XrSpatialCapabilityConfigurationObjectTrackingEXT objectTrackingConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT};
objectTrackingConfig.capability = XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT;
objectTrackingConfig.enabledComponentCount = enabledComponents.size();
objectTrackingConfig.enabledComponents = enabledComponents.data();
if (supportsObjectSemanticLabelSubsetFeature) {
  objectTrackingConfig.next = &subsetFeature;
}

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&objectTrackingConfig),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Descobrir entidades espaciais e consultar dados de componentes

O exemplo de código a seguir demonstra como descobrir entidades espaciais para um contexto configurado com XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT e consultar os dados do componente.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
if (supportsKeyboardSemanticLabel) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrBoxf> bounded3D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded3DListEXT bounded3DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT};
    bounded3DList.boundCount = bounded3D.size();
    bounded3DList.bounds = bounded3D.data();
    queryResult.next = &bounded3DList;

    std::vector<XrSpatialKeyboardSemanticLabelEXT> semanticLabels;
    XrSpatialComponentKeyboardSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT};
    if (supportsKeyboardSemanticLabel) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // 3D bounds for entity entityIds[i] is bounded3D[i].extents centered on bounded3D[i].center.

      if (supportsKeyboardSemanticLabel) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

Novas estruturas

• XrSpatialCapabilityConfigurationObjectTrackingEXT

• Estendendo XrSpatialCapabilityConfigurationObjectTrackingEXT :

  • XrSpatialFeatureObjectSemanticLabelSubsetEXT

• Estendendo XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentKeyboardSemanticLabelListEXT
  • XrSpatialComponentMouseSemanticLabelListEXT
  • XrSpatialComponentObjectSemanticLabelListEXT

Novos tipos enumerados

• XrSpatialKeyboardSemanticLabelEXT
• XrSpatialMouseSemanticLabelEXT
• XrSpatialObjectSemanticLabelEXT

Novas constantes de tipo enumerado

• XR_EXT_SPATIAL_OBJECT_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_object_tracking_SPEC_VERSION

• Estendendo XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

• Estendendo XrSpatialCapabilityFeatureEXT :

  • XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

• Estendendo XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

• Estendendo XrStructureType :

  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
  • XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Problemas

Histórico de versões

• Revisão 1, 03/06/2025 (Nihav Jain, Google)

  • Descrição inicial da extensão