Class XRCpuImage.Api

An API for interacting with XRCpuImages.

Inheritance
Object
XRCpuImage.Api
Namespace: UnityEngine.XR.ARSubsystems
Syntax
public abstract class Api
Remarks

This interface is intended to be implemented by AR platform providers (e.g., ARCore, ARKit, Magic Leap, & HoloLens). The XRCpuImage uses it to make platform-specific API calls. Unity developers need not 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 to 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 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.

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

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

NativeHandleValid(Int32)

Method to be implemented by the provider to determine whether a native image handle 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, 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

TryConvert(Int32, XRCpuImage.ConversionParams, 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, 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.
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 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.