Struct XRCpuImage

Represents a single, raw image from a device camera. Provides access to the raw image plane data, as well as conversion methods to convert to color and grayscale formats. See Convert(XRCpuImage.ConversionParams, IntPtr, Int32) and ConvertAsync(XRCpuImage.ConversionParams). Use TryAcquireLatestCpuImage(out XRCpuImage) to get a XRCpuImage.

Namespace: UnityEngine.XR.ARSubsystems

Syntax

public struct XRCpuImage : IDisposable, IEquatable<XRCpuImage>

Remarks

Each XRCpuImage must be explicitly disposed. Failing to do so will leak resources and could prevent future camera image access.

Properties

dimensions

The dimensions (width and height) of the image.

Declaration

public Vector2Int dimensions { get; }

Property Value

Type	Description
Vector2Int	The dimensions (width and height) of the image.

format

The format used by the image planes. You will only need this if you plan to interpret the raw plane data.

Declaration

public XRCpuImage.Format format { get; }

Property Value

Type	Description
XRCpuImage.Format	The format used by the image planes.

height

The image height.

Declaration

public int height { get; }

Property Value

Type	Description
Int32	The image height.

planeCount

The number of image planes. A "plane" in this context refers to a channel in the raw video format, not a physical surface.

Declaration

public int planeCount { get; }

Property Value

Type	Description
Int32	The number of image planes.

timestamp

The timestamp, in seconds, associated with this camera image

Declaration

public double timestamp { get; }

Property Value

Type	Description
Double	The timestamp, in seconds, associated with this camera image

valid

Whether this XRCpuImage represents a valid image (i.e., not Disposed).

Declaration

public bool valid { get; }

Property Value

Type	Description
Boolean	true if this XRCpuImage represents a valid image. Otherwise, false.

width

The image width.

Declaration

public int width { get; }

Property Value

Type	Description
Int32	The image width.

Methods

Convert(XRCpuImage.ConversionParams, IntPtr, Int32)

Convert the XRCpuImage to one of the supported formats using the specified conversionParams.

Declaration

public void Convert(XRCpuImage.ConversionParams conversionParams, IntPtr destinationBuffer, int bufferLength)

Parameters

Type	Name	Description
XRCpuImage.ConversionParams	conversionParams	The parameters for the image conversion.
IntPtr	destinationBuffer	A pointer to memory to which to write the converted image.
Int32	bufferLength	The number of bytes pointed to by destinationBuffer. Must be greater than or equal to the value returned by GetConvertedDataSize(XRCpuImage.ConversionParams).

Exceptions

Type	Condition
ArgumentException	Thrown if the bufferLength is smaller than the data size required by the conversion.
InvalidOperationException	Thrown if the conversion failed.

See Also

FormatSupported(TextureFormat)

Convert(XRCpuImage.ConversionParams, NativeSlice<Byte>)

Convert the XRCpuImage to one of the supported formats using the specified conversionParams.

Declaration

public void Convert(XRCpuImage.ConversionParams conversionParams, NativeSlice<byte> destinationBuffer)

Parameters

Type	Name	Description
XRCpuImage.ConversionParams	conversionParams	The parameters for the image conversion.
NativeSlice<Byte>	destinationBuffer	The destination buffer for the converted data. The buffer must be large enough to hold the converted data, that is, at least as large as the value returned by GetConvertedDataSize(XRCpuImage.ConversionParams).

Exceptions

Type	Condition
ArgumentException	Thrown if the destinationBuffer has insufficient space for the converted data.
InvalidOperationException	Thrown if the conversion failed.

See Also

FormatSupported(TextureFormat)

ConvertAsync(XRCpuImage.ConversionParams)

Convert the XRCpuImage to one of the supported formats using the specified conversionParams. The conversion is performed asynchronously. Use the returned XRCpuImage.AsyncConversion to check for the status of the conversion, and retrieve the data when complete.

Declaration

public XRCpuImage.AsyncConversion ConvertAsync(XRCpuImage.ConversionParams conversionParams)

Parameters

Type	Name	Description
XRCpuImage.ConversionParams	conversionParams	The parameters to use for the conversion.

Returns

Type	Description
XRCpuImage.AsyncConversion	A XRCpuImage.AsyncConversion which can be used to check the status of the conversion operation and get the resulting data.

Remarks

It is safe to Dispose the XRCpuImage before the asynchronous operation has completed.

See Also

FormatSupported(TextureFormat)

ConvertAsync(XRCpuImage.ConversionParams, Action<XRCpuImage.AsyncConversionStatus, XRCpuImage.ConversionParams, NativeArray<Byte>>)

Convert the XRCpuImage to one of the supported formats using the specified conversionParams. The conversion is performed asynchronously, and onComplete is invoked when the conversion is complete, whether successful or not.

The NativeArray provided in the onComplete delegate is only valid during the invocation and is disposed immediately upon return.

