From 596c48f73caeee067111ac6bf5eb4618ac529419 Mon Sep 17 00:00:00 2001
From: Kelsey Gilbert <kelsey.gilbert@mozilla.com>
Date: Thu, 10 Oct 2024 14:16:28 -0700
Subject: [PATCH] Spec that out-of-range premultipliedAlpha:true values have
 undefined compositing results. (#3698)

---
 specs/latest/1.0/index.html | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/specs/latest/1.0/index.html b/specs/latest/1.0/index.html
index 5e8d8bfba..4b9a89bed 100644
--- a/specs/latest/1.0/index.html
+++ b/specs/latest/1.0/index.html
@@ -839,12 +839,29 @@ <h4>Context creation parameters</h4>
             </dd>
         <dt> <span class=prop-value>premultipliedAlpha</span>
             <dd>
+            <p>
                 If the value is true the page compositor will assume the drawing buffer contains
                 colors with premultiplied alpha. If the value is false the page compositor will
                 assume that colors in the drawing buffer are not premultiplied. This flag is ignored
-                if the <strong>alpha</strong> flag is
-                false. See <a href="#PREMULTIPLIED_ALPHA">Premultiplied Alpha</a> for more
+                if the <strong>alpha</strong> flag is false.
+            </p>
+            <p>
+                With <code>premultipliedAlpha:true</code>, any pixels sent to the page
+                compositor shall have color values less-than-or-equal-to their alpha value,
+                otherwise the colors resulting from compositing such out-of-range pixel values
+                are undefined.
+                <div class="note">
+                    For example, with <code>premultipliedAlpha:true</code>
+                    <code>vec4(1.0, 0.0, 0.0, 0.5)</code> might display as green
+                    instead of red, possibly due to optimized packed compositing math overflows.
+                    This is left undefined due to the intractible performance impact of requiring
+                    consistent behavior.
+                </div>
+            </p>
+            <p>
+                See <a href="#PREMULTIPLIED_ALPHA">Premultiplied Alpha</a> for more
                 information on the effects of the <code>premultipliedAlpha</code> flag.
+            </p>
             </dd>
         <dt> <span class=prop-value>preserveDrawingBuffer</span>
             <dd>