ImageAnimator.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.Drawing.Imaging;
using System.Threading;

namespace System.Drawing;

/// <summary>
///     Animates one or more images that have time-based frames.
///     See the ImageInfo.cs file for the helper nested ImageInfo class.
///
///     A common pattern for using this class is as follows (See PictureBox control):
///     1. The winform app (user's code) calls ImageAnimator.Animate() from the main thread.
///     2. Animate() spawns the animating (worker) thread in the background, which will update the image
///        frames and raise the OnFrameChanged event, which handler will be executed in the main thread.
///     3. The main thread triggers a paint event (Invalidate()) from the OnFrameChanged handler.
///     4. From the OnPaint event, the main thread calls ImageAnimator.UpdateFrames() and then paints the
///        image (updated frame).
///     5. The main thread calls ImageAnimator.StopAnimate() when needed. This does not kill the worker thread.
///
///     Comment on locking the image ref:
///     We need to synchronize access to sections of code that modify the image(s), but we don't want to block
///     animation of one image when modifying a different one; for this, we use the image ref for locking the
///     critical section (lock(image)).
///
///     This class is safe for multi-threading but Image is not; multithreaded applications must use a critical
///     section lock using the image ref the image access is not from the same thread that executes ImageAnimator
///     code.  If the user code locks on the image ref forever a deadlock will happen preventing the animation
///     from occurring.
/// </summary>
public sealed partial class ImageAnimator
{
    // We use a timer to apply an animation tick speeds of something a bit shorter than 50ms
    // such that if the requested frame rate is about 20 frames per second, we will rarely skip
    // a frame entirely. Sometimes we'll show a few more frames if available, but we will never
    // show more than 25 frames a second and that's OK.
    internal const int AnimationDelayMS = 40;

    /// <summary>
    ///  A list of images to be animated.
    /// </summary>
    private static List<ImageInfo>? s_imageInfoList;

    /// <summary>
    ///  A variable to flag when an image or images need to be updated due to the selection of a new frame
    ///  in an image.  We don't need to synchronize access to this variable, in the case it is true we don't
    ///  do anything, otherwise the worse case is where a thread attempts to update the image's frame after
    ///  another one did which is harmless.
    /// </summary>
    private static bool s_anyFrameDirty;

    /// <summary>
    ///  The thread used for animating the images.
    /// </summary>
    private static Thread? s_animationThread;

    /// <summary>
    ///  Lock that allows either concurrent read-access to the images list for multiple threads, or write-
    ///  access to it for a single thread.  Observe that synchronization access to image objects are done
    ///  with critical sections (lock).
    /// </summary>
    private static readonly ReaderWriterLock s_rwImgListLock = new();

    /// <summary>
    ///  Flag to avoid a deadlock when waiting on a write-lock and an attempt to acquire a read-lock is
    ///  made in the same thread. If RWLock is currently owned by another thread, the current thread is going to wait on an
    ///  event using CoWaitForMultipleHandles while pumps message.
    ///
    ///  The comment above refers to the COM STA message pump, not to be confused with the UI message pump.
    ///  However, the effect is the same, the COM message pump will pump messages and dispatch them to the
    ///  window while waiting on the writer lock; this has the potential of creating a re-entrancy situation
    ///  that if during the message processing a wait on a reader lock is originated the thread will be block
    ///  on itself.
    ///
    ///  While processing STA message, the thread may call back into managed code. We do this because
    ///  we can not block finalizer thread.  Finalizer thread may need to release STA objects on this thread. If
    ///  the current thread does not pump message, finalizer thread is blocked, and AD  unload is blocked while
    ///  waiting for finalizer thread. RWLock is a fair lock. If a thread waits for a writer lock, then it needs
    ///  a reader lock while pumping message, the thread is blocked forever.
    ///  This TLS variable is used to flag the above situation and avoid the deadlock, it is ThreadStatic so each
    ///  thread calling into ImageAnimator is guarded against this problem.
    /// </summary>
    [ThreadStatic]
    private static int t_threadWriterLockWaitCount;

    /// <summary>
    ///  Prevent instantiation of this class.
    /// </summary>
    private ImageAnimator()
    {
    }

