pixel-data-js 0.0.3 → 0.1.0

package/src/ImageData/blit.ts

@@ -0,0 +1,145 @@
+import type { BlendColor32, Color32 } from '../_types'
+import { sourceOverColor32 } from './blend-modes'
+
+export type BlendImageDataOptions = {
+  dx?: number
+  dy?: number
+  sx?: number
+  sy?: number
+  sw?: number
+  sh?: number
+  opacity?: number
+  alpha?: number
+  mask?: Uint8Array | null
+  maskMode?: 'binary' | 'alpha'
+  blendFn?: BlendColor32
+}
+
+/**
+ * Blits source ImageData into a destination ImageData using 32-bit integer bitwise blending.
+ * * This function bypasses standard Canvas API limitations by operating directly on
+ * Uint32Array views. It supports various blend modes, binary/alpha masking, and
+ * automatic clipping of both source and destination bounds.
+ * * @param dst - The destination ImageData to write into.
+ * @param src - The source ImageData to read from.
+ * @param dst - The destination ImageData to write to.
+ * @param opts - Configuration for the blit operation.
+ * @param opts.dx - Destination X offset. Defaults to 0.
+ * @param opts.dy - Destination Y offset. Defaults to 0.
+ * @param opts.sx - Source X offset. Defaults to 0.
+ * @param opts.sy - Source Y offset. Defaults to 0.
+ * @param opts.sw - Width of the source area to blit. Defaults to src.width.
+ * @param opts.sh - Height of the source area to blit. Defaults to src.height.
+ * @param opts.opacity - Global strength of the blit (0.0 to 1.0). Defaults to 1.0.
+ * @param opts.alpha - Global strength of the blit (0 to 255). Overrides 'opacity' if provided.
+ * @param opts.mask - An optional Uint8Array acting as a stencil or alpha mask.
+ * Must match source dimensions.
+ * @param opts.maskMode - 'binary' ignores pixels where mask is 0.
+ * 'alpha' scales source alpha by mask value (0-255).
+ * @param opts.blendFn - The math logic used to combine pixels.
+ * Defaults to `sourceOverColor32`.
+ * * @example
+ * blendImageData32(ctx.getImageData(0,0,100,100), sprite, {
+ * blendFn: COLOR_32_BLEND_MODES.multiply,
+ * mask: brushMask,
+ * maskMode: 'alpha'
+ * });
+ */
+export function blendImageData(
+  dst: ImageData,
+  src: ImageData,
+  opts: BlendImageDataOptions,
+) {
+  let {
+    dx = 0,
+    dy = 0,
+    sx = 0,
+    sy = 0,
+    sw = src.width,
+    sh = src.height,
+    maskMode = 'alpha',
+    opacity = 1,
+    alpha,
+    blendFn = sourceOverColor32,
+    mask,
+  } = opts
+
+  // 1. Clip Source Area
+  if (sx < 0) {
+    dx -= sx
+    sw += sx
+    sx = 0
+  }
+  if (sy < 0) {
+    dy -= sy
+    sh += sy
+    sy = 0
+  }
+  sw = Math.min(sw, src.width - sx)
+  sh = Math.min(sh, src.height - sy)
+
+  // 2. Clip Destination Area
+  if (dx < 0) {
+    sx -= dx
+    sw += dx
+    dx = 0
+  }
+  if (dy < 0) {
+    sy -= dy
+    sh += dy
+    dy = 0
+  }
+  const actualW = Math.min(sw, dst.width - dx)
+  const actualH = Math.min(sh, dst.height - dy)
+
+  if (actualW <= 0 || actualH <= 0) return
+
+  // 32-bit views of the same memory
+  const dst32 = new Uint32Array(dst.data.buffer)
+  const src32 = new Uint32Array(src.data.buffer)
+
+  const dw = dst.width
+  const sw_orig = src.width
+
+  const gAlpha = alpha !== undefined
+    ? (alpha | 0)
+    : Math.round(opacity * 255)
+
+  const maskIsAlpha = maskMode === 'alpha'
+
+  for (let iy = 0; iy < actualH; iy++) {
+    const dRow = (iy + dy) * dw
+    const sRow = (iy + sy) * sw_orig
+
+    for (let ix = 0; ix < actualW; ix++) {
+      const di = dRow + (ix + dx)
+      const si = sRow + (ix + sx)
+
+      let s = src32[si] as Color32
+      let sa = (s >>> 24) & 0xFF
+
+      // skip fully transparent pixel
+      if (sa === 0) continue
+
+      let activeWeight = gAlpha
+
+      if (mask) {
+        const m = mask[si]
+        if (m === 0) continue
+        activeWeight = maskIsAlpha ? (m * activeWeight + 128) >> 8 : activeWeight
+      }
+
+      if (activeWeight < 255) {
+        sa = (sa * activeWeight + 128) >> 8
+      }
+
+      // If combined alpha is 0 after masking/opacity, skip the blend math
+      if (sa === 0) continue
+
+      // Re-pack source with final calculated alpha
+      s = ((s & 0x00FFFFFF) | (sa << 24)) >>> 0 as Color32
+
+      dst32[di] = blendFn(s, dst32[di] as Color32)
+    }
+  }
+}

