diff --git a/src/Titano.Core/Codecs/Apng/ApngEncoder.cs b/src/Titano.Core/Codecs/Apng/ApngEncoder.cs new file mode 100644 index 00000000..5047d90a --- /dev/null +++ b/src/Titano.Core/Codecs/Apng/ApngEncoder.cs @@ -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; + +/// Options of . +public sealed record ApngEncoderOptions +{ + /// Write RGBA (alpha taken from 4-channel buffers); otherwise RGB. + public bool Alpha { get; init; } + + /// acTL num_plays: 0 loops forever. + public int LoopCount { get; init; } + + /// Crop frames to the changed area (blend OVER with transparent unchanged pixels when possible). + public bool FrameDifferencing { get; init; } = true; + + public CompressionLevel CompressionLevel { get; init; } = CompressionLevel.Optimal; +} + +/// +/// 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. +/// +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 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); + } + + /// Frames written so far (merged identical frames count once). + public int FrameCount { get; private set; } + + /// Adds a linear-light frame shown for ticks. + 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); + } + + /// Adds interleaved 8-bit sRGB pixels (RGB, or RGBA when ). + public void AddFrame(ReadOnlySpan pixels, long duration90k) + { + if (pixels.Length != _width * _height * _bpp) throw new ArgumentException($"Expected width × height × {_bpp} bytes", nameof(pixels)); + AddPixels(pixels.ToArray(), duration90k); + } + + /// Writes the last frame and IEND, then patches the frame count. + 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 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; + } + + /// Exact reduced fraction of a second when it fits 16 bits; otherwise the cumulative timeline rounded to 1/1000 … 1 s. + 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)[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 actl = stackalloc byte[8]; + BinaryPrimitives.WriteInt32BigEndian(actl, frames); + BinaryPrimitives.WriteInt32BigEndian(actl[4..], _options.LoopCount); + PngEncoder.WriteChunk(_output, "acTL", actl); + } +} diff --git a/tests/Titano.Core.Tests/Video/ApngEncoderTests.cs b/tests/Titano.Core.Tests/Video/ApngEncoderTests.cs new file mode 100644 index 00000000..db4eba39 --- /dev/null +++ b/tests/Titano.Core.Tests/Video/ApngEncoderTests.cs @@ -0,0 +1,221 @@ +using System.Buffers.Binary; +using System.IO.Compression; +using System.Text; +using Titano.Core.Codecs.Apng; +using Titano.Core.Hashing; +using Titano.Core.Imaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Video; + +public sealed class ApngEncoderTests +{ + private const int W = 40, H = 30; + + [Test] + public void ChunkOrderSequenceNumbersAndCrcsAreValid() + { + var frames = Enumerable.Range(0, 5).Select(i => Pattern(i, 3)).ToList(); + var bytes = Encode(frames, new ApngEncoderOptions(), 3000); + var chunks = Chunks(bytes); + Assert.SequenceEqual( + ["IHDR", "acTL", "fcTL", "IDAT", "fcTL", "fdAT", "fcTL", "fdAT", "fcTL", "fdAT", "fcTL", "fdAT", "IEND"], + chunks.Select(c => c.Type)); + var actl = chunks[1].Data; + Assert.Equal(5, BinaryPrimitives.ReadInt32BigEndian(actl)); + Assert.Equal(0, BinaryPrimitives.ReadInt32BigEndian(actl.AsSpan(4))); + var sequence = chunks.Where(c => c.Type is "fcTL" or "fdAT").Select(c => BinaryPrimitives.ReadUInt32BigEndian(c.Data)).ToList(); + Assert.SequenceEqual(Enumerable.Range(0, sequence.Count).Select(i => (uint)i), sequence); + var first = chunks[2].Data; + Assert.Equal((W, H, 0, 0), (BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(4)), BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(8)), + BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(12)), BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(16)))); + Assert.Equal((1, 30), Delay(first)); + } + + [Test] + public void FirstFrameIsTheDefaultImageAndAllFramesComposeExactly() + { + var frames = new List { Pattern(0, 3), Pattern(0, 3), Pattern(1, 3) }; + // Frame 3 changes only a small block of frame 2. + var last = (byte[])frames[2].Clone(); + for (var y = 5; y < 9; y++) + { + for (var x = 20; x < 26; x++) last[(y * W + x) * 3] ^= 0xFF; + } + frames.Add(last); + var bytes = Encode(frames, new ApngEncoderOptions(), 1500); + var decoded = Decode(bytes, 3); + Assert.Equal(3, decoded.Count); // the duplicate merged into the first frame + Assert.BytesEqual(frames[0], decoded[0].Canvas); + Assert.BytesEqual(frames[2], decoded[1].Canvas); + Assert.BytesEqual(frames[3], decoded[2].Canvas); + Assert.Equal((1, 30), decoded[0].Delay); + Assert.Equal((20, 5, 6, 4), decoded[2].Rect); + Assert.Equal(0, decoded[2].Blend); // RGB output always uses SOURCE + } + + [Test] + public void RgbaDifferencingUsesOverWithTransparentUnchangedPixels() + { + var a = Pattern(2, 4); + var b = (byte[])a.Clone(); + b[(10 * W + 10) * 4] ^= 0x80; + b[(12 * W + 14) * 4 + 1] ^= 0x80; + var bytes = Encode([a, b], new ApngEncoderOptions { Alpha = true }, 3000); + var decoded = Decode(bytes, 4); + Assert.Equal(2, decoded.Count); + Assert.Equal(1, decoded[1].Blend); + Assert.Equal((10, 10, 5, 3), decoded[1].Rect); + Assert.BytesEqual(b, decoded[1].Canvas); + } + + [Theory] + [Case(3003L, 1001, 30000)] + [Case(90000L * 30, 30, 1)] + [Case(3001L, 33, 1000)] + public void DelaysAreExactFractionsOrCumulativelyRounded(long duration, int num, int den) + { + var bytes = Encode([Pattern(0, 3), Pattern(1, 3)], new ApngEncoderOptions(), duration); + var fctl = Chunks(bytes).Where(c => c.Type == "fcTL").ToList(); + Assert.Equal((num, den), Delay(fctl[0].Data)); + } + + [Test] + public void LinearBuffersAreEncodedAsSrgb() + { + using var image = new ImageBuffer(W, H, 4); + image.Plane(0).Fill(ColorSpace.Linear8(200)); + image.Plane(1).Fill(ColorSpace.Linear8(100)); + image.Plane(3).Fill(0.5f); + using var ms = new MemoryStream(); + var encoder = new ApngEncoder(ms, W, H, new ApngEncoderOptions { Alpha = true, LoopCount = 2 }); + encoder.AddFrame(image, 9000); + encoder.Complete(); + var decoded = Decode(ms.ToArray(), 4); + Assert.SequenceEqual(new byte[] { 200, 100, 0, 128 }, decoded[0].Canvas.Take(4)); + Assert.Equal(2, BinaryPrimitives.ReadInt32BigEndian(Chunks(ms.ToArray())[1].Data.AsSpan(4))); + } + + private static byte[] Encode(List frames, ApngEncoderOptions options, long duration) + { + using var ms = new MemoryStream(); + var encoder = new ApngEncoder(ms, W, H, options); + foreach (var f in frames) encoder.AddFrame(f, duration); + encoder.Complete(); + return ms.ToArray(); + } + + private static (int, int) Delay(byte[] fctl) => + (BinaryPrimitives.ReadUInt16BigEndian(fctl.AsSpan(20)), BinaryPrimitives.ReadUInt16BigEndian(fctl.AsSpan(22))); + + private sealed record Chunk(string Type, byte[] Data); + + /// Splits the PNG into chunks, checking the signature, lengths and every CRC. + private static List Chunks(byte[] png) + { + Assert.BytesEqual([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A], png.AsSpan(0, 8)); + var list = new List(); + var pos = 8; + while (pos < png.Length) + { + var length = BinaryPrimitives.ReadInt32BigEndian(png.AsSpan(pos)); + var type = Encoding.ASCII.GetString(png, pos + 4, 4); + Assert.Equal(BinaryPrimitives.ReadUInt32BigEndian(png.AsSpan(pos + 8 + length)), Crc32.Compute(png.AsSpan(pos + 4, length + 4)), $"CRC of {type}"); + list.Add(new Chunk(type, png.AsSpan(pos + 8, length).ToArray())); + pos += 12 + length; + } + Assert.Equal(png.Length, pos); + return list; + } + + private sealed record Frame(byte[] Canvas, (int, int) Delay, (int X, int Y, int W, int H) Rect, int Blend); + + /// Inflates, unfilters and composites every frame (dispose NONE, blend SOURCE/OVER with binary alpha). + private static List Decode(byte[] png, int bpp) + { + var chunks = Chunks(png); + var canvas = new byte[W * H * bpp]; + var frames = new List(); + for (var i = 0; i < chunks.Count; i++) + { + if (chunks[i].Type != "fcTL") continue; + var f = chunks[i].Data; + int w = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(4)), h = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(8)); + int x = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(12)), y = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(16)); + Assert.Equal((byte)0, f[24]); + var data = chunks[i + 1].Type == "IDAT" ? chunks[i + 1].Data : chunks[i + 1].Data[4..]; + var pixels = Unfilter(Inflate(data), w, h, bpp); + for (var row = 0; row < h; row++) + { + for (var col = 0; col < w; col++) + { + var s = (row * w + col) * bpp; + var d = ((y + row) * W + x + col) * bpp; + if (f[25] == 1 && bpp == 4 && pixels[s + 3] == 0) continue; + pixels.AsSpan(s, bpp).CopyTo(canvas.AsSpan(d)); + } + } + frames.Add(new Frame((byte[])canvas.Clone(), Delay(f), (x, y, w, h), f[25])); + } + return frames; + } + + private static byte[] Inflate(byte[] zlib) + { + using var z = new ZLibStream(new MemoryStream(zlib), CompressionMode.Decompress); + using var ms = new MemoryStream(); + z.CopyTo(ms); + return ms.ToArray(); + } + + private static byte[] Unfilter(byte[] filtered, int w, int h, int bpp) + { + var stride = w * bpp; + Assert.Equal((stride + 1) * h, filtered.Length); + var output = new byte[stride * h]; + for (var y = 0; y < h; y++) + { + var filter = filtered[y * (stride + 1)]; + for (var i = 0; i < stride; i++) + { + int raw = filtered[y * (stride + 1) + 1 + i]; + int a = i >= bpp ? output[y * stride + i - bpp] : 0; + int b = y > 0 ? output[(y - 1) * stride + i] : 0; + int c = i >= bpp && y > 0 ? output[(y - 1) * stride + i - bpp] : 0; + output[y * stride + i] = (byte)(filter switch + { + 0 => raw, + 1 => raw + a, + 2 => raw + b, + 3 => raw + ((a + b) >> 1), + _ => raw + Paeth(a, b, c), + }); + } + } + return output; + } + + private static int Paeth(int a, int b, int c) + { + var p = a + b - c; + int pa = Math.Abs(p - a), pb = Math.Abs(p - b), pc = Math.Abs(p - c); + return pa <= pb && pa <= pc ? a : pb <= pc ? b : c; + } + + private static byte[] Pattern(int variant, int bpp) + { + var pixels = new byte[W * H * bpp]; + for (var y = 0; y < H; y++) + { + for (var x = 0; x < W; x++) + { + var o = (y * W + x) * bpp; + pixels[o] = (byte)(x * 6 + variant * 40); + pixels[o + 1] = (byte)(y * 8); + pixels[o + 2] = (byte)((x ^ y) * 4 + variant); + if (bpp == 4) pixels[o + 3] = 255; + } + } + return pixels; + } +}