Repository/Library/PackageCache/com.unity.xr.arsubsystems@3.1.3/Runtime/CameraSubsystem/XRCameraImage.cs

using AOT;
using System;
using System.Runtime.InteropServices;
using Unity.Collections;
using Unity.Collections.LowLevel.Unsafe;

namespace UnityEngine.XR.ARSubsystems
{
    /// <summary>
    /// 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 <see cref="Convert"/> and
    /// <see cref="ConvertAsync(XRCameraImageConversionParams)"/>. Use
    /// <see cref="XRCameraSubsystem.TryGetLatestImage"/> to get a <c>XRCameraImage</c>.
    /// </summary>
    /// <remarks>
    /// Each <c>XRCameraImage</c> must be explicitly disposed. Failing to do so will leak resources and could prevent
    /// future camera image access.
    /// </remarks>
    public struct XRCameraImage : IDisposable, IEquatable<XRCameraImage>
    {
        int m_NativeHandle;

        XRCameraSubsystem m_CameraSubsystem;

        static XRCameraSubsystem.OnImageRequestCompleteDelegate s_OnAsyncConversionComplete;

#if ENABLE_UNITY_COLLECTIONS_CHECKS
        AtomicSafetyHandle m_SafetyHandle;
#endif

        /// <summary>
        /// The dimensions (width and height) of the image.
        /// </summary>
        /// <value>
        /// The dimensions (width and height) of the image.
        /// </value>
        public Vector2Int dimensions { get; private set; }

        /// <summary>
        /// The image width.
        /// </summary>
        /// <value>
        /// The image width.
        /// </value>
        public int width { get { return dimensions.x; } }

        /// <summary>
        /// The image height.
        /// </summary>
        /// <value>
        /// The image height.
        /// </value>
        public int height { get { return dimensions.y; } }

        /// <summary>
        /// The number of image planes. A "plane" in this context refers to a channel in the raw video format,
        /// not a physical surface.
        /// </summary>
        /// <value>
        /// The number of image planes.
        /// </value>
        public int planeCount { get; private set; }

        /// <summary>
        /// The format used by the image planes. You will only need this if you plan to interpret the raw plane data.
        /// </summary>
        /// <value>
        /// The format used by the image planes.
        /// </value>
        public CameraImageFormat format { get; private set; }

        /// <summary>
        /// The timestamp, in seconds, associated with this camera image
        /// </summary>
        /// <value>
        /// The timestamp, in seconds, associated with this camera image
        /// </value>
        public double timestamp { get; private set; }

        /// <summary>
        /// Whether this <c>XRCameraImage</c> represents a valid image (i.e., not Disposed).
        /// </summary>
        /// <value>
        /// <c>true</c> if this <c>XRCameraImage</c> represents a valid image. Otherwise, <c>false</c>.
        /// </value>
        public bool valid
        {
            get { return (m_CameraSubsystem != null) && m_CameraSubsystem.NativeHandleValid(m_NativeHandle); }
        }

        /// <summary>
        /// Initialize the static callback for when the image request completes.
        /// </summary>
        static XRCameraImage()
        {
            s_OnAsyncConversionComplete = new XRCameraSubsystem.OnImageRequestCompleteDelegate(OnAsyncConversionComplete);
        }

        /// <summary>
        /// Construct the <c>XRCameraImage</c> with the given native image information.
        /// </summary>
        /// <param name="cameraSubsystem">The camera subsystem to use for interacting with the native image.</param>
        /// <param name="nativeHandle">The native image handle.</param>
        /// <param name="dimensions">The dimensions of the native image.</param>
        /// <param name="planeCount">The number of video planes in the native image.</param>
        /// <param name="timestamp">The timestamp for when the native image was captured.</param>
        /// <param name="format">The camera image format of the native image.</param>
        internal XRCameraImage(
            XRCameraSubsystem cameraSubsystem,
            int nativeHandle,
            Vector2Int dimensions,
            int planeCount,
            double timestamp,
            CameraImageFormat format)
        {
            m_CameraSubsystem = cameraSubsystem;
            m_NativeHandle = nativeHandle;
            this.dimensions = dimensions;
            this.planeCount = planeCount;
            this.timestamp = timestamp;
            this.format = format;

#if ENABLE_UNITY_COLLECTIONS_CHECKS
            m_SafetyHandle = AtomicSafetyHandle.Create();
#endif
        }

