Extensión OpenXR XR_ANDROID_composition_layer_passthrough_mesh

Cadena de nombre

XR_ANDROID_composition_layer_passthrough_mesh

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

463

Revisión

1

Dependencias de extensiones y versiones

OpenXR 1.0

Última fecha de modificación

2024-09-18

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Descripción general

En el caso de los dispositivos que admiten varios modos de combinación de entornos, el sistema puede proporcionar configuraciones de transferencia para mostrarle al usuario su entorno físico desde una vista envolvente.

Esta extensión permite que las aplicaciones proyecten texturas de transferencia a una geometría arbitraria a través de una capa de composición adicional XrCompositionLayerPassthroughANDROID.

Las características de la capa de transferencia se especifican con los siguientes parámetros, en los que la proyección está representada por XrPassthroughLayerANDROID.

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

Para la transferencia de pantalla completa, las aplicaciones pueden usar el modo de combinación de entornos.

Cómo inspeccionar la capacidad del sistema

Una aplicación puede inspeccionar si el sistema es capaz de usar una malla de transferencia de capas de composición encadenando una estructura XrSystemPassthroughLayerPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties.

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

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.
• supportsPassthroughLayer es un XrBool32, que indica si el sistema actual admite la malla de transferencia de capas de composición.
• maxMeshIndexCount es un uint32_t que muestra el recuento máximo de índices que se aceptarán para una malla de transferencia.
• maxMeshVertexCount es un uint32_t que muestra la cantidad máxima de vértices que se aceptarán para una malla de transferencia.

Si supportsPassthroughLayer muestra XR_FALSE, el sistema no es compatible con la malla de transferencia de la capa de composición y, por lo tanto, recibirá XR_ERROR_FEATURE_UNSUPPORTED de xrCreatePassthroughLayerANDROID. La aplicación debe evitar usar la malla de transferencia de capas de composición cuando supportsPassthroughLayer sea XR_FALSE.

Si supportsPassthroughLayer muestra XR_TRUE, el sistema admite la malla de transferencia de capas de composición. En este caso, maxMeshIndexCount y maxMeshVertexCount mostrarán un número distinto de cero. Una aplicación debe usar maxMeshIndexCount y maxMeshVertexCount como los valores máximos para establecer mallas de transferencia cuando se llama a xrCreatePassthroughLayerANDROID y xrSetPassthroughLayerMeshANDROID. De lo contrario, se puede mostrar XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID para indicar que los datos de malla superan el límite admitido.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de usar XrSystemPassthroughLayerPropertiesANDROID.
• type debe ser XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID.
• next debe ser NULL o un puntero válido a la próxima estructura en una cadena de estructuras.

Composición de capas de transferencia

XrCompositionLayerPassthroughANDROID contiene la información necesaria para renderizar una textura de transferencia en una malla de triángulos cuando se llama a xrEndFrame. XrCompositionLayerPassthroughANDROID es un tipo de alias para la estructura base XrCompositionLayerBaseHeader que se usa en XrFrameEndInfo.

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

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.
• layerFlags es una máscara binaria de XrCompositionLayerFlags que describe las marcas que se aplicarán a la capa.
• space es el XrSpace en el que se evalúa el pose de la malla de capas con el tiempo.
• pose es un XrPosef que define la posición y la orientación de la malla de la capa en el marco de referencia de space.
• scale es un XrVector3f que define la escala de la malla de la capa.
• opacity es un float que define la opacidad de la textura de transferencia en el rango [0, 1].
• layer es el XrPassthroughLayerANDROID que xrCreatePassthroughLayerANDROID creó anteriormente.

La aplicación puede crear una estructura XrCompositionLayerPassthroughANDROID con el layer creado y las mallas correspondientes que proporciona XrPassthroughLayerMeshANDROID.

Se puede enviar un puntero a XrCompositionLayerPassthroughANDROID en xrEndFrame como un puntero a la estructura base XrCompositionLayerBaseHeader, en el orden de capas elegido, para solicitar que el entorno de ejecución componga una capa de transferencia en la salida de fotogramas final.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de usar XrCompositionLayerPassthroughANDROID.
• type debe ser XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID.
• next debe ser NULL o un puntero válido a la próxima estructura en una cadena de estructuras.
• layerFlags debe ser 0 o una combinación válida de valores de XrCompositionLayerFlagBits.
• space debe ser un identificador de XrSpace válido.
• layer debe ser un controlador XrPassthroughLayerANDROID válido.
• layer y space deben haberse creado, asignado o recuperado desde la misma XrSession.

