Extensão OpenXR XR_ANDROID_composition_layer_passthrough_mesh

String de nome

XR_ANDROID_composition_layer_passthrough_mesh

Tipo de extensão

Extensão de instância

Número de extensão registrado

463

Revisão

1

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2024-09-18

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Visão geral

Para dispositivos com suporte a vários modos de mesclagem de ambiente, o sistema pode oferecer configurações de passagem para mostrar ao usuário o ambiente físico em uma visualização imersiva.

Essa extensão permite que os aplicativos projetem texturas de passagem em geometria arbitrária usando uma camada de composição adicional XrCompositionLayerPassthroughANDROID.

As características da camada de passagem são especificadas pelos parâmetros abaixo, em que a projeção é representada por XrPassthroughLayerANDROID.

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

Para passagem em tela cheia, os aplicativos podem usar o modo de mesclagem do ambiente.

Inspecionar o capability do sistema

Um aplicativo pode inspecionar se o sistema é capaz de criar uma malha de passagem de camadas de composição vinculando uma estrutura XrSystemPassthroughLayerPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties.

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

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.
• supportsPassthroughLayer é um XrBool32, indicando se o sistema atual oferece suporte à malha de transmissão de camada de composição.
• maxMeshIndexCount é um uint32_t que retorna a contagem máxima de índices que serão aceitos para uma malha de passagem.
• maxMeshVertexCount é um uint32_t que retorna a contagem máxima de vértices que será aceita para uma malha de passagem.

Se supportsPassthroughLayer retornar XR_FALSE, o sistema não oferece suporte à malha de transmissão de camada de composição e, portanto, receberá XR_ERROR_FEATURE_UNSUPPORTED de xrCreatePassthroughLayerANDROID. O aplicativo deve evitar usar a malha de transmissão de camada de composição quando supportsPassthroughLayer for XR_FALSE.

Se supportsPassthroughLayer retornar XR_TRUE, o sistema oferecerá suporte à malha de transmissão da camada de composição. Nesse caso, maxMeshIndexCount e maxMeshVertexCount vão retornar um número diferente de zero. Um aplicativo precisa usar maxMeshIndexCount e maxMeshVertexCount como os valores máximos para definir malhas de passagem ao chamar xrCreatePassthroughLayerANDROID e xrSetPassthroughLayerMeshANDROID. Caso contrário, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID poderá ser retornado para indicar que os dados da malha excedem o limite aceito.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de usar XrSystemPassthroughLayerPropertiesANDROID.
• type precisa ser XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.

Composição de camada de passagem

O XrCompositionLayerPassthroughANDROID contém as informações necessárias para renderizar uma textura de passagem em uma malha triangular ao chamar xrEndFrame. XrCompositionLayerPassthroughANDROID é um tipo de alias para a estrutura base XrCompositionLayerBaseHeader usada em XrFrameEndInfo.

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

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.
• layerFlags é uma máscara de bits de XrCompositionLayerFlags que descreve flags a serem aplicadas à camada.
• space é o XrSpace em que o pose da malha de camadas é avaliado ao longo do tempo.
• pose é um XrPosef que define a posição e a orientação da malha da camada no frame de referência do space.
• scale é um XrVector3f que define a escala da malha da camada.
• opacity é um float que define a opacidade da textura de passagem no intervalo [0, 1].
• layer é a XrPassthroughLayerANDROID criada anteriormente por xrCreatePassthroughLayerANDROID.

O aplicativo pode criar uma estrutura XrCompositionLayerPassthroughANDROID com o layer criado e as malhas correspondentes fornecidas por XrPassthroughLayerMeshANDROID.

Um ponteiro para XrCompositionLayerPassthroughANDROID pode ser enviado em xrEndFrame como um ponteiro para a estrutura de base XrCompositionLayerBaseHeader, na ordem de camada escolhida, para solicitar que o ambiente de execução combine uma camada de passagem na saída final do frame.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de usar XrCompositionLayerPassthroughANDROID.
• type precisa ser XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.
• layerFlags precisa ser 0 ou uma combinação válida de valores de XrCompositionLayerFlagBits.
• space precisa ser um identificador XrSpace válido.
• layer precisa ser um identificador XrPassthroughLayerANDROID válido.
• layer e space precisam ter sido criados, alocados ou recuperados da mesma XrSession.