        /// <summary>
        /// Determines whether the given <c>TextureFormat</c> is supported for conversion.
        /// </summary>
        /// <remarks>
        /// These texture formats are supported:
        /// <list type="bullet">
        /// <item><description><c>TextureFormat.R8</c></description></item>
        /// <item><description><c>TextureFormat.Alpha8</c></description></item>
        /// <item><description><c>TextureFormat.RGB24</c></description></item>
        /// <item><description><c>TextureFormat.RGBA32</c></description></item>
        /// <item><description><c>TextureFormat.ARGBA32</c></description></item>
        /// <item><description><c>TextureFormat.BGRA32</c></description></item>
        /// </list>
        /// </remarks>
        /// <param name="format">A <c>TextureFormat</c> to test.</param>
        /// <returns><c>true</c> if the format is supported by the various conversion methods.</returns>
        public static bool FormatSupported(TextureFormat format)
        {
            switch (format)
            {
                case TextureFormat.Alpha8:
                case TextureFormat.R8:
                case TextureFormat.RGB24:
                case TextureFormat.RGBA32:
                case TextureFormat.ARGB32:
                case TextureFormat.BGRA32:
                    return true;
                default:
                    return false;
            }
        }

        /// <summary>
        /// Get an image "plane". A "plane" in this context refers to a channel in the raw video format, not a physical
        /// surface.
        /// </summary>
        /// <param name="planeIndex">The index of the plane to get.</param>
        /// <returns>A <see cref="XRCameraImagePlane"/> describing the plane.</returns>
        /// <exception cref="System.ArgumentOutOfRangeException">Thrown if <paramref name="planeIndex"/> is not within
        /// the range [0, <see cref="planeCount"/>).</exception>
        /// <exception cref="System.InvalidOperationException">Thrown if the requested plane is not valid.</exception>
        public unsafe XRCameraImagePlane GetPlane(int planeIndex)
        {
            ValidateNativeHandleAndThrow();
            if (planeIndex < 0 || planeIndex >= planeCount)
            {
                throw new ArgumentOutOfRangeException("planeIndex",
                    string.Format("planeIndex must be in the range 0 to {0}", planeCount - 1));
            }

            XRCameraSubsystem.CameraImagePlaneCinfo imagePlaneCinfo;
            if (!m_CameraSubsystem.TryGetPlane(m_NativeHandle, planeIndex, out imagePlaneCinfo))
            {
                throw new InvalidOperationException("The requested plane is not valid for this XRCameraImage.");
            }

            var data = NativeArrayUnsafeUtility.ConvertExistingDataToNativeArray<byte>(
                (void*)imagePlaneCinfo.dataPtr, imagePlaneCinfo.dataLength, Allocator.None);

#if ENABLE_UNITY_COLLECTIONS_CHECKS
            NativeArrayUnsafeUtility.SetAtomicSafetyHandle(ref data, m_SafetyHandle);
#endif

            return new XRCameraImagePlane
            {
                rowStride = imagePlaneCinfo.rowStride,
                pixelStride = imagePlaneCinfo.pixelStride,
                data = data
            };
        }

