Class XRCameraSubsystem.Provider

Interface for providing camera functionality for the implementation.

Inheritance

Object

XRCameraSubsystem.Provider

Namespace: UnityEngine.XR.ARSubsystems

Syntax

protected class Provider

Properties

cameraFocusMode

Property to be implemented by the provider to get or set the focus mode for the camera.

Declaration

public virtual CameraFocusMode cameraFocusMode { get; set; }

Property Value

Type	Description
CameraFocusMode

cameraMaterial

Property to be implemented by the provder to get the material used by XRCameraSubsystem to render the camera texture.

Declaration

public virtual Material cameraMaterial { get; }

Property Value

Type	Description
Material	The material to render the camera texture.

currentConfiguration

Property to be implemented by the provider to query/set the current camera configuration.

Declaration

public virtual XRCameraConfiguration? currentConfiguration { get; set; }

Property Value

Type	Description
Nullable<XRCameraConfiguration>	The current camera configuration if it exists. Otherise, null.

Exceptions

Type	Condition
NotSupportedException	Thrown when setting the current configuration if the implementation does not support camera configurations.
ArgumentException	Thrown when setting the current configuration if the given configuration is not a valid, supported camera configuration.
InvalidOperationException	Thrown when setting the current configuration if the implementation is unable to set the current camera configuration.

invertCulling

Whether or not culling should be inverted during rendering. Some front-facing camera modes may require this.

Declaration

public virtual bool invertCulling { get; }

Property Value

Type	Description
Boolean

permissionGranted

Property to be implemented by the provider to determine whether camera permission has been granted.

Declaration

public virtual bool permissionGranted { get; }

Property Value

Type	Description
Boolean	true if camera permission has been granted. Otherwise, false.

Methods

ConvertAsync(Int32, XRCameraImageConversionParams)

Method to be implemented by the provider to create an asynchronous request to convert a camera image, similar to TryConvert(Int32, XRCameraImageConversionParams, IntPtr, Int32) except the conversion should happen on a thread other than the calling (main) thread.

Declaration

public virtual int ConvertAsync(int nativeHandle, XRCameraImageConversionParams conversionParams)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
XRCameraImageConversionParams	conversionParams	The parameters to use during the conversion.

Returns

Type	Description
Int32	A unique identifier for this request.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

ConvertAsync(Int32, XRCameraImageConversionParams, XRCameraSubsystem.OnImageRequestCompleteDelegate, IntPtr)

Method to be implemented by the provider to similar to ConvertAsync(Int32, XRCameraImageConversionParams) but takes a delegate to invoke when the request is complete, rather than returning a request id.

Declaration

public virtual void ConvertAsync(int nativeHandle, XRCameraImageConversionParams conversionParams, XRCameraSubsystem.OnImageRequestCompleteDelegate callback, IntPtr context)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
XRCameraImageConversionParams	conversionParams	The parameters to use during the conversion.
XRCameraSubsystem.OnImageRequestCompleteDelegate	callback	A delegate which must be invoked when the request is complete, whether the conversion was successfully or not.
IntPtr	context	A native pointer which must be passed back unaltered to callback.

Remarks

If the first parameter to callback is Ready then the dataPtr parameter must be valid for the duration of the invocation. The data may be destroyed immediately upon return. The context parameter must be passed back to the callback.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

CreateCameraMaterial(String)

Create the camera material from the given camera shader name.

Declaration

protected Material CreateCameraMaterial(string cameraShaderName)

Parameters

Type	Name	Description
String	cameraShaderName	The name of the camera shader.

Returns

Type	Description
Material	The created camera material shader.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the shader cannot be found or if a material cannot be created for the shader.

Destroy()

Method to be implemented by provider to destroy the camera for the subsystem.

Declaration

public virtual void Destroy()

DisposeAsyncRequest(Int32)

Method to be implemented by the provider to dispose an existing async conversion request.

Declaration