package/src/_types.ts

@@ -7,6 +7,8 @@ export type Color32 = number & { readonly __brandColor32: unique symbol };
 // ALL values are floats from 0-1
 export type RGBAFloat = RGBA & { readonly __brandRGBAFloat: unique symbol }
 
+export type BlendColor32 = (src: Color32, dst: Color32) => Color32;
+
 export type ImageDataLike = {
   width: number
   height: number

package/src/color.ts

@@ -45,13 +45,46 @@ export function colorDistance(a: Color32, b: Color32): number {
   return dr * dr + dg * dg + db * db + da * da
 }
 
+/**
+ * Linearly interpolates between two 32-bit colors using a floating-point weight.
+ * * This is the preferred method for UI animations or scenarios where high
+ * precision is required. It uses the standard `a + t * (b - a)` formula
+ * for each channel.
+ * @param a - The starting color as a 32-bit integer (AABBGGRR).
+ * @param b - The target color as a 32-bit integer (AABBGGRR).
+ * @param t - The interpolation factor between 0.0 and 1.0.
+ * @returns The interpolated 32-bit color.
+ */
 export function lerpColor32(a: Color32, b: Color32, t: number): Color32 {
   const r = (a & 0xFF) + t * ((b & 0xFF) - (a & 0xFF))
   const g = ((a >>> 8) & 0xFF) + t * (((b >>> 8) & 0xFF) - ((a >>> 8) & 0xFF))
   const b_ = ((a >>> 16) & 0xFF) + t * (((b >>> 16) & 0xFF) - ((a >>> 16) & 0xFF))
   const a_ = ((a >>> 24) & 0xFF) + t * (((b >>> 24) & 0xFF) - ((a >>> 24) & 0xFF))
 
-  return packColor(r, g, b_, a_)
+  return ((a_ << 24) | (b_ << 16) | (g << 8) | r) >>> 0 as Color32
+}
+
+/**
+ * Linearly interpolates between two 32-bit colors using integer fixed-point math.
+ * Highly optimized for image processing and real-time blitting. It processes
+ * channels in parallel using bitmasks (RB and GA pairs).
+ * @note Subject to a 1-bit drift (rounding down) due to fast bit-shift division.
+ * @param src - The source (foreground) color as a 32-bit integer.
+ * @param dst - The destination (background) color as a 32-bit integer.
+ * @param w - The blend weight as a byte value from 0 to 255. Where 0 is 100% dst and 255 is 100% src
+ * @returns The blended 32-bit color.
+ */export function lerpColor32Fast(src: Color32, dst: Color32, w: number): Color32 {
+  const invA = 255 - w;
+
+  // Masking Red and Blue: 0x00FF00FF
+  // We process R and B in one go, then shift back down
+  const rb = (((src & 0x00FF00FF) * w + (dst & 0x00FF00FF) * invA) >>> 8) & 0x00FF00FF;
+
+  // Masking Green and Alpha: 0xFF00FF00
+  // We shift down first to avoid overflow, then shift back up
+  const ga = ((((src >>> 8) & 0x00FF00FF) * w + ((dst >>> 8) & 0x00FF00FF) * invA) >>> 8) & 0x00FF00FF;
+
+  return (rb | (ga << 8)) >>> 0 as Color32;
 }
 
 // Convert 0xAABBGGRR to #RRGGBBAA

package/src/index.ts

@@ -1 +1,5 @@
+export * from './color'
 export * from './ImageData/serialization'
+export * from './ImageData/blit'
+export * from './ImageData/blend-modes'
+export * from './ImageData/read-write-pixels'