Crea un controlador de capa de transferencia

El control XrPassthroughLayerANDROID representa una capa de transferencia que define el comportamiento de XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Una aplicación puede crear un control XrPassthroughLayerANDROID llamando a xrCreatePassthroughLayerANDROID. El control XrPassthroughLayerANDROID que se muestra se puede usar posteriormente en llamadas a la API.

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

Descripciones de los parámetros

• session es un XrSession en el que se creará la capa de transferencia.
• createInfo es un puntero a una estructura XrPassthroughLayerCreateInfoANDROID que especifica los parámetros iniciales de la capa de transferencia. Este campo también se puede encadenar a una estructura XrPassthroughLayerMeshANDROID para configurar la malla al mismo tiempo.
• layer es un puntero a un controlador en el que se muestra la XrPassthroughLayerANDROID creada.

La aplicación debe especificar la cantidad de índices de malla de transferencia en XrPassthroughLayerCreateInfoANDROID::vertexCapacity y XrPassthroughLayerCreateInfoANDROID::indexCapacity que sean menores o iguales a los valores máximos que muestran XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount y XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount cuando se llama a xrGetSystemProperties. xrCreatePassthroughLayerANDROID mostrará un error XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID si el recuento de índices de malla que define createInfo es mayor que los valores máximos.

El controlador XrPassthroughLayerANDROID debe liberarse con la función xrDestroyPassthroughLayerANDROID.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de llamar a xrCreatePassthroughLayerANDROID.
• session debe ser un identificador XrSession válido.
• createInfo debe ser un puntero a una estructura XrPassthroughLayerCreateInfoANDROID válida.
• layer debe ser un puntero a un control XrPassthroughLayerANDROID.

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

La estructura XrPassthroughLayerCreateInfoANDROID se define de la siguiente manera:

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

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. XrPassthroughLayerMeshANDROID se puede proporcionar en la siguiente cadena para especificar una malla inicial para la capa de transferencia cuando se llama a xrCreatePassthroughLayerANDROID.
• vertexCapacity es un uint32_t que representa la capacidad máxima del búfer de vértices para la malla de esta capa, o 0 si no se especifica. Si se especifica, XrPassthroughLayerMeshANDROID::vertexCount de cualquier malla establecida para esta capa debe ser menor o igual que vertexCapacity.
• indexCapacity es un uint32_t que representa la capacidad máxima del búfer de índices para la malla de esta capa, o 0 si no se especifica. Si se especifica, el XrPassthroughLayerMeshANDROID::indexCount de cualquier malla establecida para esta capa debe ser menor o igual que indexCapacity.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de usar XrPassthroughLayerCreateInfoANDROID.
• type debe ser XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID.
• next debe ser NULL o un puntero válido a la próxima estructura en una cadena de estructuras. Consulta también: XrPassthroughLayerMeshANDROID

Una aplicación puede usar la función xrDestroyPassthroughLayerANDROID para liberar la capa de transferencia y los recursos subyacentes.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Descripciones de los parámetros

• layer es el XrPassthroughLayerANDROID que se destruirá.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de llamar a xrDestroyPassthroughLayerANDROID.
• layer debe ser un controlador XrPassthroughLayerANDROID válido.

Seguridad de subprocesos

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

Códigos de retorno

Correcto

• XR_SUCCESS

Error

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID

Cómo configurar la malla de la capa de transferencia

Una aplicación puede usar la función xrSetPassthroughLayerMeshANDROID para configurar la malla de una capa de transferencia.

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

Descripciones de los parámetros

• layer es un control XrPassthroughLayerANDROID en el que se debe actualizar con el mesh determinado.
  • mesh es un puntero a una estructura XrPassthroughLayerMeshANDROID que especifica la información de la malla.