public virtual void DisposeAsyncRequest(int requestId)

Parameters

Type	Name	Description
Int32	requestId	A unique identifier for the request.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

See Also

ConvertAsync(Int32, XRCameraImageConversionParams)

DisposeImage(Int32)

Method to be implemented by the provider to dispose an existing native image identified by nativeHandle.

Declaration

public virtual void DisposeImage(int nativeHandle)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for this camera image.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

See Also

TryAcquireLatestImage(out XRCameraSubsystem.CameraImageCinfo)

GetAsyncRequestStatus(Int32)

Method to be implemented by the provider to get the status of an existing asynchronous conversion request.

Declaration

public virtual AsyncCameraImageConversionStatus GetAsyncRequestStatus(int requestId)

Parameters

Type	Name	Description
Int32	requestId	The unique identifier associated with a request.

Returns

Type	Description
AsyncCameraImageConversionStatus	The state of the request.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

See Also

ConvertAsync(Int32, XRCameraImageConversionParams)

GetConfigurations(XRCameraConfiguration, Allocator)

Method to be implemented by the provider to query the supported camera configurations.

Declaration

public virtual NativeArray<XRCameraConfiguration> GetConfigurations(XRCameraConfiguration defaultCameraConfiguration, Allocator allocator)

Parameters

Type	Name	Description
XRCameraConfiguration	defaultCameraConfiguration	A default value used to fill the returned array before copying in real values. This ensures future additions to this struct are backwards compatible.
Allocator	allocator	The allocation strategy to use for the returned data.

Returns

Type	Description
NativeArray<XRCameraConfiguration>	The supported camera configurations.

GetTextureDescriptors(XRTextureDescriptor, Allocator)

Get the XRTextureDescriptors associated with the current XRCameraFrame.

Declaration

public virtual NativeArray<XRTextureDescriptor> GetTextureDescriptors(XRTextureDescriptor defaultDescriptor, Allocator allocator)

Parameters

Type	Name	Description
XRTextureDescriptor	defaultDescriptor	A default value which should be used to fill the returned array before copying in the real values. This ensures future additions to this struct are backwards compatible.
Allocator	allocator	The allocator to use when creating the returned NativeArray.

Returns

Type	Description
NativeArray<XRTextureDescriptor>	The current texture descriptors.

NativeHandleValid(Int32)

Method to be implemented by the provider to determine whether a native image handle returned by TryAcquireLatestImage(out XRCameraSubsystem.CameraImageCinfo) is currently valid. An image may become invalid if it has been disposed.

Declaration

public virtual bool NativeHandleValid(int nativeHandle)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image in question.

Returns

Type	Description
Boolean	true, if it is a valid handle. Otherwise, false.

Remarks

If a handle is valid, TryConvert(Int32, XRCameraImageConversionParams, IntPtr, Int32) and TryGetConvertedDataSize(Int32, Vector2Int, TextureFormat, out Int32) should not fail.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

See Also

DisposeImage(Int32)

Start()

Method to be implemented by provider to start the camera for the subsystem.

Declaration

public virtual void Start()

Stop()

Method to be implemented by provider to stop the camera for the subsystem.

Declaration

public virtual void Stop()

TryAcquireLatestImage(out XRCameraSubsystem.CameraImageCinfo)

Method to be implemented by the provider to query for the latest native camera image.

Declaration

public virtual bool TryAcquireLatestImage(out XRCameraSubsystem.CameraImageCinfo cameraImageCinfo)

Parameters

Type	Name	Description
XRCameraSubsystem.CameraImageCinfo	cameraImageCinfo	The metadata required to construct a XRCameraImage

Returns

Type	Description
Boolean	true if the camera image is acquired. Otherwise, false.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

TryConvert(Int32, XRCameraImageConversionParams, IntPtr, Int32)

Method to be implemented by the provider to convert the image with handle nativeHandle using the provided .

Declaration

