Class XRCpuImage.Api

An API for interacting with XRCpuImages.

Inheritance
object
XRCpuImage.Api
Inherited Members
Namespace: UnityEngine.XR.ARSubsystems
Assembly: Unity.XR.ARSubsystems.dll
Syntax
public abstract class XRCpuImage.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(int, ConversionParams)

Method to be implemented by the provider to create an asynchronous request to convert a camera image, similar to TryConvert(int, ConversionParams, IntPtr, int) 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
int nativeHandle

A unique identifier for the camera image to convert.
XRCpuImage.ConversionParams conversionParams

The parameters to use during the conversion.
Returns
Type Description
int

A unique identifier for this request.
Exceptions
Type Condition
NotSupportedException

Thrown if the implementation does not support camera image.

ConvertAsync(int, ConversionParams, OnImageRequestCompleteDelegate, IntPtr)

Method to be implemented by the provider. It is similar to ConvertAsync(int, 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
int 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 successful 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(int)

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
int requestId

A unique identifier for the request.
Exceptions
Type Condition
NotSupportedException

Thrown if the implementation does not support camera image.
See Also

DisposeImage(int)

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
int 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.
TextureFormat format

The TextureFormat to test.
Returns
Type Description
bool

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

GetAsyncRequestStatus(int)

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

NativeHandleValid(int)

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
int nativeHandle

A unique identifier for the camera image in question.
Returns
Type Description
bool

true, if it is a valid handle. Otherwise, false.
Remarks

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

Exceptions
Type Condition
NotSupportedException

Thrown if the implementation does not support camera image.
See Also

TryConvert(int, ConversionParams, IntPtr, int)

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
int 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.
int bufferLength

The number of bytes available in the buffer.
Returns
Type Description
bool

true if the image was converted and stored in destinationBuffer.
Exceptions
Type Condition
NotSupportedException

Thrown if the implementation does not support camera image.

TryGetAsyncRequestData(int, out IntPtr, out int)

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(int) returns Ready.

Declaration
public virtual bool TryGetAsyncRequestData(int requestId, out IntPtr dataPtr, out int dataLength)
Parameters
Type Name Description
int requestId

The unique identifier associated with a request.
IntPtr dataPtr

A pointer to the native buffer containing the data.
int dataLength

The number of bytes in dataPtr.
Returns
Type Description
bool

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(int, Vector2Int, TextureFormat, out int)

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
int 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.
int size

The number of bytes required to store the converted image.
Returns
Type Description
bool

true if the output size was set.
Exceptions
Type Condition
NotSupportedException

Thrown if the implementation does not support camera image conversion.

TryGetPlane(int, int, out 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
int nativeHandle

A unique identifier for this camera image.
int planeIndex

The index of the plane to get.
XRCpuImage.Plane.Cinfo planeCinfo

The returned camera plane information if successful.
Returns
Type Description
bool

true if the image plane was acquired. Otherwise, false.
Exceptions
Type Condition
NotSupportedException

Thrown if the implementation does not support camera image.