        /// <summary>
        /// Get the number of bytes required to store a converted image with the given parameters.
        /// </summary>
        /// <param name="dimensions">The desired dimensions of the converted image.</param>
        /// <param name="format">The desired <c>TextureFormat</c> for the converted image.</param>
        /// <returns>The number of bytes required to store the converted image.</returns>
        /// <exception cref="System.ArgumentException">Thrown if the desired <paramref name="format"/> is not
        /// supported.</exception>
        /// <exception cref="System.ArgumentOutOfRangeException">Thrown if the desired <paramref name="dimensions"/>
        /// exceed the native image dimensions.</exception>
        /// <exception cref="System.InvalidOperationException">Thrown if the image is invalid.</exception>
        /// <seealso cref="FormatSupported"/>
        public int GetConvertedDataSize(Vector2Int dimensions, TextureFormat format)
        {
            ValidateNativeHandleAndThrow();

            if (dimensions.x > this.dimensions.x)
            {
                throw new ArgumentOutOfRangeException("width",
                    string.Format("Converted image width must be less than or equal to native image width. {0} > {1}",
                                  dimensions.x, this.dimensions.x));
            }

            if (dimensions.y > this.dimensions.y)
            {
                throw new ArgumentOutOfRangeException("height",
                    string.Format("Converted image height must be less than or equal to native image height. {0} > {1}",
                                  dimensions.y, this.dimensions.y));
            }

            if (!FormatSupported(format))
            {
                throw new ArgumentException("Invalid texture format.", "format");
            }

            int size;
            if (!m_CameraSubsystem.TryGetConvertedDataSize(m_NativeHandle, dimensions, format, out size))
            {
                throw new InvalidOperationException("XRCameraImage is not valid.");
            }

            return size;
        }

        /// <summary>
        /// Get the number of bytes required to store a converted image with the given parameters.
        /// </summary>
        /// <param name="conversionParams">The desired conversion parameters.</param>
        /// <returns>The number of bytes required to store the converted image.</returns>
        /// <exception cref="System.ArgumentException">Thrown if the desired format is not supported.</exception>
        /// <exception cref="System.ArgumentOutOfRangeException">Thrown if the desired dimensions exceed the native
        /// image dimensions.</exception>
        /// <exception cref="System.InvalidOperationException">Thrown if the image is invalid.</exception>
        /// <seealso cref="FormatSupported"/>
        public int GetConvertedDataSize(XRCameraImageConversionParams conversionParams)
        {
            return GetConvertedDataSize(
                conversionParams.outputDimensions,
                conversionParams.outputFormat);
        }

        /// <summary>
        /// Convert the <c>XRCameraImage</c> to one of the supported formats using the specified
        /// <paramref name="conversionParams"/>.
        /// </summary>
        /// <param name="conversionParams">The parameters for the image conversion.</param>
        /// <param name="destinationBuffer">A pointer to memory to which to write the converted image.</param>
        /// <param name="bufferLength">The number of bytes pointed to by <paramref name="destinationBuffer"/>. Must be
        /// greater than or equal to the value returned by
        /// <see cref="GetConvertedDataSize(XRCameraImageConversionParams)"/>.</param>
        /// <exception cref="System.ArgumentException">Thrown if the <paramref name="bufferLength"/> is smaller than
        /// the data size required by the conversion.</exception>
        /// <exception cref="System.InvalidOperationException">Thrown if the conversion failed.</exception>
        /// <seealso cref="FormatSupported"/>
        public void Convert(XRCameraImageConversionParams conversionParams, IntPtr destinationBuffer, int bufferLength)
        {
            ValidateNativeHandleAndThrow();
            ValidateConversionParamsAndThrow(conversionParams);
            int requiredDataSize = GetConvertedDataSize(conversionParams);

            if (bufferLength < requiredDataSize)
            {
                throw new ArgumentException(string.Format(
                    "Conversion requires {0} bytes but only provided {1} bytes.", requiredDataSize, bufferLength),
                    "bufferLength");
            }

            if (!m_CameraSubsystem.TryConvert(m_NativeHandle, conversionParams, destinationBuffer, bufferLength))
            {
                throw new InvalidOperationException("Conversion failed.");
            }
        }