Criar um identificador de camada de passagem

O gerenciador XrPassthroughLayerANDROID representa uma camada de passagem que define o comportamento de XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Um aplicativo pode criar um identificador XrPassthroughLayerANDROID chamando xrCreatePassthroughLayerANDROID. O gerenciador XrPassthroughLayerANDROID retornado pode ser usado posteriormente em chamadas de API.

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

Descrições dos parâmetros

• session é uma XrSession em que a camada de transferência será criada.
• createInfo é um ponteiro para uma estrutura XrPassthroughLayerCreateInfoANDROID que especifica os parâmetros iniciais da camada de passagem. Esse campo pode também ser encadeado a uma estrutura XrPassthroughLayerMeshANDROID para definir a malha ao mesmo tempo.
• layer é um ponteiro para um identificador em que a XrPassthroughLayerANDROID criada é retornada.

O aplicativo precisa especificar o número de índices de mesh de passagem no XrPassthroughLayerCreateInfoANDROID::vertexCapacity e XrPassthroughLayerCreateInfoANDROID::indexCapacity menor ou igual aos valores máximos retornados por XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount e XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount ao chamar xrGetSystemProperties. xrCreatePassthroughLayerANDROID vai retornar um erro XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID se a contagem de índices de mesh definidos por createInfo for maior que os valores máximos.

O gerenciador XrPassthroughLayerANDROID precisa ser liberado usando a função xrDestroyPassthroughLayerANDROID.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de chamar xrCreatePassthroughLayerANDROID.
• session precisa ser um identificador XrSession válido
• createInfo precisa ser um ponteiro para uma estrutura XrPassthroughLayerCreateInfoANDROID válida.
• layer precisa ser um ponteiro para um identificador XrPassthroughLayerANDROID

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_SIZE_INSUFFICIENT
• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

A estrutura XrPassthroughLayerCreateInfoANDROID é definida como:

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

Descrições dos participantes

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. XrPassthroughLayerMeshANDROID pode ser fornecido na próxima cadeia para especificar uma malha inicial para a camada de passagem ao chamar xrCreatePassthroughLayerANDROID.
• vertexCapacity é um uint32_t que representa a capacidade máxima do buffer de vértices da malha dessa camada ou 0, se não especificado. Se especificado, o XrPassthroughLayerMeshANDROID::vertexCount de qualquer malha definida para essa camada precisa ser menor ou igual a vertexCapacity.
• indexCapacity é um uint32_t que representa a capacidade máxima do buffer de índice para a malha dessa camada ou 0, se não especificado. Se especificado, o XrPassthroughLayerMeshANDROID::indexCount de qualquer malha definida para essa camada precisa ser menor ou igual a indexCapacity.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de usar XrPassthroughLayerCreateInfoANDROID.
• type precisa ser XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas. Consulte também: XrPassthroughLayerMeshANDROID

Um aplicativo pode usar a função xrDestroyPassthroughLayerANDROID para liberar a camada de passagem e os recursos subjacentes.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Descrições dos parâmetros

• layer é o XrPassthroughLayerANDROID a ser destruído.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de chamar xrDestroyPassthroughLayerANDROID.
• layer precisa ser um identificador XrPassthroughLayerANDROID válido.

Segurança da linha de execução

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

Códigos de retorno

Sucesso

• XR_SUCCESS

Falha

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID

Definir a malha de camada de passagem

Um aplicativo pode usar a função xrSetPassthroughLayerMeshANDROID para definir a malha de uma camada de passagem.

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

Descrições dos parâmetros

• layer é um gerenciador XrPassthroughLayerANDROID para atualizar com o mesh fornecido.
  • mesh é um ponteiro para uma estrutura XrPassthroughLayerMeshANDROID que especifica as informações da malha.

