Class XRCpuImage.Api

An API for interacting with XRCpuImages.

Inheritance

Object

XRCpuImage.Api

Inherited Members

Object.ToString()

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: UnityEngine.XR.ARSubsystems

Syntax

public abstract class Api

Remarks

This interface is intended to be implemented by AR platform providers (for example, ARCore, ARKit, and Open XR). The XRCpuImage uses it to make platform-specific API calls. Unity developers don't need to interact directly with this class; use the XRCpuImage instead.

Methods

ConvertAsync(Int32, XRCpuImage.ConversionParams)

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

Declaration

public virtual int ConvertAsync(int nativeHandle, XRCpuImage.ConversionParams conversionParams)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
XRCpuImage.ConversionParams	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, XRCpuImage.ConversionParams, XRCpuImage.Api.OnImageRequestCompleteDelegate, IntPtr)

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

Declaration

public virtual void ConvertAsync(int nativeHandle, XRCpuImage.ConversionParams conversionParams, XRCpuImage.Api.OnImageRequestCompleteDelegate callback, IntPtr context)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
XRCpuImage.ConversionParams	conversionParams	The parameters to use during the conversion.
XRCpuImage.Api.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, the dataPtr parameter must be valid for the duration of the invocation. The data can 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.

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, XRCpuImage.ConversionParams)

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.

FormatSupported(XRCpuImage, TextureFormat)

Determines whether a given TextureFormat is supported for image conversion.

Declaration

public virtual bool FormatSupported(XRCpuImage image, TextureFormat format)

Parameters

Type	Name	Description
XRCpuImage	image	The XRCpuImage to convert.
UnityEngine.TextureFormat	format	The TextureFormat to test.

Returns

Type	Description
Boolean	Returns true if image can be converted to format. Returns false otherwise.

GetAsyncRequestStatus(Int32)

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

Declaration

public virtual XRCpuImage.AsyncConversionStatus GetAsyncRequestStatus(int requestId)

Parameters

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

Returns

Type	Description
XRCpuImage.AsyncConversionStatus	The state of the request.

Exceptions

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

See Also

ConvertAsync(Int32, XRCpuImage.ConversionParams)

NativeHandleValid(Int32)

Method to be implemented by the provider to determine whether a native image handle is currently valid. An image can 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, XRCpuImage.ConversionParams, 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)

TryConvert(Int32, XRCpuImage.ConversionParams, IntPtr, Int32)

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

Declaration

public virtual bool TryConvert(int nativeHandle, XRCpuImage.ConversionParams conversionParams, IntPtr destinationBuffer, int bufferLength)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for the camera image to convert.
XRCpuImage.ConversionParams	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.
UnityEngine.Vector2Int	dimensions	The dimensions of the output image.
UnityEngine.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 conversion.

TryGetPlane(Int32, Int32, out XRCpuImage.Plane.Cinfo)

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 XRCpuImage.Plane.Cinfo planeCinfo)

Parameters

Type	Name	Description
Int32	nativeHandle	A unique identifier for this camera image.
Int32	planeIndex	The index of the plane to get.
XRCpuImage.Plane.Cinfo	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.