@thi.ng/shader-ast-stdlib 0.12.28 → 0.13.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-22T21:47:07Z
+- **Last updated**: 2023-01-10T15:20:19Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.13.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/shader-ast-stdlib@0.13.0) (2023-01-10)
+
+#### 🚀 Features
+
+- add pre/postmultiplyAlpha() fns ([367ebbd](https://github.com/thi-ng/umbrella/commit/367ebbd))
+
+#### 🩹 Bug fixes
+
+- fix porterDuff() ops ([f5bbcc8](https://github.com/thi-ng/umbrella/commit/f5bbcc8))
+
 ## [0.12.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/shader-ast-stdlib@0.12.0) (2022-05-07)
 
 #### 🚀 Features

package/README.md

@@ -101,7 +101,7 @@ For Node.js REPL:
 const shaderAstStdlib = await import("@thi.ng/shader-ast-stdlib");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 10.88 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 10.96 KB
 
 ## Dependencies
 
@@ -502,4 +502,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2019 - 2022 Karsten Schmidt // Apache License 2.0
+© 2019 - 2023 Karsten Schmidt // Apache License 2.0

package/color/porter-duff.d.ts

@@ -1,23 +1,30 @@
 import type { Fn2 } from "@thi.ng/api";
-import type { FloatTerm } from "@thi.ng/shader-ast";
+import type { FloatTerm, Vec4Sym } from "@thi.ng/shader-ast";
 /**
  * Higher-order Porter-Duff alpha compositing operator. See
  * [thi.ng/porter-duff](https://thi.ng/porter-duff) for reference. Returns an
  * optimized AST function which accepts 2 RGBA colors (vec4) and returns blended
- * & clamped result (also a vec4). All built-in PD operators are defined via
- * this HOF.
+ * & clamped result (also a vec4).
  *
- * The two given JS functions are used to extract blending coefficients for
- * src/dest colors and are called with the alpha components of both colors.
+ * @remark
+ * All built-in PD operators are defined via this HOF. The two given coefficient
+ * functions are used to extract blending coefficients for src/dest colors and
+ * are called with the alpha components of both colors.
  *
  * Optimization only happens for cases where either `fa` and/or `fb` are
- * {@link ZERO}.
+ * {@link ZERO} or {@link ONE}.
+ *
+ * *IMPORTANT*: Both colors MUST be use pre-multiplied alpha for correct
+ * results. If needed, use {@link premultiplyAlpha} and
+ * {@link postmultiplyAlpha}.
  *
  * @param name - function name
  * @param fa - src coeff fn
  * @param fb - dest coeff fn
  */
 export declare const porterDuff: (name: string, fa: Fn2<FloatTerm, FloatTerm, FloatTerm>, fb: Fn2<FloatTerm, FloatTerm, FloatTerm>) => import("@thi.ng/shader-ast").TaggedFn2<"vec4", "vec4", "vec4">;
+export declare const premultiplyAlpha: (col: Vec4Sym) => import("@thi.ng/shader-ast").Lit<"vec4">;
+export declare const postmultiplyAlpha: (col: Vec4Sym) => import("@thi.ng/shader-ast").Lit<"vec4">;
 export declare const ZERO: () => import("@thi.ng/shader-ast").Lit<"float">;
 export declare const ONE: () => import("@thi.ng/shader-ast").Lit<"float">;
 export declare const A: (a: FloatTerm) => FloatTerm;

package/color/porter-duff.js

@@ -1,37 +1,47 @@
 import { defn, ret } from "@thi.ng/shader-ast/ast/function";
 import { FLOAT0, FLOAT1, vec4 } from "@thi.ng/shader-ast/ast/lit";
-import { add, mul, sub } from "@thi.ng/shader-ast/ast/ops";
-import { $w } from "@thi.ng/shader-ast/ast/swizzle";
+import { add, div, mul, sub } from "@thi.ng/shader-ast/ast/ops";
+import { $w, $xyz } from "@thi.ng/shader-ast/ast/swizzle";
 import { clamp01 } from "../math/clamp.js";
-const coeff = (f, a, b) => (f === ZERO ? FLOAT0 : f === ONE ? a : mul(a, f($w(a), $w(b))));
+/** @internal */
+const __coeff = (col, f) => f === FLOAT0 ? vec4() : f === FLOAT1 ? col : mul(col, f);
 /**
  * Higher-order Porter-Duff alpha compositing operator. See
  * [thi.ng/porter-duff](https://thi.ng/porter-duff) for reference. Returns an
  * optimized AST function which accepts 2 RGBA colors (vec4) and returns blended
- * & clamped result (also a vec4). All built-in PD operators are defined via
- * this HOF.
+ * & clamped result (also a vec4).
  *
- * The two given JS functions are used to extract blending coefficients for
- * src/dest colors and are called with the alpha components of both colors.
+ * @remark
+ * All built-in PD operators are defined via this HOF. The two given coefficient
+ * functions are used to extract blending coefficients for src/dest colors and
+ * are called with the alpha components of both colors.
  *
  * Optimization only happens for cases where either `fa` and/or `fb` are
- * {@link ZERO}.
+ * {@link ZERO} or {@link ONE}.
+ *
+ * *IMPORTANT*: Both colors MUST be use pre-multiplied alpha for correct
+ * results. If needed, use {@link premultiplyAlpha} and
+ * {@link postmultiplyAlpha}.
  *
  * @param name - function name
  * @param fa - src coeff fn
  * @param fb - dest coeff fn
  */
 export const porterDuff = (name, fa, fb) => defn("vec4", name, ["vec4", "vec4"], (a, b) => {
-    const src = coeff(fa, a, b);
-    const dest = coeff(fb, a, b);
-    const srcZero = src === FLOAT0;
-    const destZero = dest === FLOAT0;
+    const sa = fa($w(a), $w(b));
+    const sb = fb($w(a), $w(b));
+    const src = __coeff(a, sa);
+    const dest = __coeff(b, sb);
+    const srcZero = sa === FLOAT0;
+    const destZero = sb === FLOAT0;
     return [
         ret(srcZero && destZero
             ? vec4()
             : clamp01(srcZero ? dest : destZero ? src : add(src, dest))),
     ];
 });
+export const premultiplyAlpha = (col) => vec4(mul($xyz(col), $w(col)), $w(col));
+export const postmultiplyAlpha = (col) => vec4(div($xyz(col), $w(col)), $w(col));
 // coefficient functions
 export const ZERO = () => FLOAT0;
 export const ONE = () => FLOAT1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/shader-ast-stdlib",
-  "version": "0.12.28",
+  "version": "0.13.0",
   "description": "Function collection for modular GPGPU / shader programming with @thi.ng/shader-ast",
   "type": "module",
   "module": "./index.js",
@@ -34,12 +34,12 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.2",
-    "@thi.ng/shader-ast": "^0.12.35"
+    "@thi.ng/api": "^8.6.3",
+    "@thi.ng/shader-ast": "^0.12.37"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.8",
+    "@thi.ng/testament": "^0.3.9",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.22",
@@ -330,5 +330,5 @@
     ],
     "year": 2019
   },
-  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
+  "gitHead": "3f0b3e2a7c82aefc7e46fb4338369836b5e1b8cf\n"
 }