Class OpenXRCustomLayerHandler<T>

Provides a base implementation for the OpenXRLayerProvider.ILayerHandler interface. You can implement the required methods of this abstract class to create a concrete layer handler.

Inheritance

object

OpenXRCustomLayerHandler<T>

Implements

OpenXRLayerProvider.ILayerHandler

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: UnityEngine.XR.OpenXR.CompositionLayers

Assembly: Unity.XR.OpenXR.dll

Syntax

public abstract class OpenXRCustomLayerHandler<T> : OpenXRLayerProvider.ILayerHandler, IDisposable where T : struct

Type Parameters

Name	Description
T	The native OpenXR structure of the composition layer to handle.

Remarks

The OpenXRLayerProvider.ILayerHandler methods that this class implements handle adding and removing composition layers from native arrays, swap chain creation dispatching and other tasks required by the Unity side of the API.

The abstract methods that you must implement handle the custom aspects of your layer. These methods include:

• CreateSwapchain(LayerInfo, out SwapchainCreateInfo)
• CreateNativeLayer(LayerInfo, SwapchainCreatedOutput, out T)
• ModifyNativeLayer(LayerInfo, ref T)

You are not required to implement a custom layer handler based on this abstract class, but doing so should be easier than implementing the OpenXRLayerProvider.ILayerHandler interface in its entirety.

You must register your concrete layer handler object with RegisterLayerHandler(Type, ILayerHandler).

Constructors

OpenXRCustomLayerHandler()

Initializes and returns an instance of this OpenXRCustomLayerHandler<T> while also setting the singleton instance member.

Declaration

protected OpenXRCustomLayerHandler()

Fields

Instance

Singleton instance of this specific handler.

Declaration

protected static OpenXRCustomLayerHandler<T> Instance

Field Value

Type	Description
OpenXRCustomLayerHandler<T>

actionsForMainThread

Thread safe queue used to dispatch callbacks that may come from other threads such as the swapchain creation on the graphics thread.

Declaration

protected ConcurrentQueue<Action> actionsForMainThread

Field Value

Type	Description
ConcurrentQueue<Action>

m_nativeLayers

Mapping of unique ids and native layer structs to help determine what layers are currently set to be active.

Declaration

protected Dictionary<int, T> m_nativeLayers

Field Value

Type	Description
Dictionary<int, T>

Methods

ActiveNativeLayer(LayerInfo, ref T)

Override this method to modify a native composition layer struct in response to when it is active. An active composition layer will invoke this every frame.

Declaration

protected virtual bool ActiveNativeLayer(CompositionLayerManager.LayerInfo layerInfo, ref T nativeLayer)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that is active.
T	nativeLayer	A reference to the native OpenXR structure of the composition layer that is active.

Returns

Type	Description
bool	Bool indicating success or failure. A failure case will result in the native composition layer struct not being added into the final XrFrameEndInfo struct.

CreateLayer(LayerInfo)

Implements the OpenXRLayerProvider.ILayerHandler method that is called by the OpenXRLayerProvider when a new layer has been created. This implementation triggers the creation of a swapchain before the actual native layer struct is created.

Declaration

public void CreateLayer(CompositionLayerManager.LayerInfo layerInfo)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer being created.

CreateNativeLayer(LayerInfo, SwapchainCreatedOutput, out T)

Override this method to create the native composition layer struct of type T that is passed to OpenXR. A swapchain info struct is provided so your layer handler has access to any needed swapchain information.

Declaration

protected abstract bool CreateNativeLayer(CompositionLayerManager.LayerInfo layerInfo, OpenXRCustomLayerHandler<T>.SwapchainCreatedOutput swapchainOutput, out T nativeLayer)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that was just created.
OpenXRCustomLayerHandler<T>.SwapchainCreatedOutput	swapchainOutput	Information regarding the swapchain that was created for this layer, such as the associated swapchain handle.
T	nativeLayer	An object of type T that is created and initialized by the concrete implementation of this method.

Returns

Type	Description
bool	A bool indicating success or failure.

Remarks

To add extensions when constructing the XrSwapchainCreateInfo struct, initialize the Next pointer with GetExtensionsChain(LayerInfo, ExtensionTarget).

If your struct needs any XrSpace relative info you can use GetCurrentAppSpace() to get the current app space.

Examples

Constructs an XrCompositionLayerQuad struct with some members using component data.