        /// <summary>
        /// Convert the <c>XRCameraImage</c> to one of the supported formats using the specified
        /// <paramref name="conversionParams"/>. The conversion is performed asynchronously. Use the returned
        /// <see cref="XRAsyncCameraImageConversion"/> to check for the status of the conversion, and retrieve the data
        /// when complete.
        /// </summary>
        /// <remarks>
        /// It is safe to <c>Dispose</c> the <c>XRCameraImage</c> before the asynchronous operation has completed.
        /// </remarks>
        /// <param name="conversionParams">The parameters to use for the conversion.</param>
        /// <returns>A <see cref="XRAsyncCameraImageConversion"/> which can be used to check the status of the
        /// conversion operation and get the resulting data.</returns>
        /// <seealso cref="FormatSupported"/>
        public XRAsyncCameraImageConversion ConvertAsync(XRCameraImageConversionParams conversionParams)
        {
            ValidateNativeHandleAndThrow();
            ValidateConversionParamsAndThrow(conversionParams);

            return new XRAsyncCameraImageConversion(m_CameraSubsystem, m_NativeHandle, conversionParams);
        }

        /// <summary>
        /// <para>Convert the <c>XRCameraImage</c> to one of the supported formats using the specified
        /// <paramref name="conversionParams"/>. The conversion is performed asynchronously, and
        /// <paramref name="onComplete"/> is invoked when the conversion is complete, whether successful or not.</para>
        /// <para>The <c>NativeArray</c> provided in the <paramref name="onComplete"/> delegate is only valid during
        /// the invocation and is disposed immediately upon return.</para>
        /// </summary>
        /// <param name="conversionParams">The parameters to use for the conversion.</param>
        /// <param name="onComplete">A delegate to invoke when the conversion operation completes. The delegate is
        /// always invoked.</param>
        /// <seealso cref="FormatSupported"/>
        public void ConvertAsync(
            XRCameraImageConversionParams conversionParams,
            Action<AsyncCameraImageConversionStatus, XRCameraImageConversionParams, NativeArray<byte>> onComplete)
        {
            ValidateNativeHandleAndThrow();
            ValidateConversionParamsAndThrow(conversionParams);

            var handle = GCHandle.Alloc(onComplete);
            var context = GCHandle.ToIntPtr(handle);
            m_CameraSubsystem.ConvertAsync(m_NativeHandle, conversionParams, s_OnAsyncConversionComplete, context);
        }

        /// <summary>
        /// Callback from native code for when the asychronous conversion is complete.
        /// </summary>
        /// <param name="status">The status of the conversion operation.</param>
        /// <param name="conversionParams">The parameters for the conversion.</param>
        /// <param name="dataPtr">The native pointer to the converted data.</param>
        /// <param name="dataLength">The memory size of the converted data.</param>
        /// <param name="context">The native context for the conversion operation.</param>
        [MonoPInvokeCallback(typeof(XRCameraSubsystem.OnImageRequestCompleteDelegate))]
        static unsafe void OnAsyncConversionComplete(
            AsyncCameraImageConversionStatus status, XRCameraImageConversionParams conversionParams, IntPtr dataPtr,
            int dataLength, IntPtr context)
        {
            var handle = GCHandle.FromIntPtr(context);
            var onComplete = (Action<AsyncCameraImageConversionStatus, XRCameraImageConversionParams, NativeArray<byte>>)handle.Target;

            if (onComplete != null)
            {
                var data = NativeArrayUnsafeUtility.ConvertExistingDataToNativeArray<byte>(
                    (void*)dataPtr, dataLength, Allocator.None);

#if ENABLE_UNITY_COLLECTIONS_CHECKS
                var safetyHandle = AtomicSafetyHandle.Create();
                NativeArrayUnsafeUtility.SetAtomicSafetyHandle(ref data, safetyHandle);
#endif

                onComplete(status, conversionParams, data);

#if ENABLE_UNITY_COLLECTIONS_CHECKS
                AtomicSafetyHandle.Release(safetyHandle);
#endif
            }

            handle.Free();
        }

