From 0a6635d993fc01d1c01a6cd41f1e248133254615 Mon Sep 17 00:00:00 2001
From: Jennifer Taylor <dragonminded@dragonminded.com>
Date: Sun, 23 May 2021 20:31:39 +0000
Subject: [PATCH] Add comment about additive blending alpha 'hack'.

---
 bemani/format/afp/blend.py         | 8 ++++++++
 bemani/format/afp/blendaltimpl.cxx | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/bemani/format/afp/blend.py b/bemani/format/afp/blend.py
index 019c198..b54f3ad 100644
--- a/bemani/format/afp/blend.py
+++ b/bemani/format/afp/blend.py
@@ -64,6 +64,14 @@ except ImportError:
             clamp(dest[0] + (src[0] * srcpercent)),
             clamp(dest[1] + (src[1] * srcpercent)),
             clamp(dest[2] + (src[2] * srcpercent)),
+            # Additive blending doesn't actually make sense on semi-transparent destinations,
+            # as that implies that the semi-transparent pixel will be later displayed on top
+            # of something else. That doesn't work since additive blending needs to non-linearly
+            # mix with the destination. So, in reality, we should be doing what subtractive
+            # blending does and keeping the destination alpha (which should always be 255),
+            # but if somebody renders an animation with additive blending meant to go over a
+            # background onto a transparent or semi-transparent background this will make the
+            # resulting graphic look more correct.
             clamp(dest[3] + (255 * srcpercent)),
         )
 
diff --git a/bemani/format/afp/blendaltimpl.cxx b/bemani/format/afp/blendaltimpl.cxx
index 6533df7..2b8e1fb 100644
--- a/bemani/format/afp/blendaltimpl.cxx
+++ b/bemani/format/afp/blendaltimpl.cxx
@@ -121,6 +121,14 @@ extern "C"
             clamp(dest.r + (src.r * srcpercent)),
             clamp(dest.g + (src.g * srcpercent)),
             clamp(dest.b + (src.b * srcpercent)),
+            // Additive blending doesn't actually make sense on semi-transparent destinations,
+            // as that implies that the semi-transparent pixel will be later displayed on top
+            // of something else. That doesn't work since additive blending needs to non-linearly
+            // mix with the destination. So, in reality, we should be doing what subtractive
+            // blending does and keeping the destination alpha (which should always be 255),
+            // but if somebody renders an animation with additive blending meant to go over a
+            // background onto a transparent or semi-transparent background this will make the
+            // resulting graphic look more correct.
             clamp(dest.a + (255 * srcpercent)),
         };
     }