diff --git a/src/Titano.Core/Video/Yuv/Nv12Converter.cs b/src/Titano.Core/Video/Yuv/Nv12Converter.cs new file mode 100644 index 00000000..44b7f477 --- /dev/null +++ b/src/Titano.Core/Video/Yuv/Nv12Converter.cs @@ -0,0 +1,299 @@ +using System.Runtime.CompilerServices; +using System.Runtime.Intrinsics; +using Titano.Core.Imaging; + +namespace Titano.Core.Video.Yuv; + +/// Position of 4:2:0 chroma samples relative to luma. +public enum ChromaSiting +{ + /// Co-sited with the left luma sample, vertically between rows (MPEG-2/H.264/HEVC default, chroma_sample_loc_type 0). + Left, + + /// Centred between four luma samples (JPEG/MPEG-1, chroma_sample_loc_type 1). + Center, +} + +/// +/// Linear-light RGB ⇄ BT.709 limited-range Y'CbCr 4:2:0: NV12 (8-bit) and P010 +/// (10-bit in the top bits of 16-bit words). The sRGB transfer is applied before the matrix, as encoders expect +/// display-referred input. Width and height must be even; luma is vectorised, rows run in parallel. +/// +public static class Nv12Converter +{ + private const float Kr = 0.2126f, Kg = 0.7152f, Kb = 0.0722f; + private const float CbScale = 1 / (2 * (1 - Kb)); // 1 / 1.8556 + private const float CrScale = 1 / (2 * (1 - Kr)); // 1 / 1.5748 + private const int ParallelThreshold = 1 << 16; + private static readonly float[] EncodeLut = BuildEncodeLut(); + + /// Bytes of an NV12 frame (elements of a P010 frame) for a row stride in bytes (elements). + public static int FrameLength(int stride, int height) => checked(stride * height * 3 / 2); + + /// Writes NV12: Y rows of bytes, then interleaved CbCr rows of the same stride. + public static unsafe void ToNv12(ImageBuffer source, Span destination, ChromaSiting siting = ChromaSiting.Left, int stride = 0) + { + stride = Validate(source.Width, source.Height, stride, destination.Length); + fixed (byte* d = destination) Convert(source, (nint)d, stride, siting, tenBit: false); + } + + /// Writes P010: as NV12 with 16-bit elements holding 10-bit codes in the top bits; counts elements. + public static unsafe void ToP010(ImageBuffer source, Span destination, ChromaSiting siting = ChromaSiting.Left, int stride = 0) + { + stride = Validate(source.Width, source.Height, stride, destination.Length); + fixed (ushort* d = destination) Convert(source, (nint)d, stride, siting, tenBit: true); + } + + /// NV12 back to linear RGB (chroma upsampled for the given siting); used for verification. + public static void FromNv12(ReadOnlySpan source, ImageBuffer destination, ChromaSiting siting = ChromaSiting.Left, int stride = 0) + { + stride = Validate(destination.Width, destination.Height, stride, source.Length); + var (luma, cb, cr) = Planes(destination.Width, destination.Height); + var w = destination.Width; + for (var y = 0; y < destination.Height; y++) + { + for (var x = 0; x < w; x++) luma[y * w + x] = (source[y * stride + x] - 16) / 219f; + } + var uv = source[(stride * destination.Height)..]; + for (var j = 0; j < destination.Height / 2; j++) + { + for (var i = 0; i < w / 2; i++) + { + cb[j * (w / 2) + i] = (uv[j * stride + 2 * i] - 128) / 224f; + cr[j * (w / 2) + i] = (uv[j * stride + 2 * i + 1] - 128) / 224f; + } + } + Reverse(destination, siting, luma, cb, cr); + } + + /// P010 back to linear RGB; used for verification. + public static void FromP010(ReadOnlySpan source, ImageBuffer destination, ChromaSiting siting = ChromaSiting.Left, int stride = 0) + { + stride = Validate(destination.Width, destination.Height, stride, source.Length); + var (luma, cb, cr) = Planes(destination.Width, destination.Height); + var w = destination.Width; + for (var y = 0; y < destination.Height; y++) + { + for (var x = 0; x < w; x++) luma[y * w + x] = ((source[y * stride + x] >> 6) - 64) / 876f; + } + var uv = source[(stride * destination.Height)..]; + for (var j = 0; j < destination.Height / 2; j++) + { + for (var i = 0; i < w / 2; i++) + { + cb[j * (w / 2) + i] = ((uv[j * stride + 2 * i] >> 6) - 512) / 896f; + cr[j * (w / 2) + i] = ((uv[j * stride + 2 * i + 1] >> 6) - 512) / 896f; + } + } + Reverse(destination, siting, luma, cb, cr); + } + + private static (float[] Luma, float[] Cb, float[] Cr) Planes(int width, int height) => + (new float[width * height], new float[width * height / 4], new float[width * height / 4]); + + private static int Validate(int width, int height, int stride, int length) + { + if ((width & 1) != 0 || (height & 1) != 0) throw new ArgumentException("4:2:0 needs even width and height"); + stride = stride == 0 ? width : stride; + if (stride < width) throw new ArgumentOutOfRangeException(nameof(stride)); + if (length < FrameLength(stride, height)) throw new ArgumentException("Buffer too small for the frame"); + return stride; + } + + private static void Convert(ImageBuffer source, nint destination, int stride, ChromaSiting siting, bool tenBit) + { + var pairs = source.Height / 2; + if (source.Width * source.Height < ParallelThreshold) + { + var scratch = new Scratch(source.Width); + for (var j = 0; j < pairs; j++) ConvertRowPair(source, destination, stride, j, siting, tenBit, scratch); + return; + } + Parallel.For(0, pairs, () => new Scratch(source.Width), (j, _, scratch) => + { + ConvertRowPair(source, destination, stride, j, siting, tenBit, scratch); + return scratch; + }, static _ => { }); + } + + private sealed class Scratch(int width) + { + public readonly float[] R0 = new float[width], G0 = new float[width], B0 = new float[width]; + public readonly float[] R1 = new float[width], G1 = new float[width], B1 = new float[width]; + } + + private static unsafe void ConvertRowPair(ImageBuffer source, nint destination, int stride, int pair, ChromaSiting siting, bool tenBit, Scratch s) + { + var width = source.Width; + var y0 = pair * 2; + EncodeRow(source, y0, s.R0, s.G0, s.B0); + EncodeRow(source, y0 + 1, s.R1, s.G1, s.B1); + var chromaRow = source.Height + pair; + if (tenBit) + { + var d = (ushort*)destination; + LumaRow10(s.R0, s.G0, s.B0, new Span(d + (long)y0 * stride, width)); + LumaRow10(s.R1, s.G1, s.B1, new Span(d + (long)(y0 + 1) * stride, width)); + var uv = new Span(d + (long)chromaRow * stride, width); + for (var i = 0; i < width / 2; i++) + { + var (cb, cr) = Chroma(s, i, siting); + uv[2 * i] = (ushort)(Quantize(cb, 896, 512, 1023) << 6); + uv[2 * i + 1] = (ushort)(Quantize(cr, 896, 512, 1023) << 6); + } + } + else + { + var d = (byte*)destination; + LumaRow8(s.R0, s.G0, s.B0, new Span(d + (long)y0 * stride, width)); + LumaRow8(s.R1, s.G1, s.B1, new Span(d + (long)(y0 + 1) * stride, width)); + var uv = new Span(d + (long)chromaRow * stride, width); + for (var i = 0; i < width / 2; i++) + { + var (cb, cr) = Chroma(s, i, siting); + uv[2 * i] = (byte)Quantize(cb, 224, 128, 255); + uv[2 * i + 1] = (byte)Quantize(cr, 224, 128, 255); + } + } + } + + /// sRGB-encodes one row into R'G'B' scratch rows (grey sources fill all three). + private static void EncodeRow(ImageBuffer source, int y, float[] r, float[] g, float[] b) + { + Encode(source.Row(0, y), r); + if (source.Channels == 1) + { + r.CopyTo(g, 0); + r.CopyTo(b, 0); + return; + } + Encode(source.Row(1, y), g); + Encode(source.Row(2, y), b); + } + + /// + /// Direct 16-bit lookup of the sRGB transfer: the steepest slope (12.92) keeps the error below 1e-4, + /// a tenth of a 10-bit code, at a fraction of the cost of the interpolated encoder. + /// + private static void Encode(ReadOnlySpan linear, float[] encoded) + { + var lut = EncodeLut; + for (var x = 0; x < linear.Length; x++) + { + var v = linear[x]; + v = v > 0f ? (v < 1f ? v : 1f) : 0f; // NaN → 0 + encoded[x] = lut[(int)(v * 65535f + 0.5f)]; + } + } + + private static float[] BuildEncodeLut() + { + var lut = new float[65536]; + for (var i = 0; i < lut.Length; i++) lut[i] = (float)ColorSpace.LinearToSrgb(i / 65535.0); + return lut; + } + + /// Filters R'G'B' of the 2×2 (centre) or 3×2 [1 2 1] (left) footprint, then applies the matrix. + [MethodImpl(MethodImplOptions.AggressiveInlining)] + private static (float Cb, float Cr) Chroma(Scratch s, int i, ChromaSiting siting) + { + var x = 2 * i; + float r, g, b; + if (siting == ChromaSiting.Center) + { + r = (s.R0[x] + s.R0[x + 1] + s.R1[x] + s.R1[x + 1]) * 0.25f; + g = (s.G0[x] + s.G0[x + 1] + s.G1[x] + s.G1[x + 1]) * 0.25f; + b = (s.B0[x] + s.B0[x + 1] + s.B1[x] + s.B1[x + 1]) * 0.25f; + } + else + { + var l = x == 0 ? 0 : x - 1; + r = (s.R0[l] + 2 * s.R0[x] + s.R0[x + 1] + s.R1[l] + 2 * s.R1[x] + s.R1[x + 1]) * 0.125f; + g = (s.G0[l] + 2 * s.G0[x] + s.G0[x + 1] + s.G1[l] + 2 * s.G1[x] + s.G1[x + 1]) * 0.125f; + b = (s.B0[l] + 2 * s.B0[x] + s.B0[x + 1] + s.B1[l] + 2 * s.B1[x] + s.B1[x + 1]) * 0.125f; + } + var y = Kr * r + Kg * g + Kb * b; + return ((b - y) * CbScale, (r - y) * CrScale); + } + + [MethodImpl(MethodImplOptions.AggressiveInlining)] + private static int Quantize(float value, float scale, float offset, int max) => Math.Clamp((int)(value * scale + offset + 0.5f), 0, max); + + private static void LumaRow8(float[] r, float[] g, float[] b, Span y) + { + var x = 0; + if (Vector256.IsHardwareAccelerated) + { + var max = Vector256.Create(255); + for (; x <= r.Length - 32; x += 32) + { + var a = Luma(r, g, b, x, 219f, 16.5f, max); + var c = Luma(r, g, b, x + 8, 219f, 16.5f, max); + var e = Luma(r, g, b, x + 16, 219f, 16.5f, max); + var f = Luma(r, g, b, x + 24, 219f, 16.5f, max); + var low = Vector256.Narrow(a.AsUInt32(), c.AsUInt32()); + var high = Vector256.Narrow(e.AsUInt32(), f.AsUInt32()); + Vector256.Narrow(low, high).CopyTo(y[x..]); + } + } + for (; x < r.Length; x++) y[x] = (byte)Math.Clamp((int)((Kr * r[x] + Kg * g[x] + Kb * b[x]) * 219f + 16.5f), 0, 255); + } + + private static void LumaRow10(float[] r, float[] g, float[] b, Span y) + { + var x = 0; + if (Vector256.IsHardwareAccelerated) + { + var max = Vector256.Create(1023); + for (; x <= r.Length - 16; x += 16) + { + var a = Vector256.ShiftLeft(Luma(r, g, b, x, 876f, 64.5f, max), 6); + var c = Vector256.ShiftLeft(Luma(r, g, b, x + 8, 876f, 64.5f, max), 6); + Vector256.Narrow(a.AsUInt32(), c.AsUInt32()).CopyTo(y[x..]); + } + } + for (; x < r.Length; x++) y[x] = (ushort)(Math.Clamp((int)((Kr * r[x] + Kg * g[x] + Kb * b[x]) * 876f + 64.5f), 0, 1023) << 6); + } + + /// Eight luma codes: round(Y' × scale + offset) clamped to [0, max]. + [MethodImpl(MethodImplOptions.AggressiveInlining)] + private static Vector256 Luma(float[] r, float[] g, float[] b, int x, float scale, float offset, Vector256 max) + { + var y = Vector256.Create(r, x) * Kr + Vector256.Create(g, x) * Kg + Vector256.Create(b, x) * Kb; + var code = Vector256.ConvertToInt32(y * scale + Vector256.Create(offset)); + return Vector256.Min(Vector256.Max(code, Vector256.Zero), max); + } + + private static void Reverse(ImageBuffer destination, ChromaSiting siting, float[] luma, float[] cbPlane, float[] crPlane) + { + int width = destination.Width, height = destination.Height, half = width / 2; + for (var y = 0; y < height; y++) + { + var row = y / 2 * half; + for (var x = 0; x < width; x++) + { + var i = x / 2; + float cb = cbPlane[row + i], cr = crPlane[row + i]; + if (siting == ChromaSiting.Left && (x & 1) == 1) + { + // Odd luma columns sit halfway between two co-sited chroma samples. + var n = Math.Min(i + 1, half - 1); + cb = (cb + cbPlane[row + n]) * 0.5f; + cr = (cr + crPlane[row + n]) * 0.5f; + } + var yv = luma[y * width + x]; + if (destination.Channels == 1) + { + destination[0, x, y] = (float)ColorSpace.SrgbToLinear(Math.Clamp(yv, 0, 1)); + continue; + } + var r = yv + cr / CrScale; + var b = yv + cb / CbScale; + var g = (yv - Kr * r - Kb * b) / Kg; + destination[0, x, y] = (float)ColorSpace.SrgbToLinear(Math.Clamp(r, 0, 1)); + destination[1, x, y] = (float)ColorSpace.SrgbToLinear(Math.Clamp(g, 0, 1)); + destination[2, x, y] = (float)ColorSpace.SrgbToLinear(Math.Clamp(b, 0, 1)); + } + } + } +} diff --git a/tests/Titano.Core.Tests/Video/Nv12ConverterTests.cs b/tests/Titano.Core.Tests/Video/Nv12ConverterTests.cs new file mode 100644 index 00000000..5231b8a9 --- /dev/null +++ b/tests/Titano.Core.Tests/Video/Nv12ConverterTests.cs @@ -0,0 +1,181 @@ +using Titano.Core.Imaging; +using Titano.Core.Video.Yuv; +using Titano.Testing; + +namespace Titano.Core.Tests.Video; + +public sealed class Nv12ConverterTests +{ + [Theory] + [Case(1f, 1f, 1f, 235, 128, 128)] + [Case(0f, 0f, 0f, 16, 128, 128)] + [Case(1f, 0f, 0f, 63, 102, 240)] + [Case(0f, 1f, 0f, 173, 42, 26)] + [Case(0f, 0f, 1f, 32, 240, 118)] + public void FlatColoursHitBt709LimitedRangeCodes(float r, float g, float b, int y, int u, int v) + { + using var image = Flat(8, 4, r, g, b); + var nv12 = new byte[Nv12Converter.FrameLength(8, 4)]; + Nv12Converter.ToNv12(image, nv12); + Assert.True(nv12.AsSpan(0, 32).ToArray().All(c => c == y), $"luma {nv12[0]} expected {y}"); + Assert.Equal((byte)u, nv12[32]); + Assert.Equal((byte)v, nv12[33]); + + var p010 = new ushort[Nv12Converter.FrameLength(8, 4)]; + Nv12Converter.ToP010(image, p010); + Assert.InRange(p010[0] >> 6, y * 4 - 2, y * 4 + 2); + Assert.Equal(0, p010[0] & 0x3F); + Assert.InRange(p010[32] >> 6, u * 4 - 2, u * 4 + 2); + } + + [Test] + public void TenBitWhiteAndBlackAreExact() + { + using var white = Flat(4, 2, 1, 1, 1); + var p010 = new ushort[Nv12Converter.FrameLength(4, 2)]; + Nv12Converter.ToP010(white, p010); + Assert.Equal((ushort)(940 << 6), p010[0]); + Assert.Equal((ushort)(512 << 6), p010[8]); + using var black = Flat(4, 2, 0, 0, 0); + Nv12Converter.ToP010(black, p010); + Assert.Equal((ushort)(64 << 6), p010[3]); + } + + [Theory] + [Case(70, 34)] + [Case(512, 256)] + public void LumaMatchesScalarReferenceIncludingRemainders(int width, int height) + { + using var image = Gradient(width, height); + var nv12 = new byte[Nv12Converter.FrameLength(width, height)]; + var p010 = new ushort[Nv12Converter.FrameLength(width, height)]; + Nv12Converter.ToNv12(image, nv12); + Nv12Converter.ToP010(image, p010); + for (var y = 0; y < height; y++) + { + for (var x = 0; x < width; x++) + { + var luma = 0.2126f * ColorSpace.EncodeFast(image[0, x, y]) + 0.7152f * ColorSpace.EncodeFast(image[1, x, y]) + 0.0722f * ColorSpace.EncodeFast(image[2, x, y]); + Assert.InRange(nv12[y * width + x], luma * 219 + 16 - 1, luma * 219 + 17); + Assert.InRange(p010[y * width + x] >> 6, luma * 876 + 64 - 1, luma * 876 + 65); + } + } + } + + [Theory] + [Case(ChromaSiting.Left)] + [Case(ChromaSiting.Center)] + public void RoundTripStaysWithinQuantisationError(ChromaSiting siting) + { + const int w = 256, h = 128; + using var image = Gradient(w, h); + using var back = new ImageBuffer(w, h); + var nv12 = new byte[Nv12Converter.FrameLength(w, h)]; + Nv12Converter.ToNv12(image, nv12, siting); + Nv12Converter.FromNv12(nv12, back, siting); + var maxNv12 = MaxEncodedError(image, back); + + var p010 = new ushort[Nv12Converter.FrameLength(w, h)]; + Nv12Converter.ToP010(image, p010, siting); + Nv12Converter.FromP010(p010, back, siting); + var maxP010 = MaxEncodedError(image, back); + + Assert.LessOrEqual(maxNv12, 3.5 / 255); + Assert.LessOrEqual(maxP010, 2.0 / 255); + Assert.Less(maxP010, maxNv12); + } + + [Test] + public void GreyRampRoundTripOnlyCarriesLumaQuantisation() + { + const int w = 256, h = 4; + using var image = new ImageBuffer(w, h, 1); + for (var y = 0; y < h; y++) + { + for (var x = 0; x < w; x++) image[0, x, y] = ColorSpace.Linear8((byte)x); + } + using var back = new ImageBuffer(w, h, 1); + var nv12 = new byte[Nv12Converter.FrameLength(w, h)]; + Nv12Converter.ToNv12(image, nv12); + Assert.True(nv12.AsSpan(w * h).ToArray().All(c => c == 128), "grey has neutral chroma"); + Nv12Converter.FromNv12(nv12, back); + double max = 0; + for (var i = 0; i < w * h; i++) max = Math.Max(max, Math.Abs(ColorSpace.LinearToSrgb(image.Plane(0)[i]) - ColorSpace.LinearToSrgb(back.Plane(0)[i]))); + // One limited-range step is 255/219 full-range levels; rounding keeps half of it. + Assert.LessOrEqual(max, 0.6 / 219); + } + + [Test] + public void SitingChangesTheChromaFilterFootprint() + { + // Columns: red, red | blue, blue. Centre siting keeps the second chroma pure blue, + // left siting (co-sited with column 2, taps 1:2:1) mixes in a quarter of red. + using var image = new ImageBuffer(4, 2); + for (var y = 0; y < 2; y++) + { + image[0, 0, y] = image[0, 1, y] = 1; + image[2, 2, y] = image[2, 3, y] = 1; + } + var centre = new byte[Nv12Converter.FrameLength(4, 2)]; + var left = new byte[Nv12Converter.FrameLength(4, 2)]; + Nv12Converter.ToNv12(image, centre, ChromaSiting.Center); + Nv12Converter.ToNv12(image, left, ChromaSiting.Left); + Assert.Equal((byte)240, centre[8 + 2]); // Cb of pure blue + Assert.Equal((byte)118, centre[8 + 3]); // Cr of pure blue + Assert.Equal((byte)240, left[8 + 1]); // Cr of pure red at column 0 + // R'G'B' = (0.25, 0, 0.75): Cb = (0.75 − 0.1073) / 1.8556 → 206, Cr = (0.25 − 0.1073) / 1.5748 → 148. + Assert.Equal((byte)206, left[8 + 2]); + Assert.Equal((byte)148, left[8 + 3]); + } + + [Test] + public void RespectsStrideAndRejectsOddSizes() + { + using var image = Flat(6, 2, 1, 1, 1); + var nv12 = new byte[Nv12Converter.FrameLength(16, 2)]; + nv12.AsSpan().Fill(7); + Nv12Converter.ToNv12(image, nv12, stride: 16); + Assert.Equal((byte)235, nv12[5]); + Assert.Equal((byte)7, nv12[6]); // padding untouched + Assert.Equal((byte)128, nv12[32]); + using var odd = new ImageBuffer(5, 2); + Assert.Throws(() => Nv12Converter.ToNv12(odd, new byte[64])); + } + + private static double MaxEncodedError(ImageBuffer a, ImageBuffer b) + { + double max = 0; + for (var c = 0; c < 3; c++) + { + var pa = a.Plane(c); + var pb = b.Plane(c); + for (var i = 0; i < pa.Length; i++) max = Math.Max(max, Math.Abs(ColorSpace.LinearToSrgb(pa[i]) - ColorSpace.LinearToSrgb(pb[i]))); + } + return max; + } + + private static ImageBuffer Flat(int w, int h, float r, float g, float b) + { + var image = new ImageBuffer(w, h); + image.Plane(0).Fill(r); + image.Plane(1).Fill(g); + image.Plane(2).Fill(b); + return image; + } + + /// Smooth colour ramps in encoded space (linearised), so 4:2:0 loss stays small. + private static ImageBuffer Gradient(int w, int h) + { + var image = new ImageBuffer(w, h); + for (var y = 0; y < h; y++) + { + for (var x = 0; x < w; x++) + { + image[0, x, y] = (float)ColorSpace.SrgbToLinear(0.1 + 0.8 * x / w); + image[1, x, y] = (float)ColorSpace.SrgbToLinear(0.2 + 0.6 * y / h); + image[2, x, y] = (float)ColorSpace.SrgbToLinear(0.5 + 0.2 * Math.Sin((x + y) * 0.02)); + } + } + return image; + } +}