Struct XRCameraImage

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(XRCameraImageConversionParams, IntPtr, Int32) and ConvertAsync(XRCameraImageConversionParams). Use TryGetLatestImage(out XRCameraImage) to get a XRCameraImage.

Namespace: UnityEngine.XR.ARSubsystems

Syntax

public struct XRCameraImage : IDisposable, IEquatable<XRCameraImage>

Remarks

Each XRCameraImage 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 CameraImageFormat format { get; }

Property Value

Type	Description
CameraImageFormat	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 XRCameraImage represents a valid image (i.e., not Disposed).

Declaration

public bool valid { get; }

Property Value

Type	Description
Boolean	true if this XRCameraImage 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(XRCameraImageConversionParams, IntPtr, Int32)

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

Declaration

public void Convert(XRCameraImageConversionParams conversionParams, IntPtr destinationBuffer, int bufferLength)

Parameters

Type	Name	Description
XRCameraImageConversionParams	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(XRCameraImageConversionParams).

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)

ConvertAsync(XRCameraImageConversionParams)

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

Declaration

public XRAsyncCameraImageConversion ConvertAsync(XRCameraImageConversionParams conversionParams)

Parameters

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

Returns

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

Remarks

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

See Also

FormatSupported(TextureFormat)

ConvertAsync(XRCameraImageConversionParams, Action<AsyncCameraImageConversionStatus, XRCameraImageConversionParams, NativeArray<Byte>>)

Convert the XRCameraImage 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(XRCameraImageConversionParams conversionParams, Action<AsyncCameraImageConversionStatus, XRCameraImageConversionParams, NativeArray<byte>> onComplete)

Parameters

Type	Name	Description
XRCameraImageConversionParams	conversionParams	The parameters to use for the conversion.
Action<AsyncCameraImageConversionStatus, XRCameraImageConversionParams, NativeArray<Byte>>	onComplete	A delegate to invoke when the conversion operation completes. The delegate is always invoked.

See Also

FormatSupported(TextureFormat)

Dispose()

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

Declaration

public void Dispose()

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj

Returns

Type	Description
Boolean

Overrides

ValueType.Equals(Object)

Equals(XRCameraImage)

Declaration

public bool Equals(XRCameraImage other)

Parameters

Type	Name	Description
XRCameraImage	other

Returns

Type	Description
Boolean

FormatSupported(TextureFormat)

Determines whether the given TextureFormat is supported for conversion.

Declaration

public static bool FormatSupported(TextureFormat format)

Parameters

Type	Name	Description
TextureFormat	format	A TextureFormat to test.

Returns

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

Remarks

These texture formats are supported:

• TextureFormat.R8
• TextureFormat.Alpha8
• TextureFormat.RGB24
• TextureFormat.RGBA32
• TextureFormat.ARGBA32
• TextureFormat.BGRA32

GetConvertedDataSize(XRCameraImageConversionParams)

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

Declaration

public int GetConvertedDataSize(XRCameraImageConversionParams conversionParams)

Parameters

Type	Name	Description
XRCameraImageConversionParams	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)

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)

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

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 XRCameraImagePlane GetPlane(int planeIndex)

Parameters

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

Returns

Type	Description
XRCameraImagePlane	A XRCameraImagePlane 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()

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

ValueType.ToString()

Operators

Equality(XRCameraImage, XRCameraImage)

Declaration

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

Parameters

Type	Name	Description
XRCameraImage	lhs
XRCameraImage	rhs

Returns

Type	Description
Boolean

Inequality(XRCameraImage, XRCameraImage)

Declaration

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

Parameters

Type	Name	Description
XRCameraImage	lhs
XRCameraImage	rhs

Returns

Type	Description
Boolean