Declaration

public void ConvertAsync(XRCpuImage.ConversionParams conversionParams, Action<XRCpuImage.AsyncConversionStatus, XRCpuImage.ConversionParams, NativeArray<byte>> onComplete)

Parameters

Type	Name	Description
XRCpuImage.ConversionParams	conversionParams	The parameters to use for the conversion.
Action<XRCpuImage.AsyncConversionStatus, XRCpuImage.ConversionParams, NativeArray<Byte>>	onComplete	A delegate to invoke when the conversion operation completes. The delegate is always invoked, regardless of whether the conversion succeeded.

See Also

FormatSupported(TextureFormat)

Dispose()

Dispose native resources associated with this request, including the raw image data. Any XRCpuImage.Planes returned by GetPlane(Int32) are invalidated immediately after calling Dispose.

Declaration

public void Dispose()

Equals(Object)

Tests for equality.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj	The object to compare against.

Returns

Type	Description
Boolean	True if obj is of type XRCpuImage and Equals(XRCpuImage) also returns true; otherwise false.

Overrides

ValueType.Equals(Object)

Equals(XRCpuImage)

Tests for equality.

Declaration

public bool Equals(XRCpuImage other)

Parameters

Type	Name	Description
XRCpuImage	other	The other XRCpuImage to compare against.

Returns

Type	Description
Boolean	True if every field in other is equal to this XRCpuImage, otherwise false.

FormatSupported(TextureFormat)

Determines whether the given TextureFormat is supported for conversion.

Declaration

public bool FormatSupported(TextureFormat format)

Parameters

Type	Name	Description
TextureFormat	format	A TextureFormat to test.

Returns

Type	Description
Boolean	Returns true if format is supported by the various conversion methods.

GetConvertedDataSize(Vector2Int, TextureFormat)

Get the number of bytes required to store a converted image with the given parameters.

Declaration

public int GetConvertedDataSize(Vector2Int dimensions, TextureFormat format)

Parameters

Type	Name	Description
Vector2Int	dimensions	The desired dimensions of the converted image.
TextureFormat	format	The desired TextureFormat for the converted image.

Returns

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

Exceptions

Type	Condition
ArgumentException	Thrown if the desired format is not supported.
ArgumentOutOfRangeException	Thrown if the desired dimensions exceed the native image dimensions.
InvalidOperationException	Thrown if the image is invalid.

See Also

FormatSupported(TextureFormat)

GetConvertedDataSize(XRCpuImage.ConversionParams)

Get the number of bytes required to store a converted image with the given parameters.

Declaration

public int GetConvertedDataSize(XRCpuImage.ConversionParams conversionParams)

Parameters

Type	Name	Description
XRCpuImage.ConversionParams	conversionParams	The desired conversion parameters.

Returns

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

Exceptions

Type	Condition
ArgumentException	Thrown if the desired format is not supported.
ArgumentOutOfRangeException	Thrown if the desired dimensions exceed the native image dimensions.
InvalidOperationException	Thrown if the image is invalid.

See Also

FormatSupported(TextureFormat)

GetHashCode()

Generates a hash suitable for use with containers like HashSet and Dictionary.

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	A hash code generated from this object's fields.

Overrides

ValueType.GetHashCode()

GetPlane(Int32)

Get an image "plane". A "plane" in this context refers to a channel in the raw video format, not a physical surface.

Declaration

public XRCpuImage.Plane GetPlane(int planeIndex)

Parameters

Type	Name	Description
Int32	planeIndex	The index of the plane to get.

Returns

Type	Description
XRCpuImage.Plane	A XRCpuImage.Plane describing the plane.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if planeIndex is not within the range [0, planeCount).
InvalidOperationException	Thrown if the requested plane is not valid.

ToString()

Generates a string representation of this XRCpuImage.

Declaration

public override string ToString()

Returns

Type	Description
String	A string representation of this XRCpuImage.

Overrides

ValueType.ToString()

Operators

Equality(XRCpuImage, XRCpuImage)

Tests for equality. Same as Equals(XRCpuImage).

Declaration

public static bool operator ==(XRCpuImage lhs, XRCpuImage rhs)

Parameters

Type	Name	Description
XRCpuImage	lhs	The XRCpuImage to compare with rhs.
XRCpuImage	rhs	The XRCpuImage to compare with lhs.

Returns

Type	Description
Boolean	True if lhs is equal to rhs, otherwise false.

Inequality(XRCpuImage, XRCpuImage)

Tests for inequality. Same as !Equals(XRCpuImage).

Declaration

public static bool operator !=(XRCpuImage lhs, XRCpuImage rhs)

Parameters

Type	Name	Description
XRCpuImage	lhs	The XRCpuImage to compare with rhs.
XRCpuImage	rhs	The XRCpuImage to compare with lhs.

Returns

Type	Description
Boolean	True if lhs is not equal to rhs, otherwise false.