    /// <summary>
    ///  Advances the frame in the specified image. The new frame is drawn the next time the image is rendered.
    /// </summary>
    public static void UpdateFrames(Image? image)
    {
        if (image is null || s_imageInfoList is null)
        {
            return;
        }

        if (t_threadWriterLockWaitCount > 0)
        {
            // Cannot acquire reader lock - frame update will be missed.
            return;
        }

        // If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on
        // the writer lock is incremented. It already has a reader lock, the locks ref count will be incremented
        // w/o placing the request at the end of the reader queue.

        s_rwImgListLock.AcquireReaderLock(Timeout.Infinite);

        try
        {
            bool foundDirty = false;
            bool foundImage = false;

            foreach (ImageInfo imageInfo in s_imageInfoList)
            {
                if (imageInfo.Image == image)
                {
                    if (imageInfo.FrameDirty)
                    {
                        // See comment in the class header about locking the image ref.
                        lock (imageInfo.Image)
                        {
                            imageInfo.UpdateFrame();
                        }
                    }

                    foundImage = true;
                }
                else if (imageInfo.FrameDirty)
                {
                    foundDirty = true;
                }

                if (foundDirty && foundImage)
                {
                    break;
                }
            }

            s_anyFrameDirty = foundDirty;
        }
        finally
        {
            s_rwImgListLock.ReleaseReaderLock();
        }
    }

    /// <summary>
    ///  Advances the frame in all images currently being animated. The new frame is drawn the next time the image is rendered.
    /// </summary>
    public static void UpdateFrames()
    {
        if (!s_anyFrameDirty || s_imageInfoList is null)
        {
            return;
        }

        if (t_threadWriterLockWaitCount > 0)
        {
            // Cannot acquire reader lock at this time, frames update will be missed.
            return;
        }

        s_rwImgListLock.AcquireReaderLock(Timeout.Infinite);

        try
        {
            foreach (ImageInfo imageInfo in s_imageInfoList)
            {
                // See comment in the class header about locking the image ref.
                lock (imageInfo.Image)
                {
                    imageInfo.UpdateFrame();
                }
            }

            s_anyFrameDirty = false;
        }
        finally
        {
            s_rwImgListLock.ReleaseReaderLock();
        }
    }

    /// <summary>
    ///  Adds an image to the image manager.  If the image does not support animation this method does nothing.
    ///  This method creates the image list and spawns the animation thread the first time it is called.
    /// </summary>
    public static void Animate(Image image, EventHandler onFrameChangedHandler)
    {
        if (image is null)
        {
            return;
        }

        ImageInfo? imageInfo = null;

        // See comment in the class header about locking the image ref.
        lock (image)
        {
            // could we avoid creating an ImageInfo object if FrameCount == 1 ?
            imageInfo = new ImageInfo(image);
        }

        // If the image is already animating, stop animating it
        StopAnimate(image, onFrameChangedHandler);

        // Acquire a writer lock to modify the image info list.  If the thread has a reader lock we need to upgrade
        // it to a writer lock; acquiring a reader lock in this case would block the thread on itself.
        // If the thread already has a writer lock its ref count will be incremented w/o placing the request in the
        // writer queue.  See ReaderWriterLock.AcquireWriterLock method in the MSDN.

        bool readerLockHeld = s_rwImgListLock.IsReaderLockHeld;
        LockCookie lockDowngradeCookie = default;

        t_threadWriterLockWaitCount++;

        try
        {
            if (readerLockHeld)
            {
                lockDowngradeCookie = s_rwImgListLock.UpgradeToWriterLock(Timeout.Infinite);
            }
            else
            {
                s_rwImgListLock.AcquireWriterLock(Timeout.Infinite);
            }
        }
        finally
        {
            t_threadWriterLockWaitCount--;
            Debug.Assert(t_threadWriterLockWaitCount >= 0, "threadWriterLockWaitCount less than zero.");
        }

        try
        {
            if (!imageInfo.Animated)
            {
                return;
            }

            // Construct the image array
            s_imageInfoList ??= [];

            // Add the new image
            imageInfo.FrameChangedHandler = onFrameChangedHandler;
            s_imageInfoList.Add(imageInfo);

            // Construct a new timer thread if we haven't already
            if (s_animationThread is null)
            {
                s_animationThread = new Thread(new ThreadStart(AnimateImages))
                {
                    Name = nameof(ImageAnimator),
                    IsBackground = true
                };

                s_animationThread.Start();
            }
        }
        finally
        {
            if (readerLockHeld)
            {
                s_rwImgListLock.DowngradeFromWriterLock(ref lockDowngradeCookie);
            }
            else
            {
                s_rwImgListLock.ReleaseWriterLock();
            }
        }
    }

