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 |
|
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 |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the |
InvalidOperationException | Thrown if the conversion failed. |
See Also
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
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
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
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 |
Returns
Type | Description |
---|---|
Boolean |
|
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
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 |
Returns
Type | Description |
---|---|
Int32 | The number of bytes required to store the converted image. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the desired |
ArgumentOutOfRangeException | Thrown if the desired |
InvalidOperationException | Thrown if the image is invalid. |
See Also
GetHashCode()
Declaration
public override int GetHashCode()
Returns
Type | Description |
---|---|
Int32 |
Overrides
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 |
InvalidOperationException | Thrown if the requested plane is not valid. |
ToString()
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
String |
Overrides
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 |