Add SKCodec.AnimationStatus property

[mattleibow]

Summary

Adds the SKCodec.AnimationStatus property to disambiguate the meaning of RepetitionCount == 0, which currently could mean either "not animated" (static image) or "play once" (single-loop animation).

Closes #3939

Changes

C# API

• New property: SKCodec.AnimationStatus returns SKCodecAnimationStatus enum with values:
  • Animated - Image is animated (FrameCount > 1)
  • NotAnimated - Image is static (FrameCount == 0 or 1)
  • Unknown - Animation status cannot yet be determined (may change after reading frames)

C API (mono/skia#263)

• Added sk_codec_animation_status_t enum (YES=0, NO=1, UNKNOWN=2)
• Added sk_codec_is_animated() function wrapping SkCodec::isAnimated()
• CRITICAL FIX: Uses explicit static_cast<int>() to convert C++ enum class to C enum. Original C-style cast was broken - all codecs were returning incorrect values.

Tests

Tests validate the property works correctly and strictly assert expected values:

• AnimatedGifReturnsAnimated - Animated GIF with multiple frames MUST return Animated, not `Unknown"
• StaticImageReturnsNotAnimated - Static images must NOT return Animated
• AnimationStatusDisambiguatesRepetitionCount - Validates disambiguation behavior
• PngGivesDefinitiveAnswerImmediately - Documents PNG immediate answer behavior
• GifMayReturnUnknownWithPartialInput - Documents GIF partial input behavior

Per Skia's own tests (tests/CodecAnimTest.cpp): FrameCount > 1 returns IsAnimated::kYes, FrameCount == 1 returns IsAnimated::kNo.

Dependencies

Requires: mono/skia#263 to be merged first (C API changes)

Testing

All tests pass: Failed: 0, Passed: 5730, Skipped: 13 ✅

---

Merge commit message

Add SKCodec.AnimationStatus property (#4230)

Context: https://github.com/mono/SkiaSharp/issues/3939
Fixes: #3939
Changes: https://github.com/mono/skia/pull/263

Before this change, `SKCodec.RepetitionCount == 0` was ambiguous: it could mean
either "not animated" (a static image like PNG or JPEG) or "loop once" (an
animated GIF configured to play a single time). Users had no reliable way to
distinguish between these cases, forcing them to guess based on file extension
or to attempt decoding frames unnecessarily.

Skia upstream added `SkCodec::isAnimated()` in milestone 135, returning a
tri-state result: `kYes`, `kNo`, or `kUnknown`. This PR exposes that API through
the existing SkiaSharp layers, allowing C# code to definitively identify whether
a codec represents an animated image.

~~ C API (mono/skia#263) ~~

Added `sk_codec_animation_status_t` enum with values `YES`, `NO`, and `UNKNOWN`,
and the `sk_codec_is_animated()` function wrapping `SkCodec::isAnimated()`.

CRITICAL: Initial implementation used C-style cast which does not work correctly
for C++ enum class types. Fixed to use explicit `static_cast<int>()` conversion.
Without this fix, all codecs returned incorrect values making the API non-functional.

~~ C# Wrapper ~~

Added `SKCodecAnimationStatus` enum (Animated=0, NotAnimated=1, Unknown=2) matching
the Skia enum order exactly, and a read-only `AnimationStatus` property to `SKCodec`.

~~ Tests ~~

Five tests validate correct behavior with strict assertions:

  * `AnimatedGifReturnsAnimated` — animated GIF MUST return Animated (not Unknown)
  * `StaticImageReturnsNotAnimated` — static images must NOT return Animated
  * `AnimationStatusDisambiguatesRepetitionCount` — resolves RepetitionCount==0 ambiguity
  * `PngGivesDefinitiveAnswerImmediately` — documents PNG immediate answer
  * `GifMayReturnUnknownWithPartialInput` — documents GIF partial input behavior

All 5730 tests pass (baseline: 11 pre-existing failures unrelated to this change).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Matthew Leibowitz <mattleibow@live.com>

[github-actions]

📦 Try the packages from this PR

Warning

Do not run these scripts without first reviewing the code in this PR.

Step 1 — Download the packages

bash / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.sh | bash -s -- 4230

PowerShell / Windows:

iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 4230"

Step 2 — Add the local NuGet source

dotnet nuget add source ~/.skiasharp/hives/pr-4230/packages --name skiasharp-pr-4230

More options

Option	Description
--successful-only / -SuccessfulOnly	Only use successful builds
--force / -Force	Overwrite previously downloaded packages
--list / -List	List available artifacts without downloading
--build-id ID / -BuildId ID	Download from a specific build

Or download manually from Azure Pipelines — look for the nuget artifact on the build for this PR.

Remove the source when you're done:

dotnet nuget remove source skiasharp-pr-4230

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Site
🔗 View Staging Docs
🔗 View Staging Gallery (Blazor)
🔗 View Staging Gallery (Uno Platform)
🔗 View Staging SkiaFiddle

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.