    /// <summary>
    ///  Whether or not the image has multiple time-based frames.
    /// </summary>
    public static bool CanAnimate([NotNullWhen(true)] Image? image)
    {
        if (image is null)
        {
            return false;
        }

        // See comment in the class header about locking the image ref.
        lock (image)
        {
            Guid[] dimensions = image.FrameDimensionsList;

            foreach (Guid guid in dimensions)
            {
                FrameDimension dimension = new(guid);
                if (dimension.Equals(FrameDimension.Time))
                {
                    return image.GetFrameCount(FrameDimension.Time) > 1;
                }
            }
        }

        return false;
    }

    /// <summary>
    ///  Removes an image from the image manager so it is no longer animated.
    /// </summary>
    public static void StopAnimate(Image image, EventHandler onFrameChangedHandler)
    {
        // Make sure we have a list of images
        if (image is null || s_imageInfoList is null)
        {
            return;
        }

        // Acquire a writer lock to modify the image info list - See comments on Animate() about this locking.

        bool readerLockHeld = s_rwImgListLock.IsReaderLockHeld;
        LockCookie lockDowngradeCookie = default;

        t_threadWriterLockWaitCount++;

        try
        {
            if (readerLockHeld)
            {
                lockDowngradeCookie = s_rwImgListLock.UpgradeToWriterLock(Timeout.Infinite);
            }
            else
            {
                s_rwImgListLock.AcquireWriterLock(Timeout.Infinite);
            }
        }
        finally
        {
            t_threadWriterLockWaitCount--;
            Debug.Assert(t_threadWriterLockWaitCount >= 0, "threadWriterLockWaitCount less than zero.");
        }

        try
        {
            // Find the corresponding reference and remove it
            for (int i = 0; i < s_imageInfoList.Count; i++)
            {
                ImageInfo imageInfo = s_imageInfoList[i];

                if (image == imageInfo.Image)
                {
                    if (onFrameChangedHandler == imageInfo.FrameChangedHandler
                        || (onFrameChangedHandler is not null && onFrameChangedHandler.Equals(imageInfo.FrameChangedHandler)))
                    {
                        s_imageInfoList.Remove(imageInfo);
                    }

                    break;
                }
            }
        }
        finally
        {
            if (readerLockHeld)
            {
                s_rwImgListLock.DowngradeFromWriterLock(ref lockDowngradeCookie);
            }
            else
            {
                s_rwImgListLock.ReleaseWriterLock();
            }
        }
    }

    /// <summary>
    ///  Worker thread procedure which implements the main animation loop.
    ///
    ///  NOTE: This is the ONLY code the worker thread executes, keeping it in one method helps better understand
    ///  any synchronization issues.
    ///
    ///  WARNING: Also, this is the only place where ImageInfo objects (not the contained image object) are modified,
    ///  so no access synchronization is required to modify them.
    /// </summary>
    private static void AnimateImages()
    {
        Debug.Assert(s_imageInfoList is not null, "Null images list");

        Stopwatch stopwatch = Stopwatch.StartNew();

        while (true)
        {
            Thread.Sleep(AnimationDelayMS);

            // Because Thread.Sleep is not accurate, capture how much time has actually elapsed during the animation
            long timeElapsed = stopwatch.ElapsedMilliseconds;
            stopwatch.Restart();

            // Acquire reader-lock to access imageInfoList, elements in the list can be modified w/o needing a writer-lock.
            // Observe that we don't need to check if the thread is waiting or a writer lock here since the thread this
            // method runs in never acquires a writer lock.
            s_rwImgListLock.AcquireReaderLock(Timeout.Infinite);
            try
            {
                for (int i = 0; i < s_imageInfoList.Count; i++)
                {
                    ImageInfo imageInfo = s_imageInfoList[i];

                    if (imageInfo.Animated)
                    {
                        imageInfo.AdvanceAnimationBy(timeElapsed);

                        if (imageInfo.FrameDirty)
                        {
                            s_anyFrameDirty = true;
                        }
                    }
                }
            }
            finally
            {
                s_rwImgListLock.ReleaseReaderLock();
            }
        }
    }
}