@thi.ng/shader-ast-optimize 0.3.54 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-01T15:22:50Z
+- **Last updated**: 2024-03-07T20:40:47Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,21 @@ 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.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/shader-ast-optimize@0.4.0) (2024-03-07)
+
+#### 🚀 Features
+
+- add defOptimized(), rename source file ([b1dc3c0](https://github.com/thi-ng/umbrella/commit/b1dc3c0))
+  - add defOptimized() wrapper fn
+  - fix spelling in file name
+  - update example in docs
+- expand constantFolding() features, bug fixes ([1350bf7](https://github.com/thi-ng/umbrella/commit/1350bf7))
+  - add support scalar comparisons
+  - div-by-zero checks
+  - fix non-scalar mul & sub handling
+  - add support for exp2(), pow()
+  - add tests
+
 ### [0.3.27](https://github.com/thi-ng/umbrella/tree/@thi.ng/shader-ast-optimize@0.3.27) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -15,6 +15,7 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+  - [defOptimized()](#defoptimized)
   - [Tree optimizations](#tree-optimizations)
     - [Constant folding](#constant-folding)
 - [Status](#status)
@@ -29,60 +30,79 @@
 
 Shader AST code optimization passes/strategies. This is a support package for [@thi.ng/shader-ast](https://github.com/thi-ng/umbrella/tree/develop/packages/shader-ast).
 
+### defOptimized()
+
+The function
+[`defOptimize()`](https://docs.thi.ng/umbrella/shader-ast-optimize/functions/defOptimized.html)
+can be used as direct replacement for [thi.ng/shader-ast]()'s
+[`defMain()`](https://docs.thi.ng/umbrella/shader-ast/functions/defMain.html) to
+define automatically optimized shader `main()` functions.
+
 ### Tree optimizations
 
-Currently, only the following operations are supported / considered:
+Currently, only the following operations are supported/considered:
 
 #### Constant folding
 
-- scalar math operators
-- scalar math built-in functions
+- scalar math operators (incl. some vector versions)
+- scalar math built-in functions (incl. some vector versions)
+- scalar comparisons
 - single component vector swizzling
 - literal hoisting
 
-```ts
-import { $x, $y, add, defn, float, mul, neg, ret } from "@thi.ng/shader-ast";
+(See tests for some more examples, non-exhaustive...)
+
+**Note:** The static optimizer throws an error if it detects a division-by-zero...
+
+```ts tangle:export/readme1.ts
+import {
+  add, defn, float, mul, neg, ret, scope, vec2, $x, $y
+} from "@thi.ng/shader-ast";
 import { targetGLSL } from "@thi.ng/shader-ast-glsl";
 import { constantFolding } from "@thi.ng/shader-ast-optimize";
 
+// function def
 const foo = defn("float", "foo", ["float"], (x) => [
-  ret(mul(x, add(neg(float(10)), float(42))))
+  ret(mul(x, add(neg(float(10)), 42)))
 ]);
 
 const bar = vec2(100, 200);
 
+// program def
 const prog = scope([
   foo,
   foo(add(float(1), float(2))),
   foo(add($x(bar), $y(bar)))
 ], true);
 
+// GLSL codegen
 const glsl = targetGLSL();
 
 // unoptimized AST as GLSL (see section above)
-glsl(prog);
-
-// float foo(in float _sym0) {
-//   return (_sym0 * (-10.0 + 42.0));
-// };
+console.log(glsl(prog));
+// #version 300 es
+// float foo(in float _s0) {
+// return (_s0 * ((-10.0) + 42.0));
+// }
 // foo((1.0 + 2.0));
 // foo((vec2(100.0, 200.0).x + vec2(100.0, 200.0).y));
 
-// same tree after constant folding optimizations
-glsl(constantFolding(prog))
-
-// float foo(in float _sym0) {
-//   return (_sym0 * 32.0);
-// };
+// with constant folding
+console.log(glsl(constantFolding(prog)))
+// #version 300 es
+// float foo(in float _s0) {
+// return (_s0 * 32.0);
+// }
 // foo(3.0);
 // foo(300.0);
 
 const expr = mul(float(4), $x(vec2(2)))
 
-glsl(expr)
+console.log(glsl(expr))
 // (4.0 * vec2(2.0).x)
 
-glsl(constantFolding(expr))
+// optimize single expression
+console.log(glsl(constantFolding(expr)))
 // 8.0
 ```
 
@@ -112,12 +132,13 @@ For Node.js REPL:
 const shaderAstOptimize = await import("@thi.ng/shader-ast-optimize");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1014 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.24 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 - [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)
 - [@thi.ng/shader-ast](https://github.com/thi-ng/umbrella/tree/develop/packages/shader-ast)

package/{contant-folding.d.ts → constant-folding.d.ts}

@@ -1,6 +1,23 @@
-import type { Term } from "@thi.ng/shader-ast";
+import { type FnCall, type Term } from "@thi.ng/shader-ast";
 /** @internal */
 export declare const foldNode: import("@thi.ng/defmulti/api").MultiFn1<Term<any>, boolean | undefined>;
+/**
+ * Similar to {@link foldNode}, but specialized for function calls of builtin's
+ * (aka `call_i` AST nodes).
+ *
+ * @remarks
+ * Currently, implementations are only dealing with these builtins:
+ *
+ * - exp2
+ * - pow
+ *
+ * This function delegates based on the function name of the builtin and is
+ * extensible, i.e. custom optimizations can be added by calling
+ * `foldBuiltin.add("functionname", (node) => ...)`.
+ *
+ * @internal
+ */
+export declare const foldBuiltin: import("@thi.ng/defmulti/api").MultiFn1<FnCall<any>, boolean | undefined>;
 /**
  * Traverses given AST (potentially several times) and applies constant folding
  * optimizations where possible. Returns possibly updated tree (mutates
@@ -15,18 +32,17 @@ export declare const foldNode: import("@thi.ng/defmulti/api").MultiFn1<Term<any>
  * - literal hoisting
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/constant-folding.ts
  * import {
- *   add, defn, float, mul, neg, ret, scope, vec2
- *   $x, $y
+ *   add, defn, float, mul, neg, ret, scope, vec2, $x, $y
  * } from "@thi.ng/shader-ast";
  * import { targetGLSL } from "@thi.ng/shader-ast-glsl";
  * import { constantFolding } from "@thi.ng/shader-ast-optimize";
  *
  * // function def
  * const foo = defn("float", "foo", ["float"], (x) => [
- *   ret(mul(x, add(neg(float(10)), float(42))))]
- * )
+ *   ret(mul(x, add(neg(float(10)), 42)))
+ * ]);
  *
  * const bar = vec2(100, 200);
  *
@@ -37,36 +53,38 @@ export declare const foldNode: import("@thi.ng/defmulti/api").MultiFn1<Term<any>
  *   foo(add($x(bar), $y(bar)))
  * ], true);
  *
- * // serialized (GLSL)
+ * // GLSL codegen
  * const glsl = targetGLSL();
- * glsl(prog);
  *
- * // float foo(in float _sym0) {
- * //   return (_sym0 * (-10.0 + 42.0));
- * // };
+ * // unoptimized AST as GLSL (see section above)
+ * console.log(glsl(prog));
+ * // #version 300 es
+ * // float foo(in float _s0) {
+ * // return (_s0 * ((-10.0) + 42.0));
+ * // }
  * // foo((1.0 + 2.0));
  * // foo((vec2(100.0, 200.0).x + vec2(100.0, 200.0).y));
  *
  * // with constant folding
- * glsl(constantFolding(prog))
- *
- * // float foo(in float _sym0) {
- * //   return (_sym0 * 32.0);
- * // };
+ * console.log(glsl(constantFolding(prog)))
+ * // #version 300 es
+ * // float foo(in float _s0) {
+ * // return (_s0 * 32.0);
+ * // }
  * // foo(3.0);
  * // foo(300.0);
  *
  * const expr = mul(float(4), $x(vec2(2)))
  *
- * glsl(expr)
+ * console.log(glsl(expr))
  * // (4.0 * vec2(2.0).x)
  *
  * // optimize single expression
- * glsl(constantFolding(expr))
+ * console.log(glsl(constantFolding(expr)))
  * // 8.0
  * ```
  *
  * @param tree -
  */
 export declare const constantFolding: (tree: Term<any>) => Term<any>;
-//# sourceMappingURL=contant-folding.d.ts.map
+//# sourceMappingURL=constant-folding.d.ts.map

package/{contant-folding.js → constant-folding.js}

@@ -1,17 +1,32 @@
 import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { LogLevel } from "@thi.ng/logger/api";
 import { deg, rad } from "@thi.ng/math/angle";
 import { clamp } from "@thi.ng/math/interval";
 import { mix } from "@thi.ng/math/mix";
 import { fract, mod } from "@thi.ng/math/prec";
+import {
+  matchingPrimFor,
+  neg
+} from "@thi.ng/shader-ast";
 import {
   isFloat,
   isInt,
+  isLitNumOrVecConst,
   isLitNumericConst,
   isLitVecConst,
   isUint
 } from "@thi.ng/shader-ast/ast/checks";
-import { FLOAT0, float, int, lit, uint } from "@thi.ng/shader-ast/ast/lit";
+import {
+  FLOAT0,
+  FLOAT1,
+  FLOAT2,
+  bool,
+  float,
+  int,
+  lit,
+  uint
+} from "@thi.ng/shader-ast/ast/lit";
 import { allChildren, walk } from "@thi.ng/shader-ast/ast/scope";
 import { LOGGER } from "@thi.ng/shader-ast/logger";
 const replaceNode = (node, next) => {
@@ -31,7 +46,10 @@ const replaceNumericNode = (node, res) => {
   node.type === "uint" && (res >>>= 0);
   return replaceNode(node, lit(node.type, res));
 };
-const maybeFoldMath = (op, l, r) => op === "+" ? l + r : op === "-" ? l - r : op === "*" ? l * r : op === "/" ? l / r : void 0;
+const replaceBooleanNode = (node, res) => replaceNode(node, bool(res));
+const replaceWithConst = (node, ref, n) => replaceNode(node, matchingPrimFor(ref, n));
+const maybeFoldMath = (op, l, r) => op === "+" ? l + r : op === "-" ? l - r : op === "*" ? l * r : op === "/" ? r != 0 ? l / r : illegalArgs(`division by zero: ${l}/${r}`) : void 0;
+const maybeFoldCompare = (op, l, r) => op === "==" ? l === r : op === "!=" ? l !== r : op === "<" ? l < r : op === "<=" ? l <= r : op === ">=" ? l >= r : op === ">" ? l > r : void 0;
 const COMPS = { x: 0, y: 1, z: 2, w: 3 };
 const BUILTINS = {
   abs: ([a]) => Math.abs(a),
@@ -79,24 +97,38 @@ const foldNode = defmulti(
       const isNumL = isLitNumericConst(l);
       const isNumR = isLitNumericConst(r);
       if (isNumL && isNumR) {
-        let res = maybeFoldMath(op, l.val, r.val);
-        if (res !== void 0)
-          return replaceNumericNode(node, res);
+        const num = maybeFoldMath(op, l.val, r.val);
+        if (num !== void 0)
+          return replaceNumericNode(node, num);
+        const bool2 = maybeFoldCompare(op, l.val, r.val);
+        if (bool2 !== void 0)
+          return replaceBooleanNode(node, bool2);
       } else if (op === "*") {
-        if (isNumL && l.val === 0 || isNumR && r.val === 0)
-          return replaceNode(node, FLOAT0);
+        if (isNumL && l.val === 0)
+          return replaceWithConst(node, r, FLOAT0);
+        if (isNumR && r.val === 0)
+          return replaceWithConst(node, l, FLOAT0);
         if (isNumL && l.val === 1)
           return replaceNode(node, r);
         if (isNumR && r.val === 1)
           return replaceNode(node, l);
       } else if (op === "/") {
+        if (isNumL && l.val === 0)
+          return replaceWithConst(node, r, FLOAT0);
+        if (isNumR && r.val === 0)
+          illegalArgs("division by zero");
         if (isNumR && r.val === 1)
           return replaceNode(node, l);
-      } else if (op === "+" || op === "-") {
+      } else if (op === "+") {
         if (isNumL && l.val === 0)
           return replaceNode(node, r);
         if (isNumR && r.val === 0)
           return replaceNode(node, l);
+      } else if (op === "-") {
+        if (isNumL && l.val === 0)
+          return replaceNode(node, neg(r));
+        if (isNumR && r.val === 0)
+          return replaceNode(node, l);
       }
     },
     call_i: (node) => {
@@ -109,6 +141,8 @@ const foldNode = defmulti(
             op($node.args.map((x) => x.val))
           );
         }
+      } else {
+        return foldBuiltin($node);
       }
     },
     lit: (node) => {
@@ -139,6 +173,31 @@ const foldNode = defmulti(
     }
   }
 );
+const foldBuiltin = defmulti(
+  (x) => x.id,
+  {},
+  {
+    [DEFAULT]: () => false,
+    exp2: (node) => {
+      const a = node.args[0];
+      if (isLitNumOrVecConst(a, 0)) {
+        return replaceWithConst(node, a, FLOAT1);
+      }
+      if (isLitNumOrVecConst(a, 1)) {
+        return replaceWithConst(node, a, FLOAT2);
+      }
+    },
+    pow: (node) => {
+      const [a, b] = node.args;
+      if (isLitNumOrVecConst(b, 0)) {
+        return replaceWithConst(node, a, FLOAT1);
+      }
+      if (isLitNumOrVecConst(b, 1)) {
+        return replaceNode(node, a);
+      }
+    }
+  }
+);
 const constantFolding = (tree) => {
   let exec = true;
   while (exec) {
@@ -157,5 +216,6 @@ const constantFolding = (tree) => {
 };
 export {
   constantFolding,
+  foldBuiltin,
   foldNode
 };

package/defoptimized.d.ts

@@ -0,0 +1,9 @@
+import type { FnBody0 } from "@thi.ng/shader-ast";
+/**
+ * Same as [defMain()](), but applies optimizations (e.g.
+ * {@link constantFolding}) to the given function body.
+ *
+ * @param fn
+ */
+export declare const defOptimized: (fn: FnBody0) => import("@thi.ng/shader-ast").TaggedFn0<"void">;
+//# sourceMappingURL=defoptimized.d.ts.map

package/defoptimized.js

@@ -0,0 +1,6 @@
+import { defMain } from "@thi.ng/shader-ast/ast/function";
+import { constantFolding } from "./constant-folding.js";
+const defOptimized = (fn) => constantFolding(defMain(fn));
+export {
+  defOptimized
+};

package/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./contant-folding.js";
+export * from "./constant-folding.js";
+export * from "./defoptimized.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1 +1,2 @@
-export * from "./contant-folding.js";
+export * from "./constant-folding.js";
+export * from "./defoptimized.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/shader-ast-optimize",
-  "version": "0.3.54",
+  "version": "0.4.0",
   "description": "Shader AST code optimization passes/strategies",
   "type": "module",
   "module": "./index.js",
@@ -32,14 +32,16 @@
     "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
     "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
     "pub": "yarn npm publish --access public",
-    "test": "bun test"
+    "test": "bun test",
+    "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.27",
-    "@thi.ng/defmulti": "^3.0.28",
-    "@thi.ng/logger": "^3.0.4",
-    "@thi.ng/math": "^5.10.4",
-    "@thi.ng/shader-ast": "^0.13.16"
+    "@thi.ng/api": "^8.9.28",
+    "@thi.ng/defmulti": "^3.0.29",
+    "@thi.ng/errors": "^2.4.20",
+    "@thi.ng/logger": "^3.0.5",
+    "@thi.ng/math": "^5.10.5",
+    "@thi.ng/shader-ast": "^0.15.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
@@ -69,13 +71,16 @@
     ".": {
       "default": "./index.js"
     },
-    "./contant-folding": {
-      "default": "./contant-folding.js"
+    "./constant-folding": {
+      "default": "./constant-folding.js"
+    },
+    "./defoptimized": {
+      "default": "./defoptimized.js"
     }
   },
   "thi.ng": {
     "parent": "@thi.ng/shader-ast",
     "year": 2019
   },
-  "gitHead": "df9e312af741d87e6b450afcfea6a6e381662b1e\n"
+  "gitHead": "a421058a65ba76608d94129ac29451bfedaf201c\n"
 }