[MediaTool] Add audio channel mapping APIs for PCM format (#1000)
[platform/core/csapi/tizenfx.git] / src / Tizen.Multimedia / MediaTool / MediaPacket.cs
index 64e6d59..43ba0c4 100644 (file)
@@ -16,9 +16,9 @@
 
 using System;
 using System.Diagnostics;
-using System.Runtime.InteropServices;
-using System.Threading;
 using Tizen.Internals.Errors;
+using Native = Tizen.Multimedia.Interop.MediaPacket;
+using NativeFormat = Tizen.Multimedia.Interop.MediaFormat;
 
 namespace Tizen.Multimedia
 {
@@ -45,12 +45,8 @@ namespace Tizen.Multimedia
                 throw new ArgumentNullException(nameof(format));
             }
 
-            if (format.Type == MediaFormatType.Container)
-            {
-                throw new ArgumentException("Container format can't be used to create a new packet.");
-            }
-
             Initialize(format);
+
             _format = format;
             _buffer = new Lazy<IMediaBuffer>(GetBuffer);
         }
@@ -63,8 +59,7 @@ namespace Tizen.Multimedia
         {
             _handle = handle;
 
-            IntPtr formatHandle;
-            int ret = Interop.MediaPacket.GetFormat(handle, out formatHandle);
+            int ret = Native.GetFormat(handle, out IntPtr formatHandle);
 
             MultimediaDebug.AssertNoError(ret);
 
@@ -77,10 +72,13 @@ namespace Tizen.Multimedia
             }
             finally
             {
-                Interop.MediaFormat.Unref(formatHandle);
+                NativeFormat.Unref(formatHandle);
             }
         }
 
