[css-images-4] Per WG resolution, cross-fade() takes 1+ arguments. Define sizing and painting of the new function arguments in detail.

tabatkins · tabatkins · commit ab20b4cbccf4 · 2018-08-03T16:56:43.000-07:00
diff --git a/css-images-4/Overview.bs b/css-images-4/Overview.bs
@@ -376,8 +376,6 @@ Image Fallbacks and Annotations: the ''image()'' notation {#image-notation}
 Combining images: the ''cross-fade()'' notation {#cross-fade-function}
 ----------------------------------------------------------------------
 
-
-
 	When transitioning between images,
 	CSS requires a way to explicitly refer to the intermediate image
 	that is a combination of the start and end images.
@@ -392,37 +390,146 @@ Combining images: the ''cross-fade()'' notation {#cross-fade-function}
 	The syntax for ''cross-fade()'' is defined as:
 
 	<pre class=prod>
-		<dfn caniuse="css-cross-fade">cross-fade()</dfn> = cross-fade( <<cf-mixing-image>> , <<cf-final-image>>? )
-		<dfn>&lt;cf-mixing-image></dfn> = <<percentage>>? && <<image>>
-		<dfn>&lt;cf-final-image></dfn> = <<image>> | <<color>>
+		<dfn caniuse="css-cross-fade">cross-fade()</dfn> = cross-fade( <<cf-image>># )
+		<dfn>&lt;cf-image></dfn> = <<percentage>>? && [ <<image>> | <<color>> ]
 	</pre>
 
 	The function represents an image generated by
-	combining two images.
+	combining two or more images.
 
-	The <<percentage>> represents how much of the first image is retained
-	when it is blended with the second image.
+	The <<percentage>> represents how much of each image is retained
+	when it is blended with the other images.
 	The <<percentage>> must be between ''0%'' and ''100%'' inclusive;
 	any other value is invalid.
-	If omitted,
-	it defaults to the value ''50%''.
-
-	If the last argument is a <<color>>,
-	it represents a solid-color image with the same intrinsic dimensions as the first image.
-	If omitted,
-	it defaults to the color ''transparent''.
-
-	More precisely,
-	given ''cross-fade(<var>p</var> <var>A</var>, <var>B</var>)'',
-	where <var>A</var> and <var>B</var> are images
-	and <var>p</var> is a percentage between 0% and 100%,
-	the function represents an image
-	with width equal to <code>width<sub>A</sub> &times; <var>p</var> + width<sub>B</sub> &times; (1-<var>p</var>)</code>
-	and height equal to <code>height<sub>A</sub> &times; <var>p</var> + height<sub>B</sub> &times; (1-<var>p</var>)</code>.
-	The contents of the image must be constructed by
-	first scaling <var>A</var> and <var>B</var> to the size of the generated image,
-	then applying <code>dissolve(<var>A</var>,<var>p</var>) plus dissolve(<var>B</var>,1-<var>p</var>)</code>.
-	The "dissolve()" function and "plus" compositing operator are defined in the literature by Porter-Duff. [[PORTERDUFF]]
+
+	If any percentages are omitted,
+	all the specified percentages are summed together
+	and subtracted from ''100%'',
+	the result is floored at ''0%'',
+	then divided equally between all images with omitted percentages
+	at computed-value time.
+
+	<div class=note>
+		While this is not reflected in the computed value,
+		when all the arguments’ percentages sum to greater than ''100%'',
+		the sizing/painting details effectively rescale them so that they sum to exactly ''100%''.
+
+		On the other hand,
+		when the sum is less than ''100%'',
+		the sizing/painting details effectively act like there's an additional ''transparent'' argument,
+		with its percentage set to the remaining value
+		necessary to make the sum equal ''100%''.
+	</div>
+
+	If a <<color>> is provided,
+	it represents a solid-color image
+	with “automatic” dimensions
+	(it doesn't participate in the sizing of the result image at all;
+	see details in the sizing details below).
+
+### ''cross-fade()'' Sizing ### {#cross-fade-sizing}
+
+	The dimensions of the image represented by a ''cross-fade()''
+	are a weighted average of dimensions of the <<image>> arguments to the function;
+	the <<color>> arguments have no effect.
+	They are calculated as follows:
+
+	<div algorithm>
+		To determine the <dfn export>intrinsic dimensions of a cross-fade()</dfn>:
+
+		1. Let |images| be an empty list.
+
+		2. For each |argument| of the ''cross-fade()'' function with an <<image>> value:
+			1. Let |item| be a [=tuple=] consisting of a width, a height, and a percentage.
+			2. Run the [=object size negotation=] algorithm for the <<image>>,
+				as appropriate for the context in which the ''cross-fade()'' appears,
+				and set |item|’s width and height
+				to the width and height of the resulting [=concrete object size=].
+			3. Set |item|’s percentage to the |argument|’s percentage.
+
+		3. If |images| is empty,
+			return no intrinsic dimensions.
+
+		4. Let |percentage sum| be the sum of all the percentages of the [=list/items=] in |images|.
+
+		5. [=list/For each=] |item| in |images|,
+			divide |item|’s percentage by |percentage sum|,
+			and set |item|’s percentage to the result.
+
+			Assert: The percentages in |images| now sum to ''100%''.
+
+		6. Let |final width| and |final height| be ''0px''.
+
+		7. [=list/For each=] |item| in |images|,
+			multiply |item|’s width by |item|’s percentage
+			and add the result to |final width|,
+			and multiply |item|’s height by |item|’s percentage
+			and add the result to |final height|.
+
+		8. Return an intrinsic width of |final width|
+			and an intrinsic height of |final height|.
+	</div>
+
+### ''cross-fade()'' Painting ### {#cross-fade-painting}
+
+	The image represented by a ''cross-fade()''
+	is a weighted average of the input arguments to the function,
+	calculated as follows:
+
+
+	<div algorithm>
+		To determine the <dfn export>appearance of a cross-fade()</dfn>:
+
+		1. Let |images| be an empty list.
+
+		2. Let |size| be a [=tuple=] of width and height,
+			initialized to the result of finding the [=concrete object size=]
+			of the ''cross-fade()'' function
+			(using the [=intrinsic dimensions of a cross-fade()=]).
+
+		3. For each |argument| of the ''cross-fade()'' function:
+			1. Let |item| be a [=tuple=] consisting of an image and a percentage.
+			2. If |argument| has an <<image>>,
+				rescale it to |size|’s width and height
+				and set |item|’s image to the result.
+				Otherwise, |argument| has a <<color>>;
+				set |item|’s image to a solid-color image of the <<color>>,
+				with |size|’s dimensions.
+			3. Set |item|’s percentage to the |argument|’s percentage.
+
+		4. Let |percentage sum| be the sum of all the percentages of the [=list/items=] in |images|.
+
+		5. [=list/For each=] |item| in |images|,
+			divide |item|’s percentage by |percentage sum|,
+			and set |item|’s percentage to the result.
+
+		6. Let |final image| be an image
+			with |size|’s dimensions,
+			and every pixel being the weighted linear average of the corresponding pixels of [=list/each=] |item|’s image in |images|,
+			weighted according to the |item|’s percentage.
+			(Average both the color channels and the alpha channel of the pixels.)
+
+			Note: This is applying the Porter-Duff <code>dissolve</code> operator to each source image,
+			then combining them all together with the Porter-Duff <code>plus</code> operator. [[PORTER-DUFF]]
+
+			Issue: What color space does this average take place in? sRGB? Controlled by @color-space?
+
+		8. If |percentage sum| is less than ''100%'',
+			multiply the alpha channel of every pixel in |final image| by |percentage sum|.
+
+			Note: This ensures that ''cross-fade(img 50%)'' doesn't darken the image
+			(as would happen by blending with <a>transparent black</a>),
+			but just makes it more transparent,
+			as the author almost certainly intends.
+
+			Issue: Should this also apply to explicit ''transparent'' arguments?
+			See <a href="https://github.com/w3c/csswg-drafts/issues/2722">issue 2722</a>
+			for making ''transparent'' generally act like just “transparency”,
+			rather than specifically being <a>transparent black</a>.
+			We'd specify this by filtering them out in step 3.
+
+		8. Return |final image|.
+	</div>
 
 <!--
 ████████ ██       ████████ ██     ██ ████████ ██    ██ ████████   ███ ███