protected override bool CreateNativeLayer(CompositionLayerManager.LayerInfo layerInfo, SwapchainCreatedOutput swapchainOutput, out XrCompositionLayerQuad nativeLayer)
{
    var texturesExtension = layerInfo.Layer.GetComponent<TexturesExtension>();
    var transform = layerInfo.Layer.GetComponent<Transform>();

    unsafe
    {
        var data = layerInfo.Layer.LayerData as QuadLayerData;

        nativeLayer = new XrCompositionLayerQuad()
        {
            Type = 36,
            Next = OpenXRLayerUtility.GetExtensionsChain(layerInfo, CompositionLayerExtension.ExtensionTarget.Layer),
            LayerFlags = 0x00000002,
            Space = OpenXRLayerUtility.GetCurrentAppSpace(),
            EyeVisibility = 0,
            SubImage = new SwapchainSubImage()
            {
                Swapchain = swapchainOutput.handle,
                ImageRect = new XrRect2Di()
                {
                    offset = new XrOffset2Di() { x = 0, y = 0 },
                    extent = new XrExtent2Di()
                    {
                        width = texturesExtension.LeftTexture.width,
                        height = texturesExtension.LeftTexture.height
                    }
                },
                ImageArrayIndex = 0
            },
            Pose = new XrPosef(transform.position, transform.rotation),
            Size = new XrExtend2Df()
            {
                width = data.GetScaledSize(transform.lossyScale).x,
                height = data.GetScaledSize(transform.lossyScale).y
            }
        };
    }
    return true;
}

CreateSwapchain(LayerInfo, out SwapchainCreateInfo)

Override this method to create the XrSwapchainCreateInfo struct that is passed to OpenXR to create a swapchain.

Declaration

protected abstract bool CreateSwapchain(CompositionLayerManager.LayerInfo layerInfo, out OpenXRCustomLayerHandler<T>.SwapchainCreateInfo swapchainCreateInfo)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that was just created.
OpenXRCustomLayerHandler<T>.SwapchainCreateInfo	swapchainCreateInfo	An XrSwapchainCreateInfo object created and initialized by the concrete implementation of this method.

Returns

Type	Description
bool	A bool indicating success or failure.

Remarks

To add extensions when constructing the XrSwapchainCreateInfo struct, initialize the Next pointer with GetExtensionsChain(LayerInfo, ExtensionTarget).

Examples

Constructs an XrSwapchainCreateInfo struct with some members using component data.

protected override bool CreateSwapchain(CompositionLayerManager.LayerInfo layerInfo, out SwapchainCreateInfo swapchainCreateInfo)
{
   var texturesExtension = layerInfo.Layer.GetComponent<TexturesExtension>();
   unsafe
   {
       swapchainCreateInfo = new XrSwapchainCreateInfo()
       {
            Type = (uint)XrStructureType.XR_TYPE_SWAPCHAIN_CREATE_INFO,
            Next = OpenXRLayerUtility.GetExtensionsChain(layerInfo, CompositionLayerExtension.ExtensionTarget.Swapchain),
            CreateFlags = 0,
            UsageFlags = (ulong)(XrSwapchainUsageFlags.XR_SWAPCHAIN_USAGE_SAMPLED_BIT | XrSwapchainUsageFlags.XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT),
            Format = OpenXRLayerUtility.GetDefaultColorFormat(),
            SampleCount = 1,
            Width = (uint)texturesExtension.LeftTexture.width,
            Height = (uint)texturesExtension.LeftTexture.height,
            FaceCount = 1,
            ArraySize = 1,
            MipCount = (uint)texturesExtension.LeftTexture.mipmapCount,
        };
    }
    return true;
}

CreateSwapchainAsync(LayerInfo)

Calls CreateSwapchain(LayerInfo, out SwapchainCreateInfo) to create a OpenXRCustomLayerHandler<T>.SwapchainCreateInfo struct that is then passed to the UnityOpenXR lib to actually create the swapchain on the graphics thread. The static OnCreatedSwapchainCallback(int, ulong) method is passed as a callback and invoked when the swapchain has been created.

Declaration

protected virtual void CreateSwapchainAsync(CompositionLayerManager.LayerInfo layerInfo)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that was just created.

Dispose()

Implements method from IDisposable that is called by the OpenXRLayerProvider when this custom layer handler instance is disposed.

Declaration

public void Dispose()

Dispose(bool)

Clears all maps and disposes any created native arrays.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true if this method was called by Dispose. Otherwise, this method was called by the class finalizer.