        /// <summary>
        /// Ensure the image is valid.
        /// </summary>
        /// <exception cref="System.InvalidOperationException">Thrown if the image is invalid.</exception>
        void ValidateNativeHandleAndThrow()
        {
            if (!valid)
            {
                throw new InvalidOperationException("XRCameraImage is not valid.");
            }
        }

        /// <summary>
        /// Ensure the conversion parameters are valid.
        /// </summary>
        /// <param name="conversionParams">The conversion parameters to validate.</param>
        /// <exception cref="System.ArgumentOutOfRangeException">Thrown if the input image rect exceeds the actual
        /// image dimensions or if the output dimensions exceed the input dimensions.</exception>
        /// <exception cref="System.ArgumentException">Thrown if the texture format is not suppported</exception>
        /// <seealso cref="FormatSupported"/>
        void ValidateConversionParamsAndThrow(XRCameraImageConversionParams conversionParams)
        {
            if ((conversionParams.inputRect.x + conversionParams.inputRect.width > width) ||
                (conversionParams.inputRect.y + conversionParams.inputRect.height > height))
            {
                throw new ArgumentOutOfRangeException(
                    "conversionParams.inputRect",
                    "Input rect must be completely within the original image.");
            }

            if ((conversionParams.outputDimensions.x > conversionParams.inputRect.width) ||
                (conversionParams.outputDimensions.y > conversionParams.inputRect.height))
            {
                throw new ArgumentOutOfRangeException(string.Format(
                    "Output dimensions must be less than or equal to the inputRect's dimensions: ({0}x{1} > {2}x{3}).",
                    conversionParams.outputDimensions.x, conversionParams.outputDimensions.y,
                    conversionParams.inputRect.width, conversionParams.inputRect.height));
            }

            if (!FormatSupported(conversionParams.outputFormat))
            {
                throw new ArgumentException("TextureFormat not supported.", "conversionParams.format");
            }
        }

        /// <summary>
        /// Dispose native resources associated with this request, including the raw image data. Any
        /// <see cref="XRCameraImagePlane"/>s returned by <see cref="GetPlane"/> are invalidated immediately after
        /// calling <c>Dispose</c>.
        /// </summary>
        public void Dispose()
        {
            if (m_CameraSubsystem == null || m_NativeHandle == 0)
            {
                return;
            }

            m_CameraSubsystem.DisposeImage(m_NativeHandle);
            m_NativeHandle = 0;
            m_CameraSubsystem = null;

#if ENABLE_UNITY_COLLECTIONS_CHECKS
            AtomicSafetyHandle.Release(m_SafetyHandle);
#endif
        }

        public override int GetHashCode()
        {
            unchecked
            {
                var hash = width.GetHashCode();
                hash = hash * 486187739 + height.GetHashCode();
                hash = hash * 486187739 + planeCount.GetHashCode();
                hash = hash * 486187739 + m_NativeHandle.GetHashCode();
                hash = hash * 486187739 + ((int)format).GetHashCode();
                if (m_CameraSubsystem != null)
                {
                    hash = hash * 486187739 + m_CameraSubsystem.GetHashCode();
                }
                return hash;
            }
        }

        public override bool Equals(object obj)
        {
            return ((obj is XRCameraImage) && Equals((XRCameraImage)obj));
        }

        public bool Equals(XRCameraImage other)
        {
            return
                (width == other.width) &&
                (height == other.height) &&
                (planeCount == other.planeCount) &&
                (format == other.format) &&
                (m_NativeHandle == other.m_NativeHandle) &&
                (m_CameraSubsystem == other.m_CameraSubsystem);
        }

        public static bool operator ==(XRCameraImage lhs, XRCameraImage rhs)
        {
            return lhs.Equals(rhs);
        }

        public static bool operator !=(XRCameraImage lhs, XRCameraImage rhs)
        {
            return !lhs.Equals(rhs);
        }

        public override string ToString()
        {
            return string.Format(
                "(Width: {0}, Height: {1}, PlaneCount: {2}, Format: {3})",
                width, height, planeCount, format);
        }
    }
}