La aplicación debe especificar la cantidad de índices de malla de transferencia en XrPassthroughLayerMeshANDROID::vertexCount y XrPassthroughLayerMeshANDROID::indexCount que sean menores o iguales a los valores máximos que muestran XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount y XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount cuando se llama a xrGetSystemProperties. Si el recuento de índices de malla que proporciona mesh de xrSetPassthroughLayerMeshANDROID es mayor que los valores máximos, se mostrará XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID.

Si la capacidad del búfer de malla se especifica con XrPassthroughLayerCreateInfoANDROID::vertexCapacity y XrPassthroughLayerCreateInfoANDROID::indexCapacity cuando se crea layer con xrCreatePassthroughLayerANDROID, se mostrará el error XR_ERROR_SIZE_INSUFFICIENT en xrSetPassthroughLayerMeshANDROID si el recuento de índices de malla definidos por mesh es mayor que la capacidad.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de llamar a xrSetPassthroughLayerMeshANDROID.
• layer debe ser un controlador XrPassthroughLayerANDROID válido.
• mesh debe ser un puntero a una estructura XrPassthroughLayerMeshANDROID válida.

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

La estructura XrPassthroughLayerMeshANDROID se define de la siguiente manera:

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

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.
• windingOrder es el XrWindingOrderANDROID de los triángulos de malla, que se usará para el recorte de caras posteriores cuando se renderice la malla.
• vertexCount es un uint32_t que representa la cantidad de vértices en la malla. Cuando se especifica XrPassthroughLayerCreateInfoANDROID::vertexCapacity, vertexCount debe ser menor o igual que vertexCapacity.
  • vertices es un puntero a un array de XrVector3f que contiene las posiciones de los vértices de la malla de triángulos.
• indexCount es un uint32_t que representa la cantidad de índices en la malla de triángulos. No se dibujarán los últimos indexCount % 3 índices, si los hay. Cuando se especifica XrPassthroughLayerCreateInfoANDROID::indexCapacity, indexCount debe ser menor o igual que indexCapacity.
• indices es un puntero a un array de uint16_t que contiene los índices de la malla de triángulos.

Uso válido (implícito)

• La extensión XR_ANDROID_composition_layer_passthrough_mesh debe estar habilitada antes de usar XrPassthroughLayerMeshANDROID.
• type debe ser XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID.
• next debe ser NULL o un puntero válido a la próxima estructura en una cadena de estructuras.
• windingOrder debe ser un valor válido de XrWindingOrderANDROID.
• Si vertexCount no es 0, vertices, debe ser un puntero a un array de estructuras vertexCount XrVector3f.
• Si indexCount no es 0, indices, debe ser un puntero a un array de valores indexCount uint16_t.

La enumeración XrWindingOrderANDROID identifica el orden de giro de los triángulos de una malla, que el entorno de ejecución usa para el recorte de caras posteriores cuando renderiza la malla de la capa de transferencia.

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

Descripciones de enumeradores

• XR_WINDING_ORDER_UNKNOWN_ANDROID: No se conoce el orden de giro de los triángulos de la malla.
• XR_WINDING_ORDER_CW_ANDROID: El orden de giro de los triángulos de la malla es en el sentido de las manecillas del reloj.
• XR_WINDING_ORDER_CCW_ANDROID: El orden de giro de los triángulos de la malla es en sentido contrario a las manecillas del reloj.

Ejemplo de código para la composición de capas de transferencia

En el siguiente ejemplo de código, se muestra cómo crear una capa de transferencia y usarla en la composición.

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));

Nuevos tipos de objetos

• XrPassthroughLayerANDROID

Nuevas constantes de enum

La enumeración XrObjectType se extiende con lo siguiente:

• XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

La enumeración XrStructureType se extiende con lo siguiente:

• 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

La enumeración XrResult se extiende con lo siguiente:

• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Enumeraciones nuevas

• XrWindingOrderANDROID

Nuevas estructuras

• XrPassthroughLayerCreateInfoANDROID
• XrPassthroughLayerMeshANDROID
• XrCompositionLayerPassthroughANDROID
• XrSystemPassthroughLayerPropertiesANDROID

Funciones nuevas

• xrCreatePassthroughLayerANDROID
• xrDestroyPassthroughLayerANDROID
• xrSetPassthroughLayerMeshANDROID

Problemas

Historial de versiones

• Revisión 1, 11 de septiembre de 2024 (Levana Chen)
  • Descripción inicial de la extensión