document qr alpha compositing helpers

Author: PrzemyslawKlys

CodeGlyphX.Tests/QrPngRendererTests.cs

@@ -116,6 +116,25 @@ public void Render_SimpleRgba_Preserves_Straight_Alpha_Over_Transparent_Backgrou
         Assert.Equal(128, rgba[3]);
     }
 
+    [Fact]
+    public void Render_SimpleRgba_TransparentForeground_LeavesBackgroundUnchanged() {
+        var matrix = new BitMatrix(1, 1);
+        matrix[0, 0] = true;
+
+        var png = QrPngRenderer.Render(matrix, new QrPngRenderOptions {
+            ModuleSize = 1,
+            QuietZone = 0,
+            Foreground = new Rgba32(0, 0, 0, 0),
+            Background = new Rgba32(12, 34, 56, 78),
+        });
+
+        var (rgba, _, _, _) = PngTestDecoder.DecodeRgba32(png);
+        Assert.Equal(12, rgba[0]);
+        Assert.Equal(34, rgba[1]);
+        Assert.Equal(56, rgba[2]);
+        Assert.Equal(78, rgba[3]);
+    }
+
     [Fact]
     public void Render_GeneralPath_Preserves_Straight_Alpha_Over_Transparent_Background() {
         var matrix = new BitMatrix(1, 1);
@@ -138,6 +157,28 @@ public void Render_GeneralPath_Preserves_Straight_Alpha_Over_Transparent_Backgro
         Assert.Equal(128, rgba[center + 3]);
     }
 
+    [Fact]
+    public void Render_GeneralPath_TransparentForeground_LeavesBackgroundUnchanged() {
+        var matrix = new BitMatrix(1, 1);
+        matrix[0, 0] = true;
+
+        var png = QrPngRenderer.Render(matrix, new QrPngRenderOptions {
+            ModuleSize = 5,
+            QuietZone = 0,
+            Foreground = new Rgba32(0, 0, 0, 0),
+            Background = new Rgba32(12, 34, 56, 78),
+            ModuleShape = QrPngModuleShape.Circle,
+            ModuleScale = 0.8,
+        });
+
+        var (rgba, width, height, stride) = PngTestDecoder.DecodeRgba32(png);
+        var center = (height / 2) * stride + (width / 2) * 4;
+        Assert.Equal(12, rgba[center + 0]);
+        Assert.Equal(34, rgba[center + 1]);
+        Assert.Equal(56, rgba[center + 2]);
+        Assert.Equal(78, rgba[center + 3]);
+    }
+
     [Fact]
     public void Render_LogoOverlay_Preserves_Straight_Alpha_Over_Transparent_Background() {
         var matrix = new BitMatrix(1, 1);

CodeGlyphX/Rendering/Png/QrPngRenderer.Internal.Render.cs

@@ -520,6 +520,8 @@ private static bool IsSolidMask(bool[] mask) {
     }
 
     private static Rgba32 CompositeColor(Rgba32 foreground, Rgba32 background) {
+        // Keep solid-module precompositing aligned with the per-pixel renderer so
+        // transparent output stores straight-alpha colors consistently.
         return ComposeOver(foreground, background);
     }
 
@@ -3142,6 +3144,8 @@ private static int PositiveMod(int value, int modulus) {
         return m < 0 ? m + modulus : m;
     }
 
+    // Compose straight-alpha colors using Porter-Duff "over" so transparent
+    // canvases preserve the source RGB instead of leaking hidden background RGB.
     private static Rgba32 ComposeOver(Rgba32 top, Rgba32 bottom) {
         var ta = top.A;
         if (ta == 0) return bottom;
@@ -3177,6 +3181,8 @@ private static void BlendPixel(byte[] scanlines, int stride, int x, int y, Rgba3
         BlendPixelAt(scanlines, rowStart, color);
     }
 
+    // Blend onto the stored RGBA pixel with the same straight-alpha math used by
+    // the simple and solid paths. This keeps modules, eyes, and logos consistent.
     private static void BlendPixelAt(byte[] buffer, int offset, Rgba32 color) {
         if (color.A == 0) return;
         if (color.A == 255) {

CodeGlyphX/Rendering/Png/QrPngRenderer.Internal.SimpleRgba.cs

@@ -194,6 +194,8 @@ private static void FillRowSimple(BitMatrix modules, QrPngRenderOptions opts, in
     }
 
     private static Rgba32 CompositeForeground(Rgba32 foreground, Rgba32 background) {
+        // Reuse the shared compositor so the simple square path matches the
+        // general renderer when foreground alpha is less than fully opaque.
         return ComposeOver(foreground, background);
     }