/// <summary>
/// Represents a packet for multimedia.
/// </summary>
- public abstract class MediaPacket : IDisposable
+ public abstract partial class MediaPacket : IDisposable
{
private IntPtr _handle = IntPtr.Zero;
/// Initializes a new instance of the MediaPacket class with the specified media format.
/// </summary>
/// <param name="format">The media format containing properties for the packet.</param>
- /// <exception cref="ArgumentNullException">format is null.</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="format"/> is null.</exception>
/// <exception cref="ArgumentException">
- /// <see cref="MediaFormatType"/> of the specified format is <see cref="MediaFormatType.Container"/>.</exception>
+ /// The <see cref="MediaFormatType"/> of the specified format is <see cref="MediaFormatType.Container"/>.
+ /// </exception>
/// <exception cref="InvalidOperationException">Operation failed.</exception>
internal MediaPacket(MediaFormat format)
{
/// <summary>
/// Gets or sets the PTS(Presentation Time Stamp) value of the current packet.
/// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <exception cref="InvalidOperationException">
- /// The MediaPacket is not writable state which means it being used by another module.</exception>
+ /// The MediaPacket is not in the writable state, which means it is being used by another module.
+ /// </exception>
public ulong Pts
{
get
/// <summary>
/// Gets or sets the DTS(Decoding Time Stamp) value of the current packet.
/// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <exception cref="InvalidOperationException">
- /// The MediaPacket is not in writable state which means it being used by another module.</exception>
+ /// The MediaPacket is not in the writable state, which means it is being used by another module.
+ /// </exception>
public ulong Dts
{
get
}
/// <summary>
- /// Gets a value indicating whether the packet is encoded type.
+ /// Gets a value indicating whether the packet is the encoded type.
/// </summary>
- /// <value>true if the packet is encoded type; otherwise, false.</value>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// <value>true if the packet is the encoded type; otherwise, false.</value>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
public bool IsEncoded
{
get
/// Gets the buffer of the packet.
/// </summary>
/// <value>The <see cref="MediaPacketBuffer"/> allocated to the packet.
- /// This property will return null if the packet is raw video format.</value>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// This property will return null if the packet is in the raw video format.</value>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <seealso cref="IsEncoded"/>
/// <seealso cref="VideoPlanes"/>
public MediaPacketBuffer Buffer
/// <summary>
/// Gets or sets a length of data written in the <see cref="Buffer"/>.
/// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <exception cref="ArgumentOutOfRangeException">
/// The value specified for this property is less than zero or greater than <see cref="MediaPacketBuffer.Length"/>.</exception>
/// <exception cref="InvalidOperationException">
/// The MediaPacket has <see cref="VideoPlanes"/> instead of <see cref="Buffer"/>.\n
/// -or-\n
- /// The MediaPacket is not in writable state which means it being used by another module.
+ /// The MediaPacket is not in the writable state, which means it is being used by another module.
/// </exception>
public int BufferWrittenLength
{
/// Gets the video planes of the packet.
/// </summary>
/// <value>The <see cref="MediaPacketVideoPlane"/>s allocated to the packet.
- /// This property will return null if the packet is not raw video format.</value>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// This property will return null if the packet is not in the raw video format.</value>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <seealso cref="IsEncoded"/>
/// <seealso cref="Buffer"/>
public MediaPacketVideoPlane[] VideoPlanes
/// <summary>
/// Gets or sets the buffer flags of the packet.
/// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed.</exception>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <exception cref="InvalidOperationException">
- /// The MediaPacket is not in writable state which means it being used by another module.
- /// </exception>
+ /// The MediaPacket is not in the writable state, which means it is being used by another module.
+ /// </exception>
public MediaPacketBufferFlags BufferFlags
{
get
/// Releases all resources used by the <see cref="MediaPacket"/> object.
/// </summary>
/// <exception cref="InvalidOperationException">
- /// The MediaPacket can not be disposed which means it being used by another module.
+ /// The MediaPacket can not be disposed, which means it is being used by another module.
/// </exception>
public void Dispose()
{
}
/// <summary>
- /// Validate the current object has not been disposed of.
+ /// Validates the current object has not been disposed of.
/// </summary>
/// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
private void ValidateNotDisposed()
}
/// <summary>
- /// Validate the current object is not locked.
- /// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
- /// <exception cref="InvalidOperationException">The MediaPacket is in use by another module.</exception>
- private void ValidateNotLocked()
- {
- ValidateNotDisposed();
-
- if (_lock.IsLocked)
- {
- throw new InvalidOperationException("Can't perform any writing operation." +
- "The packet is in use, internally.");
- }
- }
- /// <summary>
/// Ensures whether the packet is writable.
/// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket already has been disposed of.</exception>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
/// <exception cref="InvalidOperationException">The MediaPacket is being used by another module.</exception>
internal void EnsureWritableState()
{
/// <summary>
/// Ensures whether the packet is readable.
/// </summary>
- /// <exception cref="ObjectDisposedException">The MediaPacket already has been disposed of.</exception>
+ /// <exception cref="ObjectDisposedException">The MediaPacket has already been disposed of.</exception>
internal void EnsureReadableState()
{
ValidateNotDisposed();
}
/// <summary>
- /// Gets a value indicating whether the packet is raw video format.
+ /// Gets a value indicating whether the packet is in the raw video format.
/// </summary>
- /// <value>true if the packet is raw video format; otherwise, false.</value>
+ /// <value>true if the packet is in the raw video format; otherwise, false.</value>
private bool IsVideoPlaneSupported
{
get
return new MediaPacketBuffer(this, dataHandle, size);
}
- #region Lock operations
- private readonly LockState _lock = new LockState();
-
- /// <summary>
- /// Provides a thread-safe lock state controller.
- /// </summary>
- private sealed class LockState
- {
- const int LOCKED = 1;
- const int UNLOCKED = 0;
-
- private int _locked = UNLOCKED;
-
- internal void SetLock()
- {
- if (Interlocked.CompareExchange(ref _locked, LOCKED, UNLOCKED) == LOCKED)
- {
- throw new InvalidOperationException("The packet is already locked.");
- }
- }
-
- internal void SetUnlock()
- {
- if (Interlocked.CompareExchange(ref _locked, UNLOCKED, LOCKED) == UNLOCKED)
- {
- Debug.Fail("The packet to unlock is not locked. " +
- "There must be an error somewhere that a lock isn't disposed correctly.");
- }
- }
-
- internal bool IsLocked
- {
- get
- {
- return Interlocked.CompareExchange(ref _locked, 0, 0) == LOCKED;
- }
- }
- }
-
- /// <summary>
- /// Provides a thread-safe lock controller.
- /// </summary>
- /// <example>
- /// using (var lock = BaseMediaPacket.Lock(mediaPacket))
- /// {
- /// ....
- /// }
- /// </example>
- internal sealed class Lock : IDisposable
- {
- private readonly MediaPacket _packet;
- private readonly GCHandle _gcHandle;
- private int _lockCount;
-
- internal static Lock Get(MediaPacket packet)
- {
- Debug.Assert(packet != null);
-
- lock (packet)
- {
- Lock lck = FromHandle(packet._handle);
-
- if (lck == null)
- {
- lck = new Lock(packet);
- }
-
- lck._lockCount++;
-
- return lck;
- }
- }
-
- private Lock(MediaPacket packet)
- {
- Debug.Assert(packet != null, "The packet is null!");
-
- packet.ValidateNotDisposed();
-
- _packet = packet;
-
- _packet._lock.SetLock();
-
- _gcHandle = GCHandle.Alloc(this);
-
- SetExtra(GCHandle.ToIntPtr(_gcHandle));
- }
-
- internal static Lock FromHandle(IntPtr handle)
- {
- Debug.Assert(handle != IntPtr.Zero);
-
- IntPtr extra = GetExtra(handle);
-
- if (extra == IntPtr.Zero)
- {
- return null;
- }
-
- return (Lock)GCHandle.FromIntPtr(extra).Target;
- }
-
- private void SetExtra(IntPtr ptr)
- {
- int ret = Interop.MediaPacket.SetExtra(_packet._handle, ptr);
-
- MultimediaDebug.AssertNoError(ret);
- }
-
- private static IntPtr GetExtra(IntPtr handle)
- {
- IntPtr value;
-
- int ret = Interop.MediaPacket.GetExtra(handle, out value);
-
- MultimediaDebug.AssertNoError(ret);
-
- return value;
- }
-
- internal IntPtr GetHandle()
- {
- return _packet.GetHandle();
- }
-
- internal MediaPacket MediaPacket
- {
- get
- {
- return _packet;
- }
- }
-
- private bool _isDisposed = false;
-
- public void Dispose()
- {
- if (!_isDisposed)
- {
- lock (_packet)
- {
- _lockCount--;
-
- if (_lockCount == 0)
- {
- SetExtra(IntPtr.Zero);
-
- if (_gcHandle.IsAllocated)
- {
- _gcHandle.Free();
- }
-
- //We can assure that at this point '_packet' is always locked by this lock.
- _packet._lock.SetUnlock();
- }
- }
-
- _isDisposed = true;
- }
- }
- }
- #endregion
-
/// <summary>
/// Creates an object of the MediaPacket with the specified <see cref="MediaFormat"/>.
/// </summary>