public virtual bool TryConvert(int nativeHandle, XRCameraImageConversionParams conversionParams, IntPtr destinationBuffer, int bufferLength)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
XRCameraImageConversionParams	conversionParams	The parameters to use during the conversion.
IntPtr	destinationBuffer	A buffer to write the converted image to.
Int32	bufferLength	The number of bytes available in the buffer.

Returns

Type	Description
Boolean	true if the image was converted and stored in destinationBuffer.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

TryGetAsyncRequestData(Int32, out IntPtr, out Int32)

Method to be implemented by the provider to get a pointer to the image data from a completed asynchronous request. This method should only succeed if GetAsyncRequestStatus(Int32) returns Ready.

Declaration

public virtual bool TryGetAsyncRequestData(int requestId, out IntPtr dataPtr, out int dataLength)

Parameters

Type	Name	Description
Int32	requestId	The unique identifier associated with a request.
IntPtr	dataPtr	A pointer to the native buffer containing the data.
Int32	dataLength	The number of bytes in dataPtr.

Returns

Type	Description
Boolean	true if dataPtr and dataLength were set and point to the image data.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

TryGetConvertedDataSize(Int32, Vector2Int, TextureFormat, out Int32)

Method to be implemented by the provider to get the number of bytes required to store an image with the given dimensions and TextureFormat.

Declaration

public virtual bool TryGetConvertedDataSize(int nativeHandle, Vector2Int dimensions, TextureFormat format, out int size)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
Vector2Int	dimensions	The dimensions of the output image.
TextureFormat	format	The TextureFormat for the image.
Int32	size	The number of bytes required to store the converted image.

Returns

Type	Description
Boolean	true if the output size was set.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

TryGetFrame(XRCameraParams, out XRCameraFrame)

Method to be implemented by provider to get the camera frame for the subsystem.

Declaration

public virtual bool TryGetFrame(XRCameraParams cameraParams, out XRCameraFrame cameraFrame)

Parameters

Type	Name	Description
XRCameraParams	cameraParams	The current Unity Camera parameters.
XRCameraFrame	cameraFrame	The current camera frame returned by the method.

Returns

Type	Description
Boolean	true if the method successfully got a frame. Otherwise, false.

TryGetIntrinsics(out XRCameraIntrinsics)

Method to be implemented by the provider to get the camera intrinisics information.

Declaration

public virtual bool TryGetIntrinsics(out XRCameraIntrinsics cameraIntrinsics)

Parameters

Type	Name	Description
XRCameraIntrinsics	cameraIntrinsics	The camera intrinsics information returned from the method.

Returns

Type	Description
Boolean	true if the method successfully gets the camera intrinsics information. Otherwise, false.

TryGetPlane(Int32, Int32, out XRCameraSubsystem.CameraImagePlaneCinfo)

Method to be implemented by the provider to get information about an image plane from a native image handle by index.

Declaration

public virtual bool TryGetPlane(int nativeHandle, int planeIndex, out XRCameraSubsystem.CameraImagePlaneCinfo planeCinfo)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for this camera image.
Int32	planeIndex	The index of the plane to get.
XRCameraSubsystem.CameraImagePlaneCinfo	planeCinfo	The returned camera plane information if successful.

Returns

Type	Description
Boolean	true if the image plane was acquired. Otherwise, false.

Exceptions

Type	Condition
NotSupportedException	Thrown if the implementation does not support camera image.

See Also

TryAcquireLatestImage(out XRCameraSubsystem.CameraImageCinfo)

TrySetLightEstimationMode(LightEstimationMode)

Method to be implemented by the provider to set the light estimation mode.

Declaration

public virtual bool TrySetLightEstimationMode(LightEstimationMode lightEstimationMode)

Parameters

Type	Name	Description
LightEstimationMode	lightEstimationMode	The light estimation mode to set.

Returns

Type	Description
Boolean	true if the method successfully set the light estimation mode. Otherwise, false.