feat(apng): add APNG encoder with frame differencing and exact delays

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:51:37 +00:00
1 parent 71c0113f5f
commit 04f31e7f43
2 files changed
+467

No files matched your search

+246
View File
@@ -0,0 +1,246 @@
using System.Buffers.Binary;
using System.IO.Compression;
using Titano.Core.Codecs.Png;
using Titano.Core.Imaging;
namespace Titano.Core.Codecs.Apng;
/// <summary>Options of <see cref="ApngEncoder"/>.</summary>
public sealed record ApngEncoderOptions
{
/// <summary>Write RGBA (alpha taken from 4-channel buffers); otherwise RGB.</summary>
public bool Alpha { get; init; }
/// <summary>acTL num_plays: 0 loops forever.</summary>
public int LoopCount { get; init; }
/// <summary>Crop frames to the changed area (blend OVER with transparent unchanged pixels when possible).</summary>
public bool FrameDifferencing { get; init; } = true;
public CompressionLevel CompressionLevel { get; init; } = CompressionLevel.Optimal;
}
/// <summary>
/// Animated PNG encoder (8-bit RGB/RGBA): acTL/fcTL/IDAT/fdAT with one shared sequence counter; the first frame is
/// the default image. Delays are exact fractions of the 90 kHz durations when they fit 16 bits, otherwise rounded on
/// the cumulative timeline. Identical consecutive frames merge. The output must be seekable (acTL is patched at the
/// end) and is not disposed.
/// </summary>
public sealed class ApngEncoder
{
private const int TimeScale = 90_000;
private const byte DisposeNone = 0;
private const byte BlendSource = 0, BlendOver = 1;
private readonly Stream _output;
private readonly int _width;
private readonly int _height;
private readonly int _bpp;
private readonly ApngEncoderOptions _options;
private readonly long _actlOffset;
private byte[]? _canvas;
private Pending? _pending;
private long _time;
private uint _sequence;
private bool _completed;
public ApngEncoder(Stream output, int width, int height, ApngEncoderOptions? options = null)
{
ArgumentNullException.ThrowIfNull(output);
if (!output.CanSeek || !output.CanWrite) throw new ArgumentException("The output stream must be writable and seekable", nameof(output));
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height);
_options = options ?? new ApngEncoderOptions();
ArgumentOutOfRangeException.ThrowIfNegative(_options.LoopCount, nameof(options));
_output = output;
_width = width;
_height = height;
_bpp = _options.Alpha ? 4 : 3;
output.Write([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
Span<byte> ihdr = stackalloc byte[13];
BinaryPrimitives.WriteInt32BigEndian(ihdr, width);
BinaryPrimitives.WriteInt32BigEndian(ihdr[4..], height);
ihdr[8] = 8;
ihdr[9] = (byte)(_options.Alpha ? PngColorType.Rgba : PngColorType.Rgb);
PngEncoder.WriteChunk(output, "IHDR", ihdr);
_actlOffset = output.Position;
WriteAnimationControl(0);
}
/// <summary>Frames written so far (merged identical frames count once).</summary>
public int FrameCount { get; private set; }
/// <summary>Adds a linear-light frame shown for <paramref name="duration90k"/> ticks.</summary>
public void AddFrame(ImageBuffer frame, long duration90k)
{
if (frame.Width != _width || frame.Height != _height) throw new ArgumentException("Frame size differs from the animation size", nameof(frame));
var n = _width * _height;
var pixels = new byte[n * _bpp];
var r = frame.Plane(0);
var g = frame.Channels >= 3 ? frame.Plane(1) : r;
var b = frame.Channels >= 3 ? frame.Plane(2) : r;
var a = frame.Channels == 4 ? frame.Plane(3) : default;
for (var i = 0; i < n; i++)
{
var o = i * _bpp;
pixels[o] = ColorSpace.Encode8(r[i]);
pixels[o + 1] = ColorSpace.Encode8(g[i]);
pixels[o + 2] = ColorSpace.Encode8(b[i]);
if (_bpp == 4) pixels[o + 3] = a.IsEmpty ? (byte)255 : (byte)(Math.Clamp(a[i], 0f, 1f) * 255f + 0.5f);
}
AddPixels(pixels, duration90k);
}
/// <summary>Adds interleaved 8-bit sRGB pixels (RGB, or RGBA when <see cref="ApngEncoderOptions.Alpha"/>).</summary>
public void AddFrame(ReadOnlySpan<byte> pixels, long duration90k)
{
if (pixels.Length != _width * _height * _bpp) throw new ArgumentException($"Expected width × height × {_bpp} bytes", nameof(pixels));
AddPixels(pixels.ToArray(), duration90k);
}
/// <summary>Writes the last frame and IEND, then patches the frame count.</summary>
public void Complete()
{
if (_completed) throw new InvalidOperationException("The encoder is already complete");
if (_pending is null) throw new InvalidOperationException("No frames were added");
Emit(_time);
PngEncoder.WriteChunk(_output, "IEND", []);
var end = _output.Position;
_output.Position = _actlOffset;
WriteAnimationControl(FrameCount);
_output.Position = end;
_output.Flush();
_completed = true;
}
private sealed record Pending(long Start, int X, int Y, int Width, int Height, byte Blend, byte[] Data);
private void AddPixels(byte[] pixels, long duration)
{
if (_completed) throw new InvalidOperationException("The encoder is complete");
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(duration);
int x = 0, y = 0, w = _width, h = _height;
var blend = BlendSource;
var region = pixels;
if (_canvas is not null && _options.FrameDifferencing)
{
(x, y, w, h) = ChangedArea(pixels, _canvas);
if (w == 0)
{
_time += duration; // identical frame: the previous one stays longer
return;
}
region = Crop(pixels, x, y, w, h, out var opaque);
if (_bpp == 4 && opaque)
{
// Unchanged pixels become fully transparent and OVER keeps what is displayed beneath them.
for (var row = 0; row < h; row++)
{
for (var col = 0; col < w; col++)
{
var c = ((y + row) * _width + x + col) * 4;
if (pixels.AsSpan(c, 4).SequenceEqual(_canvas.AsSpan(c, 4))) region.AsSpan((row * w + col) * 4, 4).Clear();
}
}
blend = BlendOver;
}
}
_canvas = pixels;
var data = PngEncoder.Compress(region, h, w * _bpp, _bpp, _options.CompressionLevel);
Emit(_time);
_pending = new Pending(_time, x, y, w, h, blend, data);
_time += duration;
}
private (int X, int Y, int Width, int Height) ChangedArea(byte[] pixels, byte[] canvas)
{
int left = _width, top = _height, right = -1, bottom = -1;
for (var y = 0; y < _height; y++)
{
var row = y * _width * _bpp;
for (var x = 0; x < _width; x++)
{
var o = row + x * _bpp;
if (pixels.AsSpan(o, _bpp).SequenceEqual(canvas.AsSpan(o, _bpp))) continue;
left = Math.Min(left, x);
right = Math.Max(right, x);
top = Math.Min(top, y);
bottom = y;
}
}
return right < 0 ? (0, 0, 0, 0) : (left, top, right - left + 1, bottom - top + 1);
}
private byte[] Crop(byte[] pixels, int x, int y, int w, int h, out bool opaque)
{
var region = new byte[w * h * _bpp];
opaque = true;
for (var row = 0; row < h; row++) pixels.AsSpan(((y + row) * _width + x) * _bpp, w * _bpp).CopyTo(region.AsSpan(row * w * _bpp));
if (_bpp == 4)
{
for (var i = 3; i < region.Length && opaque; i += 4) opaque = region[i] == 255;
}
return region;
}
private void Emit(long end)
{
if (_pending is not { } frame) return;
var (num, den) = Delay(frame.Start, end);
Span<byte> fctl = stackalloc byte[26];
BinaryPrimitives.WriteUInt32BigEndian(fctl, _sequence++);
BinaryPrimitives.WriteInt32BigEndian(fctl[4..], frame.Width);
BinaryPrimitives.WriteInt32BigEndian(fctl[8..], frame.Height);
BinaryPrimitives.WriteInt32BigEndian(fctl[12..], frame.X);
BinaryPrimitives.WriteInt32BigEndian(fctl[16..], frame.Y);
BinaryPrimitives.WriteUInt16BigEndian(fctl[20..], num);
BinaryPrimitives.WriteUInt16BigEndian(fctl[22..], den);
fctl[24] = DisposeNone;
fctl[25] = frame.Blend;
PngEncoder.WriteChunk(_output, "fcTL", fctl);
if (FrameCount == 0)
{
PngEncoder.WriteChunk(_output, "IDAT", frame.Data);
}
else
{
var fdat = new byte[4 + frame.Data.Length];
BinaryPrimitives.WriteUInt32BigEndian(fdat, _sequence++);
frame.Data.CopyTo(fdat, 4);
PngEncoder.WriteChunk(_output, "fdAT", fdat);
}
FrameCount++;
_pending = null;
}
/// <summary>Exact reduced fraction of a second when it fits 16 bits; otherwise the cumulative timeline rounded to 1/1000 … 1 s.</summary>
private static (ushort Num, ushort Den) Delay(long start, long end)
{
var duration = end - start;
var g = Gcd(duration, TimeScale);
if (duration / g <= ushort.MaxValue && TimeScale / g <= ushort.MaxValue) return ((ushort)(duration / g), (ushort)(TimeScale / g));
foreach (var den in (ReadOnlySpan<int>)[1000, 100, 10, 1])
{
var num = Rounded(end, den) - Rounded(start, den);
if (num <= ushort.MaxValue) return ((ushort)num, (ushort)den);
}
return (ushort.MaxValue, 1);
static long Rounded(long ticks, int den) => (ticks * den + TimeScale / 2) / TimeScale;
}
private static long Gcd(long a, long b)
{
while (b != 0) (a, b) = (b, a % b);
return a;
}
private void WriteAnimationControl(int frames)
{
Span<byte> actl = stackalloc byte[8];
BinaryPrimitives.WriteInt32BigEndian(actl, frames);
BinaryPrimitives.WriteInt32BigEndian(actl[4..], _options.LoopCount);
PngEncoder.WriteChunk(_output, "acTL", actl);
}
}