**Name String**

`XR_ANDROID_composition_layer_passthrough_mesh`

**Extension Type**

Instance extension

**Registered Extension Number**

463

**Revision**

1

**Extension and Version Dependencies**

[OpenXR 1.0](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#versions-1.0)

**Last Modified Date**

2024-09-18

**IP Status**

No known IP claims.

**Contributors**

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

## Overview

For devices that support multiple environment blend modes, the system may provide passthrough configurations to show a user their physical environment from an immersive view.

This extension enables applications to project passthrough textures onto arbitrary geometry through an additional composition layer[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID).

The passthrough layer characteristics are specified by the following parameters, in which the projection is represented by[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID).  

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

For full screen passthrough, applications**can** use[Environment Blend Mode](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#rendering-environment-blend-mode).

## Inspect system capability

An application**can** inspect whether the system is capable of composition layer passthrough mesh by chaining an[XrSystemPassthroughLayerPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)structure to the[XrSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSystemProperties)when calling[xrGetSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrGetSystemProperties).  

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

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `supportsPassthroughLayer`is an[`XrBool32`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrBool32), indicating if the current system supports composition layer passthrough mesh.
- `maxMeshIndexCount`is a`uint32_t`returns the maximum count of indices that will be accepted for a passthrough mesh.
- `maxMeshVertexCount`is a`uint32_t`returns the maximum count of vertices that will be accepted for a passthrough mesh.

If`supportsPassthroughLayer`returns`XR_FALSE`, the system does not support composition layer passthrough mesh, and therefore will receive`XR_ERROR_FEATURE_UNSUPPORTED`from[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID). The application**should** avoid using composition layer passthrough mesh when`supportsPassthroughLayer`is`XR_FALSE`.

If`supportsPassthroughLayer`returns`XR_TRUE`, the system supports composition layer passthrough mesh. In this case,`maxMeshIndexCount`and`maxMeshVertexCount`will return a non-zero number. An application**should** use`maxMeshIndexCount`and`maxMeshVertexCount`as the maximum values to set passthrough meshes when calling[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID)and[xrSetPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrSetPassthroughLayerMeshANDROID), otherwise`XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID`may be returned to indicate the mesh data exceeds the supported limit.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to using[XrSystemPassthroughLayerPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)
- `type`**must** be`XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)

## Passthrough Layer Composition

The[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID)contains the information needed to render a passthrough texture onto a triangle mesh when calling[xrEndFrame](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrEndFrame).[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID)is an alias type for the base struct[XrCompositionLayerBaseHeader](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrCompositionLayerBaseHeader)used in[XrFrameEndInfo](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrFrameEndInfo).  

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

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `layerFlags`is a bitmask of[XrCompositionLayerFlags](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrCompositionLayerFlags)describing flags to apply to the layer.
- `space`is the[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)in which the`pose`of the layer mesh is evaluated over time.
- `pose`is an`XrPosef`defining the position and orientation of the layer mesh in the reference frame of the`space`.
- `scale`is an`XrVector3f`defining the scale of the layer mesh.
- `opacity`is a`float`defining the opacity of the passthrough texture in range \[0, 1\].
- `layer`is the[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)previously created by[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID).

The application**can** create an[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID)structure with the created`layer`and the corresponding meshes provided by[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID).

A pointer to[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID)**may** be submitted in[xrEndFrame](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrEndFrame)as a pointer to the base structure[XrCompositionLayerBaseHeader](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrCompositionLayerBaseHeader), in the chosen layer order, to request the runtime to composite a passthrough layer into the final frame output.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to using[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID)
- `type`**must** be`XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `layerFlags`**must** be`0`or a valid combination of[XrCompositionLayerFlagBits](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrCompositionLayerFlagBits)values
- `space`**must** be a valid[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)handle
- `layer`**must** be a valid[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle
- Both of`layer`and`space`**must** have been created, allocated, or retrieved from the same[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)

## Create a passthrough layer handle

The[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle represents a passthrough layer which defines the behavior of[XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID).  

    XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

An application**can** create an[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle by calling[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID). The returned[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle**can**be subsequently used in API calls.  

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

Parameter Descriptions

- `session`is an[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)in which the passthrough layer will be created for.
- `createInfo`is a pointer to an[XrPassthroughLayerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)structure specifying initial passthrough layer parameters. This field**can** also be chained to an[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)structure to set the mesh at the same time.
- `layer`is a pointer to a handle in which the created[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)is returned.

The application**should** specify the number of passthrough mesh indices in the[XrPassthroughLayerCreateInfoANDROID::vertexCapacity](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)and[XrPassthroughLayerCreateInfoANDROID::indexCapacity](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)less than or equal to the maximum values returned by[XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)and[XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)when calling[xrGetSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrGetSystemProperties).[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID)will return a`XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID`error if the count of mesh indices defined by`createInfo`is greater than the maximum values.

The[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle**must** be eventually freed using the`xrDestroyPassthroughLayerANDROID`function.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to calling[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID)
- `session`**must** be a valid[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle
- `createInfo`**must** be a pointer to a valid[XrPassthroughLayerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)structure
- `layer`**must** be a pointer to an[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `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`

The[XrPassthroughLayerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)structure is defined as:  

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

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is NULL or a pointer to the next structure in a structure chain.[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)**can** be provided in the next chain to specify an initial mesh for the passthrough layer when calling[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID).
- `vertexCapacity`is an`uint32_t`representing the**maximum** capacity of the vertex buffer for this layer's mesh, or`0`if unspecified. If specified, the[XrPassthroughLayerMeshANDROID::vertexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)of any mesh set for this layer**must** be less than or equal to the`vertexCapacity`.
- `indexCapacity`is an`uint32_t`representing the**maximum** capacity of the index buffer for this layer's mesh, or`0`if unspecified. If specified, the[XrPassthroughLayerMeshANDROID::indexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)of any mesh set for this layer**must** be less than or equal to the`indexCapacity`.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to using[XrPassthroughLayerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)
- `type`**must** be`XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains). See also:[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)

An application**can** use`xrDestroyPassthroughLayerANDROID`function to release the passthrough layer and the underlying resources.  

    XrResult xrDestroyPassthroughLayerANDROID(
        XrPassthroughLayerANDROID                   layer);

### Parameter Descriptions

- `layer`is the[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)to be destroyed.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to calling`xrDestroyPassthroughLayerANDROID`
- `layer`**must** be a valid[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle

### Thread Safety

- Access to`layer`, and any child handles,**must**be externally synchronized

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_RUNTIME_FAILURE`
- `XR_ERROR_HANDLE_INVALID`

## Set passthrough layer mesh

An application**can** use[xrSetPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrSetPassthroughLayerMeshANDROID)function to set the mesh for a passthrough layer.  

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

### Parameter Descriptions

- `layer`is an[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle in which to update with the given`mesh`.
  - `mesh`is a pointer to an[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)structure specifying the information of the mesh.

The application**should** specify the number of passthrough mesh indices in the[XrPassthroughLayerMeshANDROID::vertexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)and[XrPassthroughLayerMeshANDROID::indexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)less than or equal to the maximum values returned by[XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)and[XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)when calling[xrGetSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrGetSystemProperties). If the count of mesh indices given by`mesh`from[xrSetPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrSetPassthroughLayerMeshANDROID)is greater than the maximum values, then`XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID`will be returned.

If the mesh buffer capacity is specified by the[XrPassthroughLayerCreateInfoANDROID::vertexCapacity](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)and[XrPassthroughLayerCreateInfoANDROID::indexCapacity](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)when creating the`layer`using[xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID), then the`XR_ERROR_SIZE_INSUFFICIENT`error will be returned on[xrSetPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrSetPassthroughLayerMeshANDROID)if the count of mesh indices defined by`mesh`is greater than the capacity.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to calling[xrSetPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrSetPassthroughLayerMeshANDROID)
- `layer`**must** be a valid[XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)handle
- `mesh`**must** be a pointer to a valid[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)structure

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `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`

The[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)structure is defined as:  

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

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain.
- `windingOrder`is the[XrWindingOrderANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrWindingOrderANDROID)of the mesh triangles, which will be used for backface culling when rendering the mesh.
- `vertexCount`is an`uint32_t`representing the number of vertices in the mesh. When[XrPassthroughLayerCreateInfoANDROID::vertexCapacity](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)is specified, the`vertexCount`**must** be less than or equal to the`vertexCapacity`.
  - `vertices`is a pointer to an array of`XrVector3f`which contains the vertex positions of the triangle mesh.
- `indexCount`is an`uint32_t`representing the number of indices in the triangle mesh. The last`indexCount % 3`indices, if any, won't be drawn. When[XrPassthroughLayerCreateInfoANDROID::indexCapacity](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)is specified, the`indexCount`**must** be less than or equal to the`indexCapacity`.
- `indices`is a pointer to an array of`uint16_t`which contains the indices of the triangle mesh.

### Valid Usage (Implicit)

- The[`XR_ANDROID_composition_layer_passthrough_mesh`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XR_ANDROID_composition_layer_passthrough_mesh)extension**must** be enabled prior to using[XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)
- `type`**must** be`XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `windingOrder`**must** be a valid[XrWindingOrderANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrWindingOrderANDROID)value
- If`vertexCount`is not`0, vertices`**must** be a pointer to an array of`vertexCount`[XrVector3f](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrVector3f)structures
- If`indexCount`is not`0, indices`**must** be a pointer to an array of`indexCount uint16_t`values

The[XrWindingOrderANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrWindingOrderANDROID)enumeration identifies the winding order of a mesh's triangles, used by the runtime for backface culling when rendering the mesh of the passthrough layer.  

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

### Enumerant Descriptions

- `XR_WINDING_ORDER_UNKNOWN_ANDROID`--- Winding order of the mesh's triangles is not known.
- `XR_WINDING_ORDER_CW_ANDROID`--- Winding order of the mesh's triangles is clockwise.
- `XR_WINDING_ORDER_CCW_ANDROID`--- Winding order of the mesh's triangles is counter-clockwise.

## Example code for passthrough layer composition

The following example code demonstrates how to create a passthrough layer and use it in compositing.  

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

**New Object Types**

- [XrPassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerANDROID)

**New Enum Constants**

[XrObjectType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrObjectType)enumeration is extended with:

- `XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID`

[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)enumeration is extended with:

- `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`

[XrResult](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrResult)enumeration is extended with:

- `XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID`

**New Enums**

- [XrWindingOrderANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrWindingOrderANDROID)

**New Structures**

- [XrPassthroughLayerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerCreateInfoANDROID)
- [XrPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrPassthroughLayerMeshANDROID)
- [XrCompositionLayerPassthroughANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrCompositionLayerPassthroughANDROID)
- [XrSystemPassthroughLayerPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#XrSystemPassthroughLayerPropertiesANDROID)

**New Functions**

- [xrCreatePassthroughLayerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrCreatePassthroughLayerANDROID)
- `xrDestroyPassthroughLayerANDROID`
- [xrSetPassthroughLayerMeshANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_composition_layer_passthrough_mesh#xrSetPassthroughLayerMeshANDROID)

**Issues**

**Version History**

- Revision 1, 2024-09-11 (Levana Chen)
  - Initial extension description

*** ** * ** ***

OpenXR™ and the OpenXR logo are trademarks owned by The Khronos Group Inc. and are registered as a trademark in China, the European Union, Japan and the United Kingdom.