+        /// <summary>
+        /// Finalizes an instance of the MediaPacket class.
+        /// </summary>
         ~MediaPacket()
         {
             Dispose(false);
@@ -95,7 +93,8 @@ namespace Tizen.Multimedia
         {
             if (format.Type == MediaFormatType.Container)
             {
-                throw new ArgumentException("Creating a packet for container is not supported.");
+                throw new ArgumentException("Container format can't be used to create a new packet.",
+                    nameof(format));
             }
 
             IntPtr formatHandle = IntPtr.Zero;
@@ -104,7 +103,7 @@ namespace Tizen.Multimedia
             {
                 formatHandle = format.AsNativeHandle();
 
-                int ret = Interop.MediaPacket.Create(formatHandle, IntPtr.Zero, IntPtr.Zero, out _handle);
+                int ret = Native.Create(formatHandle, IntPtr.Zero, IntPtr.Zero, out _handle);
                 MultimediaDebug.AssertNoError(ret);
 
                 Debug.Assert(_handle != IntPtr.Zero, "Created handle must not be null");
@@ -115,7 +114,7 @@ namespace Tizen.Multimedia
             {
                 if (_handle != IntPtr.Zero)
                 {
-                    Interop.MediaPacket.Destroy(_handle);
+                    Native.Destroy(_handle);
                     _handle = IntPtr.Zero;
                 }
 
@@ -125,7 +124,7 @@ namespace Tizen.Multimedia
             {
                 if (formatHandle != IntPtr.Zero)
                 {
-                    Interop.MediaFormat.Unref(formatHandle);
+                    NativeFormat.Unref(formatHandle);
                 }
             }
         }
@@ -136,7 +135,7 @@ namespace Tizen.Multimedia
         /// <exception cref="InvalidOperationException">Operation failed.</exception>
         private void Alloc()
         {
-            ErrorCode ret = (ErrorCode)Interop.MediaPacket.Alloc(_handle);
+            ErrorCode ret = (ErrorCode)Native.Alloc(_handle);
             if (ret == ErrorCode.None)
             {
                 return;
@@ -160,6 +159,7 @@ namespace Tizen.Multimedia
         /// <summary>
         /// Gets the media format of the current packet.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         public MediaFormat Format
         {
             get
@@ -176,14 +176,14 @@ namespace Tizen.Multimedia
         /// <exception cref="InvalidOperationException">
         ///     The MediaPacket is not in the writable state, which means it is being used by another module.
         /// </exception>
+        /// <since_tizen> 3 </since_tizen>
         public ulong Pts
         {
             get
             {
                 ValidateNotDisposed();
 
-                ulong value = 0;
-                int ret = Interop.MediaPacket.GetPts(_handle, out value);
+                int ret = Native.GetPts(_handle, out var value);
 
                 MultimediaDebug.AssertNoError(ret);
 
@@ -194,7 +194,7 @@ namespace Tizen.Multimedia
                 ValidateNotDisposed();
                 ValidateNotLocked();
 
-                int ret = Interop.MediaPacket.SetPts(_handle, value);
+                int ret = Native.SetPts(_handle, value);
 
                 MultimediaDebug.AssertNoError(ret);
             }
@@ -207,15 +207,14 @@ namespace Tizen.Multimedia
         /// <exception cref="InvalidOperationException">
         ///     The MediaPacket is not in the writable state, which means it is being used by another module.
         /// </exception>
+        /// <since_tizen> 3 </since_tizen>
         public ulong Dts
         {
             get
             {
                 ValidateNotDisposed();
 
-                ulong value = 0;
-                int ret = Interop.MediaPacket.GetDts(_handle, out value);
-
+                int ret = Native.GetDts(_handle, out var value);
                 MultimediaDebug.AssertNoError(ret);
 
                 return value;
@@ -225,8 +224,36 @@ namespace Tizen.Multimedia
                 ValidateNotDisposed();
                 ValidateNotLocked();
 
-                int ret = Interop.MediaPacket.SetDts(_handle, value);
+                int ret = Native.SetDts(_handle, value);
+                MultimediaDebug.AssertNoError(ret);
+            }
+        }
+
+        /// <summary>
+        /// Gets or sets the duration value of the current packet.
+        /// </summary>
+        /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
+        /// <exception cref="InvalidOperationException">
+        ///     The MediaPacket is not in the writable state, which means it is being used by another module.
+        /// </exception>
+        /// <since_tizen> 6 </since_tizen>
+        public ulong Duration
+        {
+            get
+            {
+                ValidateNotDisposed();
 
+                int ret = Native.GetDuration(_handle, out var value);
+                MultimediaDebug.AssertNoError(ret);
+
+                return value;
+            }
+            set
+            {
+                ValidateNotDisposed();
+                ValidateNotLocked();
+
+                int ret = Native.SetDuration(_handle, value);
                 MultimediaDebug.AssertNoError(ret);
             }
         }
@@ -236,21 +263,97 @@ namespace Tizen.Multimedia
         /// </summary>
         /// <value>true if the packet is the encoded type; otherwise, false.</value>
         /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
+        /// <since_tizen> 3 </since_tizen>
         public bool IsEncoded
         {
             get
             {
                 ValidateNotDisposed();
 
-                bool value = false;
-                int ret = Interop.MediaPacket.IsEncoded(_handle, out value);
-
+                int ret = Native.IsEncoded(_handle, out var value);
                 MultimediaDebug.AssertNoError(ret);
 
                 return value;
             }
         }
 
+        /// <summary>
+        /// Gets or sets the rotation value of the current packet.
+        /// </summary>
+        /// <exception cref="ArgumentException">The specified value to set is invalid.</exception>
+        /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
+        /// <exception cref="InvalidOperationException">
+        ///     The MediaPacket is not in the writable state, which means it is being used by another module.
+        /// </exception>
+        /// <since_tizen> 5 </since_tizen>
+        public Rotation Rotation
+        {
+            get
+            {
+                ValidateNotDisposed();
+
+                int ret = Native.GetRotation(_handle, out var value);
+                MultimediaDebug.AssertNoError(ret);
+
+                var rotation = value < RotationFlip.HorizontalFlip ? (Rotation)value : Rotation.Rotate0;
+
+                return rotation;
+            }
+            set
+            {
+                ValidateNotDisposed();
+                ValidateNotLocked();
+                ValidationUtil.ValidateEnum(typeof(Rotation), value, nameof(value));
+
+                int ret = Native.SetRotation(_handle, (RotationFlip)value);
+                MultimediaDebug.AssertNoError(ret);
+            }
+        }
+
+        /// <summary>
+        /// Gets or sets the flip value of the current packet.
+        /// </summary>
+        /// <remarks>
+        /// <see cref="Flips.None"/> will be ignored in set case. It's not supported in Native FW.
+        /// </remarks>
+        /// <exception cref="ArgumentException">The specified value to set is invalid.</exception>
+        /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
+        /// <exception cref="InvalidOperationException">
+        ///     The MediaPacket is not in the writable state, which means it is being used by another module.
+        /// </exception>
+        /// <since_tizen> 5 </since_tizen>
+        public Flips Flip
+        {
+            get
+            {
+                ValidateNotDisposed();
+
+                int ret = Native.GetRotation(_handle, out var value);
+                MultimediaDebug.AssertNoError(ret);
+
+                var flip = (value < RotationFlip.HorizontalFlip) ? Flips.None :
+                    (value == RotationFlip.HorizontalFlip ? Flips.Horizontal : Flips.Vertical);
+
+                return flip;
+            }
+            set
+            {
+                ValidateNotDisposed();
+                ValidateNotLocked();
+                ValidationUtil.ValidateEnum(typeof(Flips), value, nameof(value));
+
+                if (value == Flips.None)
+                {
+                    return;
+                }
+
+                var flip = value == Flips.Horizontal ? RotationFlip.HorizontalFlip : RotationFlip.VerticalFlip;
+
+                int ret = Native.SetRotation(_handle, flip);
+                MultimediaDebug.AssertNoError(ret);
+            }
+        }
+
         private Lazy<IMediaBuffer> _buffer;
 
         /// <summary>
@@ -263,6 +366,7 @@ namespace Tizen.Multimedia
         /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
         /// <seealso cref="IsEncoded"/>
         /// <seealso cref="VideoPlanes"/>
+        /// <since_tizen> 3 </since_tizen>
         public IMediaBuffer Buffer
         {
             get
@@ -285,18 +389,18 @@ namespace Tizen.Multimedia
         /// <exception cref="ArgumentOutOfRangeException">
         ///     The value specified for this property is less than zero or greater than the length of the <see cref="Buffer"/>.</exception>
         /// <exception cref="InvalidOperationException">
-        ///     The MediaPacket has <see cref="VideoPlanes"/> instead of <see cref="Buffer"/>.\n
-        ///     -or-\n
+        ///     The MediaPacket has <see cref="VideoPlanes"/> instead of <see cref="Buffer"/>.<br/>
+        ///     -or-<br/>
         ///     The MediaPacket is not in the writable state, which means it is being used by another module.
         ///     </exception>
+        /// <since_tizen> 3 </since_tizen>
         public int BufferWrittenLength
         {
             get
             {
                 ValidateNotDisposed();
 
-                ulong value = 0;
-                int ret = Interop.MediaPacket.GetBufferSize(_handle, out value);
+                int ret = Native.GetBufferSize(_handle, out var value);
                 MultimediaDebug.AssertNoError(ret);
 
                 Debug.Assert(value < int.MaxValue);
@@ -318,10 +422,11 @@ namespace Tizen.Multimedia
 
                 if (value < 0 || value >= Buffer.Length)
                 {
-                    throw new ArgumentOutOfRangeException("value must be less than Buffer.Size.");
+                    throw new ArgumentOutOfRangeException(nameof(value), value,
+                        "value must be less than Buffer.Size.");
                 }
 
-                int ret = Interop.MediaPacket.SetBufferSize(_handle, (ulong)value);
+                int ret = Native.SetBufferSize(_handle, (ulong)value);
                 MultimediaDebug.AssertNoError(ret);
             }
         }
@@ -336,6 +441,7 @@ namespace Tizen.Multimedia
         /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
         /// <seealso cref="IsEncoded"/>
         /// <seealso cref="Buffer"/>
+        /// <since_tizen> 3 </since_tizen>
         public MediaPacketVideoPlane[] VideoPlanes
         {
             get
@@ -363,13 +469,14 @@ namespace Tizen.Multimedia
         /// <exception cref="InvalidOperationException">
         ///     The MediaPacket is not in the writable state, which means it is being used by another module.
         /// </exception>
+        /// <since_tizen> 3 </since_tizen>
         public MediaPacketBufferFlags BufferFlags
         {
             get
             {
                 ValidateNotDisposed();
 
-                int ret = Interop.MediaPacket.GetBufferFlags(_handle, out var value);
+                int ret = Native.GetBufferFlags(_handle, out var value);
 
                 MultimediaDebug.AssertNoError(ret);
 
@@ -381,31 +488,33 @@ namespace Tizen.Multimedia
                 ValidateNotDisposed();
                 ValidateNotLocked();
 
-                int ret = Interop.MediaPacket.ResetBufferFlags(_handle);
+                int ret = Native.ResetBufferFlags(_handle);
 
                 MultimediaDebug.AssertNoError(ret);
 
-                ret = Interop.MediaPacket.SetBufferFlags(_handle, (int)value);
+                ret = Native.SetBufferFlags(_handle, (int)value);
 
                 MultimediaDebug.AssertNoError(ret);
             }
         }
 
+        #region Dispose support
         /// <summary>
         /// Gets a value indicating whether the packet has been disposed of.
         /// </summary>
         /// <value>true if the packet has been disposed of; otherwise, false.</value>
+        /// <since_tizen> 3 </since_tizen>
         public bool IsDisposed => _isDisposed;
 
         private bool _isDisposed = false;
 
-
         /// <summary>
         /// Releases all resources used by the <see cref="MediaPacket"/> object.
         /// </summary>
         /// <exception cref="InvalidOperationException">
         ///     The MediaPacket can not be disposed, which means it is being used by another module.
         /// </exception>
+        /// <since_tizen> 3 </since_tizen>
         public void Dispose()
         {
             if (_isDisposed)
@@ -424,6 +533,7 @@ namespace Tizen.Multimedia
         /// <param name="disposing">
         /// true to release both managed and unmanaged resources; false to release only unmanaged resources.
         /// </param>
+        /// <since_tizen> 3 </since_tizen>
         protected virtual void Dispose(bool disposing)
         {
             if (_isDisposed)
@@ -433,22 +543,13 @@ namespace Tizen.Multimedia
 
             if (_handle != IntPtr.Zero)
             {
-                Interop.MediaPacket.Destroy(_handle);
+                Native.Destroy(_handle);
                 _handle = IntPtr.Zero;
             }
 
             _isDisposed = true;
         }
 
-        internal IntPtr GetHandle()
-        {
-            ValidateNotDisposed();
-
-            Debug.Assert(_handle != IntPtr.Zero, "The handle is invalid!");
-
-            return _handle;
-        }
-
         /// <summary>
         /// Validates the current object has not been disposed of.
         /// </summary>
@@ -460,6 +561,16 @@ namespace Tizen.Multimedia
                 throw new ObjectDisposedException("This packet has already been disposed of.");
             }
         }
+        #endregion
+
+        internal IntPtr GetHandle()
+        {
+            ValidateNotDisposed();
+
+            Debug.Assert(_handle != IntPtr.Zero, "The handle is invalid!");
+
+            return _handle;
+        }
 
         /// <summary>
         /// Ensures whether the packet is writable.
@@ -485,13 +596,7 @@ namespace Tizen.Multimedia
         /// Gets a value indicating whether the packet is in the raw video format.
         /// </summary>
         /// <value>true if the packet is in the raw video format; otherwise, false.</value>
-        private bool IsVideoPlaneSupported
-        {
-            get
-            {
-                return !IsEncoded && Format.Type == MediaFormatType.Video;
-            }
-        }
+        private bool IsVideoPlaneSupported => !IsEncoded && Format.Type == MediaFormatType.Video;
 
         /// <summary>
         /// Retrieves video planes of the current packet.
@@ -501,8 +606,7 @@ namespace Tizen.Multimedia
         {
             Debug.Assert(_handle != IntPtr.Zero, "The handle is invalid!");
 
-            uint numberOfPlanes = 0;
-            int ret = Interop.MediaPacket.GetNumberOfVideoPlanes(_handle, out numberOfPlanes);
+            int ret = Native.GetNumberOfVideoPlanes(_handle, out var numberOfPlanes);
 
             MultimediaDebug.AssertNoError(ret);
 
@@ -526,15 +630,12 @@ namespace Tizen.Multimedia
 
             Debug.Assert(_handle != IntPtr.Zero, "The handle is invalid!");
 
-            IntPtr dataHandle;
-
-            int ret = Interop.MediaPacket.GetBufferData(_handle, out dataHandle);
+            int ret = Native.GetBufferData(_handle, out var dataHandle);
             MultimediaDebug.AssertNoError(ret);
 
             Debug.Assert(dataHandle != IntPtr.Zero, "Data handle is invalid!");
 
-            int size = 0;
-            ret = Interop.MediaPacket.GetAllocatedBufferSize(_handle, out size);
+            ret = Native.GetAllocatedBufferSize(_handle, out var size);
             MultimediaDebug.AssertNoError(ret);
 
             Debug.Assert(size >= 0, "size must not be negative!");
@@ -547,6 +648,7 @@ namespace Tizen.Multimedia
         /// </summary>
         /// <param name="format">The media format for the new packet.</param>
         /// <returns>A new MediaPacket object.</returns>
+        /// <since_tizen> 3 </since_tizen>
         public static MediaPacket Create(MediaFormat format)
         {
             return new SimpleMediaPacket(format);