@thi.ng/rasterize 0.3.20 → 1.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-09-21T21:37:59Z
+- **Last updated**: 2022-10-03T16:07:55Z
 - **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.
 
+# [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rasterize@1.0.0) (2022-09-27)
+
+#### 🛑 Breaking changes
+
+- add defBlendF/I shader fns, update Shader2D ([4656c50](https://github.com/thi-ng/umbrella/commit/4656c50))
+- BREAKING CHANGE: update Shader2D args
+  - add [@thi.ng/porter-duff](https://github.com/thi-ng/umbrella/tree/main/packages/porter-duff) dependency
+  - update Shader2D args, pass target buffer as new initial arg
+  - add `defBlendF()`/`defBlendI()` shader fns for PD blend ops
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rasterize@0.3.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -1,6 +1,6 @@
 <!-- This file is generated - DO NOT EDIT! -->
 
-# ![rasterize](https://media.thi.ng/umbrella/banners-20220914/thing-rasterize.svg?6dbe9c48)
+# ![rasterize](https://media.thi.ng/umbrella/banners-20220914/thing-rasterize.svg?75411efe)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/rasterize.svg)](https://www.npmjs.com/package/@thi.ng/rasterize)
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/rasterize.svg)
@@ -20,6 +20,7 @@ This project is part of the
 - [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
 - [Authors](#authors)
 - [License](#license)
@@ -153,7 +154,7 @@ node --experimental-repl-await
 > const rasterize = await import("@thi.ng/rasterize");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.45 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.59 KB
 
 ## Dependencies
 
@@ -161,9 +162,22 @@ Package sizes (gzipped, pre-treeshake): ESM: 1.45 KB
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/equiv](https://github.com/thi-ng/umbrella/tree/develop/packages/equiv)
 - [@thi.ng/grid-iterators](https://github.com/thi-ng/umbrella/tree/develop/packages/grid-iterators)
+- [@thi.ng/porter-duff](https://github.com/thi-ng/umbrella/tree/develop/packages/porter-duff)
 - [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random)
 - [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
 
+## Usage examples
+
+Several demos in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory are using this package.
+
+A selection:
+
+| Screenshot                                                                                                             | Description                                         | Live demo                                             | Source                                                                             |
+|:-----------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------|:------------------------------------------------------|:-----------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rasterize-blend.jpg" width="240"/> | Steering behavior drawing with alpha-blended shapes | [Demo](https://demo.thi.ng/umbrella/rasterize-blend/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rasterize-blend) |
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/rasterize/)

package/api.d.ts

@@ -1,3 +1,3 @@
-import type { Fn2 } from "@thi.ng/api";
-export declare type Shader2D<T> = Fn2<number, number, T>;
+import type { Fn3, IGrid2D } from "@thi.ng/api";
+export declare type Shader2D<T> = Fn3<IGrid2D<any, T>, number, number, T>;
 //# sourceMappingURL=api.d.ts.map

package/draw.js

@@ -28,12 +28,12 @@ export const __drawShader2D = (pts, grid, shader) => {
     if (isPrimitive(grid.getAtUnsafe(0, 0))) {
         const { data, offset, stride: [sx, sy], } = grid;
         for (let { 0: x, 1: y } of pts) {
-            data[offset + x * sx + y * sy] = shader(x, y);
+            data[offset + x * sx + y * sy] = shader(grid, x, y);
         }
     }
     else {
         for (let { 0: x, 1: y } of pts) {
-            grid.setAtUnsafe(x, y, shader(x, y));
+            grid.setAtUnsafe(x, y, shader(grid, x, y));
         }
     }
     return grid;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rasterize",
-  "version": "0.3.20",
+  "version": "1.0.1",
   "description": "2D shape drawing & rasterization",
   "type": "module",
   "module": "./index.js",
@@ -34,16 +34,17 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.4.2",
-    "@thi.ng/checks": "^3.2.5",
-    "@thi.ng/equiv": "^2.1.10",
-    "@thi.ng/grid-iterators": "^2.3.13",
-    "@thi.ng/random": "^3.3.8",
-    "@thi.ng/transducers": "^8.3.14"
+    "@thi.ng/api": "^8.4.3",
+    "@thi.ng/checks": "^3.2.6",
+    "@thi.ng/equiv": "^2.1.11",
+    "@thi.ng/grid-iterators": "^2.3.15",
+    "@thi.ng/porter-duff": "^2.1.14",
+    "@thi.ng/random": "^3.3.9",
+    "@thi.ng/transducers": "^8.3.16"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.31.1",
-    "@thi.ng/testament": "^0.3.0",
+    "@thi.ng/testament": "^0.3.1",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
@@ -118,5 +119,5 @@
     "status": "alpha",
     "year": 2021
   },
-  "gitHead": "973139c5aa3b50081020f4cc726a7cc330f77fc7\n"
+  "gitHead": "8600007d81a7dc92634a1d54e2c32b14ab30ba80\n"
 }

package/poly.js

@@ -59,7 +59,7 @@ export const fillPoly = (grid, pts, val) => {
                 x1 < minX && (x1 = minX);
                 x2 > maxX && (x2 = maxX);
                 for (let x = x1; x <= x2; x++) {
-                    grid.setAtUnsafe(x, y, shader(x, y));
+                    grid.setAtUnsafe(x, y, shader(grid, x, y));
                 }
             }
         }

package/rect.js

@@ -25,14 +25,14 @@ export const drawRect = (grid, x, y, w, h, val, fill = false) => {
             for (let { 0: xx, 1: yy } of pts) {
                 xx += x;
                 yy += y;
-                data[offset + xx * sx + yy * sy] = shader(xx, yy);
+                data[offset + xx * sx + yy * sy] = shader(grid, xx, yy);
             }
         }
         else {
             for (let { 0: xx, 1: yy } of pts) {
                 xx += x;
                 yy += y;
-                grid.setAtUnsafe(xx, yy, shader(xx, yy));
+                grid.setAtUnsafe(xx, yy, shader(grid, xx, yy));
             }
         }
         return grid;

package/shader.d.ts

@@ -1,4 +1,5 @@
-import type { IGrid2D, TypedArray } from "@thi.ng/api";
+import type { IGrid2D, NumericArray, TypedArray } from "@thi.ng/api";
+import type { BlendFnF, BlendFnI, ReadonlyColor } from "@thi.ng/porter-duff";
 import type { IRandom } from "@thi.ng/random";
 import type { Shader2D } from "./api.js";
 export declare const defPattern: <T extends any[] | TypedArray, P>(pattern: IGrid2D<T, P>) => Shader2D<P>;
@@ -17,4 +18,36 @@ export interface RandomShaderOpts<T> {
     b: T;
 }
 export declare const defNoise: <T = number>(opts: RandomShaderOpts<T>) => Shader2D<T>;
+/**
+ * Defines a shader (for floating point target buffers) which blends given color
+ * (or another shader) with a Porter-Duff operator. Unless `isPremultiplied` is
+ * true, both the given color and existing pixel values in the target buffer are
+ * considered non-premultiplied.
+ *
+ * @remarks
+ * The default PD blend op is `SRC_OVER_I`. See
+ * [@thi.ng/porter-duff](https://thi.ng/porter-duff) for more info.
+ *
+ * See {@link defBlendI} for integer based buffers.
+ *
+ * @param col
+ * @param blend
+ * @param isPremultiplied
+ */
+export declare const defBlendF: (col: ReadonlyColor | Shader2D<NumericArray>, blend?: BlendFnF, isPremultiplied?: boolean) => Shader2D<NumericArray>;
+/**
+ * Similar to {@link defBlendF}, but for integer based target buffers. Defines a
+ * shader which blends given color (or another shader) with a Porter-Duff
+ * operator. Unless `isPremultiplied` is true, both the given color and existing
+ * pixel values in the target buffer are considered non-premultiplied.
+ *
+ * @remarks
+ * The default PD blend op is `SRC_OVER_I`. See
+ * [@thi.ng/porter-duff](https://thi.ng/porter-duff) for more info.
+ *
+ * @param col
+ * @param blend
+ * @param isPremultiplied
+ */
+export declare const defBlendI: (col: number | Shader2D<number>, blend?: BlendFnI, isPremultiplied?: boolean) => Shader2D<number>;
 //# sourceMappingURL=shader.d.ts.map

package/shader.js

@@ -1,13 +1,15 @@
+import { isFunction } from "@thi.ng/checks/is-function";
+import { porterDuffP, porterDuffPInt, SRC_OVER_F, SRC_OVER_I, } from "@thi.ng/porter-duff/porter-duff";
 import { SYSTEM } from "@thi.ng/random/system";
 export const defPattern = (pattern) => {
     const [w, h] = pattern.size;
-    return (x, y) => pattern.getAtUnsafe(x % w, y % h);
+    return (_, x, y) => pattern.getAtUnsafe(x % w, y % h);
 };
 export const defStripes = ({ dir, size, sizeA, a, b, }) => dir === "h"
-    ? (x) => (x % size < sizeA ? a : b)
+    ? (_, x) => (x % size < sizeA ? a : b)
     : dir === "v"
-        ? (_, y) => (y % size < sizeA ? a : b)
-        : (x, y) => ((x + y) % size < sizeA ? a : b);
+        ? (_, __, y) => (y % size < sizeA ? a : b)
+        : (_, x, y) => ((x + y) % size < sizeA ? a : b);
 export const defNoise = (opts) => {
     const { probability, rnd, a, b } = {
         probability: 0.5,
@@ -16,3 +18,51 @@ export const defNoise = (opts) => {
     };
     return () => (rnd.float() < probability ? a : b);
 };
+/**
+ * Defines a shader (for floating point target buffers) which blends given color
+ * (or another shader) with a Porter-Duff operator. Unless `isPremultiplied` is
+ * true, both the given color and existing pixel values in the target buffer are
+ * considered non-premultiplied.
+ *
+ * @remarks
+ * The default PD blend op is `SRC_OVER_I`. See
+ * [@thi.ng/porter-duff](https://thi.ng/porter-duff) for more info.
+ *
+ * See {@link defBlendI} for integer based buffers.
+ *
+ * @param col
+ * @param blend
+ * @param isPremultiplied
+ */
+export const defBlendF = (col, blend = SRC_OVER_F, isPremultiplied = false) => {
+    blend = isPremultiplied ? blend : porterDuffP(blend);
+    return isFunction(col)
+        ? (buf, x, y) => {
+            const dest = buf.getAtUnsafe(x, y);
+            return blend(dest, col(buf, x, y), dest);
+        }
+        : (buf, x, y) => {
+            const dest = buf.getAtUnsafe(x, y);
+            return blend(dest, col, dest);
+        };
+};
+/**
+ * Similar to {@link defBlendF}, but for integer based target buffers. Defines a
+ * shader which blends given color (or another shader) with a Porter-Duff
+ * operator. Unless `isPremultiplied` is true, both the given color and existing
+ * pixel values in the target buffer are considered non-premultiplied.
+ *
+ * @remarks
+ * The default PD blend op is `SRC_OVER_I`. See
+ * [@thi.ng/porter-duff](https://thi.ng/porter-duff) for more info.
+ *
+ * @param col
+ * @param blend
+ * @param isPremultiplied
+ */
+export const defBlendI = (col, blend = SRC_OVER_I, isPremultiplied = false) => {
+    blend = isPremultiplied ? blend : porterDuffPInt(blend);
+    return isFunction(col)
+        ? (buf, x, y) => blend(col(buf, x, y), buf.getAtUnsafe(x, y))
+        : (buf, x, y) => blend(col, buf.getAtUnsafe(x, y));
+};