@thi.ng/shader-ast-stdlib 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-06T08:50:42Z
+- **Last updated**: 2024-03-09T09:18:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,14 @@ 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.18.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/shader-ast-stdlib@0.18.0) (2024-03-07)
+
+#### 🚀 Features
+
+- add packFloat()/unpackFloat() ([23a6d7f](https://github.com/thi-ng/umbrella/commit/23a6d7f))
+- add packedNormal2(), refactor normal2() ([6f6dc1d](https://github.com/thi-ng/umbrella/commit/6f6dc1d))
+- add branches() n-ary helper fn & docs ([74f32ba](https://github.com/thi-ng/umbrella/commit/74f32ba))
+
 ## [0.17.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/shader-ast-stdlib@0.17.0) (2024-03-06)
 
 #### 🚀 Features

package/README.md

@@ -109,7 +109,7 @@ For Node.js REPL:
 const shaderAstStdlib = await import("@thi.ng/shader-ast-stdlib");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 13.67 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 13.93 KB
 
 ## Dependencies
 
@@ -136,6 +136,7 @@ directory are using this package:
 |                                                                                                                              | Minimal multi-pass / GPGPU example                                 | [Demo](https://demo.thi.ng/umbrella/webgl-multipass/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-multipass)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/webgl-shadertoy.jpg" width="240"/>       | Shadertoy-like WebGL setup                                         | [Demo](https://demo.thi.ng/umbrella/webgl-shadertoy/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-shadertoy)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/webgl-ssao.jpg" width="240"/>            | WebGL screenspace ambient occlusion                                | [Demo](https://demo.thi.ng/umbrella/webgl-ssao/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-ssao)          |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/webgl-texture-paint.jpg" width="240"/>   | TODO                                                               | [Demo](https://demo.thi.ng/umbrella/webgl-texture-paint/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-texture-paint) |
 
 ## API
 
@@ -408,6 +409,7 @@ Related:
 - `minComp2` / `minComp3` / `minComp4`
 - `perpendicularCCW` / `perpendicularCW`
 - `orthogonal3`
+- `packFloat` / `unpackFloat`
 - `polar2` / `polar3`
 - `sincos` / `cossin`
 - `smootherStep` / `smootherStep2` / `smootherStep3` / `smootherStep4`
@@ -528,7 +530,7 @@ Related:
 
 - `indexToCoord` / `coordToIndex`
 - `indexToUV` / `uvToIndex`
-- `normal2`
+- `normal2` / `packedNormal2`
 - `readIndex1` / `readIndex2` / `readIndex3` / `readIndex4`
 
 ### Visualization

package/color/porter-duff.d.ts

@@ -11,6 +11,17 @@ import type { FloatTerm, Vec4Sym } from "@thi.ng/shader-ast";
  * functions are used to extract blending coefficients for src/dest colors and
  * are called with the alpha components of both colors.
  *
+ * - `blendSrcOver(src, dest)`
+ * - `blendDestOver(src, dest)`
+ * - `blendSrcIn(src, dest)`
+ * - `blendDestIn(src, dest)`
+ * - `blendSrcOut(src, dest)`
+ * - `blendDestOut(src, dest)`
+ * - `blendSrcAtop(src, dest)`
+ * - `blendDestAtop(src, dest)`
+ * - `blendXor(src, dest)`
+ * - `blendPlus(src, dest)`
+ *
  * Optimization only happens for cases where either `fa` and/or `fb` are
  * {@link ZERO} or {@link ONE}.
  *
@@ -23,7 +34,19 @@ import type { FloatTerm, Vec4Sym } from "@thi.ng/shader-ast";
  * @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">;
+/**
+ * Multiplies RGB channels by alpha. Returns `vec4(col.r*col.a, col.g*col.a,
+ * col.b*col.a, col.a)`. See {@link postmultiplyAlpha} for reverse op.
+ *
+ * @param col
+ */
 export declare const premultiplyAlpha: (col: Vec4Sym) => import("@thi.ng/shader-ast").Lit<"vec4">;
+/**
+ * Divides RGB channels by alpha. Returns `vec4(col.r/col.a, col.g/col.a,
+ * col.b/col.a, col.a)`. See {@link premultiplyAlpha} for reverse op.
+ *
+ * @param col
+ */
 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">;

package/controlflow/branches.d.ts

@@ -0,0 +1,53 @@
+import type { FloatTerm, Term, Type } from "@thi.ng/shader-ast";
+/**
+ * Utility function to create an n-ary conditional based on given float value
+ * `x` in [0,1] range and any number of branch terms (at least 1). Returns a
+ * nested ternary expression.
+ *
+ * @remarks
+ * This function is useful for A/B testing of multiple versions of a shader,
+ * e.g. the popular technique of using columns based on the `gl_FragCoord.x` and
+ * dynamically computed column thresholds (defined by the number of given branch
+ * terms).
+ *
+ * @example
+ * ```ts tangle:../../export/branches.ts
+ * import { float, sym, vec3 } from "@thi.ng/shader-ast";
+ * import { branches } from "@thi.ng/shader-ast-stdlib";
+ * import { targetGLSL } from "@thi.ng/shader-ast-glsl";
+ *
+ * // dummy "position" symbol (would be gl_FragCoord.x or similar)
+ * const pos = sym(float(0.11));
+ *
+ * // serialize expression to GLSL for better legibility
+ * console.log(
+ *   targetGLSL()(
+ *     branches(
+ *       pos,
+ *       // branch terms/options...
+ *       // branch thresholds are automatically computed
+ *       // making it trivial to add/remove terms
+ *       vec3(1,0,0),
+ *       vec3(1,1,0),
+ *       vec3(0,1,0),
+ *       vec3(0,0,1),
+ *     )
+ *   )
+ * );
+ *
+ * // re-formatted result:
+ * // ((_sf5 < 0.25)
+ * //   ? vec3(1.0, 0.0, 0.0)
+ * //   : ((_sf5 < 0.5)
+ * //   ? vec3(1.0, 1.0, 0.0)
+ * //   : ((_sf5 < 0.75)
+ * //   ? vec3(0.0, 1.0, 0.0)
+ * //   : vec3(0.0, 0.0, 1.0))))
+ * ```
+ *
+ * @param x
+ * @param a
+ * @param terms
+ */
+export declare const branches: <T extends Type>(x: FloatTerm, a: Term<T>, ...terms: Term<T>[]) => Term<T>;
+//# sourceMappingURL=branches.d.ts.map

package/controlflow/branches.js

@@ -0,0 +1,16 @@
+import { ternary } from "@thi.ng/shader-ast/ast/controlflow";
+import { float } from "@thi.ng/shader-ast/ast/lit";
+import { lt } from "@thi.ng/shader-ast/ast/ops";
+const branches = (x, a, ...terms) => {
+  const n = terms.length + 1;
+  if (n < 2)
+    return a;
+  const delta = 1 / n;
+  terms = [a, ...terms];
+  return terms.reduceRight(
+    (acc, t, i) => ternary(lt(x, float((i + 1) * delta)), t, acc)
+  );
+};
+export {
+  branches
+};

package/index.d.ts

@@ -6,6 +6,7 @@ export * from "./color/linear-srgb.js";
 export * from "./color/luminance.js";
 export * from "./color/porter-duff.js";
 export * from "./color/rgbe.js";
+export * from "./controlflow/branches.js";
 export * from "./fog/exp.js";
 export * from "./fog/exp2.js";
 export * from "./fog/linear.js";
@@ -27,6 +28,7 @@ export * from "./math/mix-cubic.js";
 export * from "./math/mix-quadratic.js";
 export * from "./math/orthogonal.js";
 export * from "./math/osc.js";
+export * from "./math/pack-float.js";
 export * from "./math/polar.js";
 export * from "./math/sincos.js";
 export * from "./math/smoother-step.js";

package/index.js

@@ -6,6 +6,7 @@ export * from "./color/linear-srgb.js";
 export * from "./color/luminance.js";
 export * from "./color/porter-duff.js";
 export * from "./color/rgbe.js";
+export * from "./controlflow/branches.js";
 export * from "./fog/exp.js";
 export * from "./fog/exp2.js";
 export * from "./fog/linear.js";
@@ -27,6 +28,7 @@ export * from "./math/mix-cubic.js";
 export * from "./math/mix-quadratic.js";
 export * from "./math/orthogonal.js";
 export * from "./math/osc.js";
+export * from "./math/pack-float.js";
 export * from "./math/polar.js";
 export * from "./math/sincos.js";
 export * from "./math/smoother-step.js";

package/math/pack-float.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Encodes a float value in [0,1) interval to a vec4 suitable for a 8bit/channel
+ * render texture. Use {@link unpackFloat} for reverse op.
+ *
+ * @remarks
+ * Reference:
+ * https://aras-p.info/blog/2009/07/30/encoding-floats-to-rgba-the-final/
+ */
+export declare const packFloat: import("@thi.ng/shader-ast").TaggedFn1<"float", "vec4">;
+/**
+ * Reverse op of {@link packFloat}.
+ *
+ * @remarks
+ * Also see {@link packedNormal2} for related functionality.
+ *
+ * Reference:
+ * https://aras-p.info/blog/2009/07/30/encoding-floats-to-rgba-the-final/
+ */
+export declare const unpackFloat: import("@thi.ng/shader-ast").TaggedFn1<"vec4", "float">;
+//# sourceMappingURL=pack-float.d.ts.map

package/math/pack-float.js

@@ -0,0 +1,21 @@
+import { F, V4 } from "@thi.ng/shader-ast/api/types";
+import { defn, ret } from "@thi.ng/shader-ast/ast/function";
+import { vec4 } from "@thi.ng/shader-ast/ast/lit";
+import { mul, sub } from "@thi.ng/shader-ast/ast/ops";
+import { $ } from "@thi.ng/shader-ast/ast/swizzle";
+import { sym } from "@thi.ng/shader-ast/ast/sym";
+import { dot, fract } from "@thi.ng/shader-ast/builtin/math";
+const packFloat = defn(V4, null, [F], (x) => {
+  let res;
+  return [
+    res = sym(fract(mul(vec4(1, 255, 65025, 16581375), x))),
+    ret(sub(res, mul($(res, "yzww"), vec4(1 / 255, 1 / 255, 1 / 255, 0))))
+  ];
+});
+const unpackFloat = defn(F, null, [V4], (v) => [
+  ret(dot(v, vec4(1, 1 / 255, 1 / 65025, 1 / 16581375)))
+]);
+export {
+  packFloat,
+  unpackFloat
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/shader-ast-stdlib",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Function collection for modular GPGPU / shader programming with @thi.ng/shader-ast",
   "type": "module",
   "module": "./index.js",
@@ -35,11 +35,12 @@
     "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/shader-ast": "^0.14.0"
+    "@thi.ng/api": "^8.9.29",
+    "@thi.ng/shader-ast": "^0.15.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
@@ -85,6 +86,7 @@
     "./*.js",
     "./*.d.ts",
     "color",
+    "controlflow",
     "fog",
     "isec",
     "light",
@@ -125,6 +127,9 @@
     "./color/rgbe": {
       "default": "./color/rgbe.js"
     },
+    "./controlflow/branches": {
+      "default": "./controlflow/branches.js"
+    },
     "./fog/exp": {
       "default": "./fog/exp.js"
     },
@@ -191,6 +196,9 @@
     "./math/osc": {
       "default": "./math/osc.js"
     },
+    "./math/pack-float": {
+      "default": "./math/pack-float.js"
+    },
     "./math/polar": {
       "default": "./math/polar.js"
     },
@@ -363,5 +371,5 @@
     ],
     "year": 2019
   },
-  "gitHead": "f6bb0e172c5dcb574b961f5155a50040d5569685\n"
+  "gitHead": "69100942474942f7446ac645d59d91e7dfc352f9\n"
 }

package/tex/normal.d.ts

@@ -15,4 +15,17 @@
  * @param eps
  */
 export declare const normal2: import("@thi.ng/shader-ast").TaggedFn5<"sampler2D", "vec2", "vec2", "float", "float", "vec3">;
+/**
+ * Principally the same as {@link normal2}, but using a RGBA 8bit/channel
+ * texture storing float values encoded using {@link packFloat}. WHen
+ * `packedNormal2()` then samples this textures, each value will be
+ * automatically decoded using {@link unpackFloat}.
+ *
+ * @param tex
+ * @param uv
+ * @param step
+ * @param z
+ * @param eps
+ */
+export declare const packedNormal2: import("@thi.ng/shader-ast").TaggedFn5<"sampler2D", "vec2", "vec2", "float", "float", "vec3">;
 //# sourceMappingURL=normal.d.ts.map

package/tex/normal.js

@@ -2,32 +2,34 @@ import { F, S2D, V2, V3 } from "@thi.ng/shader-ast/api/types";
 import { defn, ret } from "@thi.ng/shader-ast/ast/function";
 import { vec2, vec3 } from "@thi.ng/shader-ast/ast/lit";
 import { add, sub } from "@thi.ng/shader-ast/ast/ops";
-import { sym } from "@thi.ng/shader-ast/ast/sym";
 import { $x, $y } from "@thi.ng/shader-ast/ast/swizzle";
+import { sym } from "@thi.ng/shader-ast/ast/sym";
 import { normalize } from "@thi.ng/shader-ast/builtin/math";
 import { texture } from "@thi.ng/shader-ast/builtin/texture";
-const sample1 = (tex, uv, unit) => sub($x(texture(tex, sub(uv, unit))), $x(texture(tex, add(uv, unit))));
-const normal2 = defn(
-  V3,
-  null,
-  [S2D, V2, V2, F, F],
-  (tex, uv, step, z, eps) => {
-    let sx;
-    let sy;
-    return [
-      sx = sym(vec2($x(step), 0)),
-      sy = sym(vec2(0, $y(step))),
-      ret(
-        normalize(
-          add(
-            vec3(sample1(tex, uv, sx), sample1(tex, uv, sy), z),
-            eps
-          )
+import { unpackFloat } from "../math/pack-float.js";
+const __defNormal2 = (decode) => defn(V3, null, [S2D, V2, V2, F, F], (tex, uv, step, z, eps) => {
+  let sx;
+  let sy;
+  const sample1 = (tex2, uv2, unit) => sub(
+    decode(texture(tex2, sub(uv2, unit))),
+    decode(texture(tex2, add(uv2, unit)))
+  );
+  return [
+    sx = sym(vec2($x(step), 0)),
+    sy = sym(vec2(0, $y(step))),
+    ret(
+      normalize(
+        add(
+          vec3(sample1(tex, uv, sx), sample1(tex, uv, sy), z),
+          eps
         )
       )
-    ];
-  }
-);
+    )
+  ];
+});
+const normal2 = __defNormal2($x);
+const packedNormal2 = __defNormal2(unpackFloat);
 export {
-  normal2
+  normal2,
+  packedNormal2
 };