O aplicativo precisa especificar o número de índices de malha de passagem em XrPassthroughLayerMeshANDROID::vertexCount e XrPassthroughLayerMeshANDROID::indexCount menor ou igual aos valores máximos retornados por XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount e XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount ao chamar xrGetSystemProperties. Se a contagem de índices de malha fornecida por mesh de xrSetPassthroughLayerMeshANDROID for maior que os valores máximos, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID será retornado.

Se a capacidade do buffer de malha for especificada por XrPassthroughLayerCreateInfoANDROID::vertexCapacity e XrPassthroughLayerCreateInfoANDROID::indexCapacity ao criar o layer usando xrCreatePassthroughLayerANDROID, o erro XR_ERROR_SIZE_INSUFFICIENT será retornado em xrSetPassthroughLayerMeshANDROID se a contagem de índices de malha definidos por mesh for maior que a capacidade.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de chamar xrSetPassthroughLayerMeshANDROID.
• layer precisa ser um identificador XrPassthroughLayerANDROID válido.
• mesh precisa ser um ponteiro para uma estrutura XrPassthroughLayerMeshANDROID válida.

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_SIZE_INSUFFICIENT
• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

A estrutura XrPassthroughLayerMeshANDROID é definida como:

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

Descrições dos participantes

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• windingOrder é o XrWindingOrderANDROID dos triângulos da malha, que será usado para eliminação de faces de trás ao renderizar a malha.
• vertexCount é um uint32_t que representa o número de vértices na malha. Quando XrPassthroughLayerCreateInfoANDROID::vertexCapacity é especificado, o vertexCount precisa ser menor ou igual ao vertexCapacity.
  • vertices é um ponteiro para uma matriz de XrVector3f que contém as posições de vértice da malha de triângulos.
• indexCount é um uint32_t que representa o número de índices na malha de triângulos. Os últimos índices indexCount % 3, se houver, não serão exibidos. Quando XrPassthroughLayerCreateInfoANDROID::indexCapacity é especificado, o indexCount precisa ser menor ou igual ao indexCapacity.
• indices é um ponteiro para uma matriz de uint16_t que contém os índices da malha de triângulos.

Uso válido (implícito)

• A extensão XR_ANDROID_composition_layer_passthrough_mesh precisa ser ativada antes de usar XrPassthroughLayerMeshANDROID.
• type precisa ser XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.
• windingOrder precisa ser um valor válido de XrWindingOrderANDROID
• Se vertexCount não for 0, vertices, precisa ser um ponteiro para uma matriz de estruturas vertexCount XrVector3f.
• Se indexCount não for 0, indices, precisa ser um ponteiro para uma matriz de valores indexCount uint16_t

A enumeração XrWindingOrderANDROID identifica a ordem de enrolamento dos triângulos de uma malha, usada pelo ambiente de execução para eliminação de faces de trás ao renderizar a malha da camada de passagem.

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

Descrições de enumerantes

• XR_WINDING_ORDER_UNKNOWN_ANDROID: a ordem de enrolamento dos triângulos da malha não é conhecida.
• XR_WINDING_ORDER_CW_ANDROID: a ordem de enrolamento dos triângulos da malha é no sentido horário.
• XR_WINDING_ORDER_CCW_ANDROID: a ordem de enrolamento dos triângulos da malha é anti-horária.

Exemplo de código para composição de camada de passagem

O exemplo de código abaixo demonstra como criar uma camada de passagem e usá-la na composição.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

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

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

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

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

Novos tipos de objeto

• XrPassthroughLayerANDROID

Novas constantes de tipo enumerado

A enumeração XrObjectType é estendida com:

• XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

A enumeração XrStructureType foi ampliada com:

• XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
• XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
• XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

A enumeração XrResult foi ampliada com:

• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Novos tipos enumerados

• XrWindingOrderANDROID

Novas estruturas

• XrPassthroughLayerCreateInfoANDROID
• XrPassthroughLayerMeshANDROID
• XrCompositionLayerPassthroughANDROID
• XrSystemPassthroughLayerPropertiesANDROID

Novas funções

• xrCreatePassthroughLayerANDROID
• xrDestroyPassthroughLayerANDROID
• xrSetPassthroughLayerMeshANDROID

Problemas

Histórico de versões

• Revisão 1, 11/09/2024 (Levana Chen)
  • Descrição inicial da extensão