~OpenXRCustomLayerHandler()

Deinitializes this instance of OpenXRCustomLayerHandler<T>.

Declaration

protected ~OpenXRCustomLayerHandler()

ModifyLayer(LayerInfo)

Implements the OpenXRLayerProvider.ILayerHandler method that is called by the OpenXRLayerProvider when a layer or attached extension has been modified. This implementation asks the subclass for any changes that must be made to the layer via ModifyNativeLayer(LayerInfo, ref T) by sending a reference to the native layer struct.

Declaration

public virtual void ModifyLayer(CompositionLayerManager.LayerInfo layerInfo)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that was modified.

ModifyNativeLayer(LayerInfo, ref T)

Override this method to modify a native composition layer struct in response to changes on the associated Unity.XR.CompositionLayers.Layers.LayerData object or any extension components on the Unity.XR.CompositionLayers.CompositionLayer GameObject.

Declaration

protected abstract bool ModifyNativeLayer(CompositionLayerManager.LayerInfo layerInfo, ref T nativeLayer)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that was modified.
T	nativeLayer	A reference to the native OpenXR structure of the composition layer that was modified. The concrete implementation of this method should update the values of the structure as appropriate.

Returns

Type	Description
bool	A bool indicating success or failure.

Remarks

You must reinitialize the Next pointer with GetExtensionsChain(LayerInfo, ExtensionTarget) to get any potential updates from extension components.

Examples

Modifies an XrCompositionLayerQuad struct with new transform and extension information.

protected override bool ModifyNativeLayer(CompositionLayerManager.LayerInfo layerInfo, ref XrCompositionLayerQuad nativeLayer)
{
    var data = layerInfo.Layer.LayerData as QuadLayerData;
    var transform = layerInfo.Layer.GetComponent<Transform>();

    nativeLayer.Pose = new XrPosef(transform.position, transform.rotation);
    nativeLayer.Size = new XrExtend2Df()
    {
        width = data.GetScaledSize(transform.lossyScale).x,
        height = data.GetScaledSize(transform.lossyScale).y
    };

    unsafe
    {
        nativeLayer.Next = OpenXRLayerUtility.GetExtensionsChain(layerInfo, CompositionLayerExtension.ExtensionTarget.Layer);
    }
    return true;
}

OnCreatedSwapchain(LayerInfo, SwapchainCreatedOutput)

This method is dispatched to the main thread inside OnCreatedSwapchainCallback(int, ulong) and asks this subclass to create the native layer struct by invoking CreateNativeLayer(LayerInfo, SwapchainCreatedOutput, out T).

Declaration

protected virtual void OnCreatedSwapchain(CompositionLayerManager.LayerInfo layerInfo, OpenXRCustomLayerHandler<T>.SwapchainCreatedOutput swapchainOutput)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer that was just created.
OpenXRCustomLayerHandler<T>.SwapchainCreatedOutput	swapchainOutput	Information regarding the swapchain that was created for this layer, such as the associated swapchain handle.

OnUpdate()

Implements the OpenXRLayerProvider.ILayerHandler method that is called by the OpenXRLayerProvider during the Unity update loop.

Declaration

public virtual void OnUpdate()

Remarks

This implementation carries out two tasks. It dequeues actions for the main thread like dispatch when the swapchain has been created, and it adds all the active layers to the endFrameInfo struct in the native UnityOpenXR lib.

RemoveLayer(int)

Implements the OpenXRLayerProvider.ILayerHandler method that is called by the OpenXRLayerProvider when a layer is destroyed or disabled.

Declaration

public virtual void RemoveLayer(int removedLayerId)

Parameters

Type	Name	Description
int	removedLayerId	The unique id of the CompositionLayer component that was removed.

ResizeNativeArrays()

Ensures that the native arrays are of the same size as the m_nativeLayers map.

Declaration

protected virtual void ResizeNativeArrays()

SetActiveLayer(LayerInfo)

Implements the OpenXRLayerProvider.ILayerHandler method that is called by the OpenXRLayerProvider when a layer is considered to be currently active.

Declaration

public virtual void SetActiveLayer(CompositionLayerManager.LayerInfo layerInfo)

Parameters

Type	Name	Description
CompositionLayerManager.LayerInfo	layerInfo	Container for the unique id and CompositionLayer component of the composition layer being set to active.

Implements

OpenXRLayerProvider.ILayerHandler

IDisposable