feat: Add animation loop control to DrawImage with repeatCount parameter

[Yushu2606]

Prerequisites

• I have written a descriptive pull-request title
• I have verified that there are no overlapping pull-requests open
• I have verified that I am following the existing coding patterns and practice as demonstrated in the repository. These follow strict Stylecop rules 👮.
• I have provided test coverage for my change (where applicable)

Description

This pull request enhances the DrawImage functionality by adding animation loop control through a new repeatCount parameter. This allows users to control how many times animated images (GIFs, APNGs, WebP animations, etc.) should loop when drawn onto another image.
Close #2997

Changes Made

• Added repeatCount parameter to all DrawImage extension methods in DrawImageExtensions.cs
• Updated DrawImageProcessor constructors to accept and store the repeatCount parameter
• Enhanced DrawImageProcessor<TPixelBg, TPixelFg> with animation frame cycling logic:
  • Added currentFrameLoop field to track animation progress
  • Implemented frame selection based on current loop count
  • Added validation to ensure repeatCount >= 0
  • Added loop termination logic (0 = infinite, >0 = specific count)

Key Features

• Animation Control: repeatCount parameter controls how many times an animated image loops
  • 0 = infinite loop
  • >0 = specific number of loops
• Frame Cycling: Automatically cycles through animation frames based on loop count
• Backward Compatibility: All existing DrawImage method signatures are preserved with the new parameter added

Usage Example

// Draw animated GIF with infinite loop
image.DrawImage(animatedGif, opacity: 0.8f, repeatCount: 0);

// Draw animated GIF with 3 loops
image.DrawImage(animatedGif, opacity: 0.8f, repeatCount: 3);

// Draw at specific location with animation control
image.DrawImage(animatedGif, new Point(10, 10), opacity: 0.8f, repeatCount: 2);

Technical Details

• The implementation tracks the current frame loop using currentFrameLoop field
• Frame selection uses modulo operation: currentFrameIndex = currentFrameLoop % ForegroundImage.Frames.Count
• Loop termination is handled by checking if current loop count exceeds the specified repeatCount
• Validation ensures repeatCount is non-negative using Guard.MustBeGreaterThanOrEqualTo

Images

before	after (loop count is 0)

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[JimBobSquarePants]

HI @Yushu2606

It's standard practice to create a post here in our Ideas channel for feature enhancements to ensure that any new features are fully fleshed out before discussion. Upon reading this PR I'm not sure exactly what benefit this feature actually brings.

Could you please visit the channel and state you case. Thanks!

[JimBobSquarePants]

@Yushu2606 I had a quick look at this and I think we can look at adding the feature. I'll do a thorough review asap.

[JimBobSquarePants]

Hi @Yushu2606 would you please be able to give me write access to your fork (i.e add me as a contributor). Git LFS doesn't let me upload test reference images without it.

[Yushu2606]

Hi @Yushu2606 would you please be able to give me write access to your fork (i.e add me as a contributor). Git LFS doesn't let me upload test reference images without it.

ok, i have invited you as a collaborator

[JimBobSquarePants]

I'm happy to merge this now. Thanks @Yushu2606 for your patience, sometimes, unfortunately it takes a very long time to get things organised.