pixel-data-js 0.2.0 → 0.4.0

package/src/PixelData/applyMaskToPixelData.ts

@@ -0,0 +1,129 @@
+import { type AnyMask, type ApplyMaskOptions, MaskType } from '../_types'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Directly applies a mask to a region of PixelData,
+ * modifying the destination's alpha channel in-place.
+ */
+export function applyMaskToPixelData(
+  dst: PixelData,
+  mask: AnyMask,
+  opts: ApplyMaskOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha: globalAlpha = 255,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // Clipping Logic
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0 || globalAlpha === 0) {
+    return
+  }
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const mPitch = mw ?? width
+  const isAlpha = maskType === MaskType.ALPHA
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const mStride = mPitch - actualW
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+      const mVal = mask[mIdx]
+      let weight = globalAlpha
+
+      if (isAlpha) {
+        const effectiveM = invertMask
+          ? 255 - mVal
+          : mVal
+
+        // Short-circuit: if source is 0, destination alpha becomes 0
+        if (effectiveM === 0) {
+          dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        weight = globalAlpha === 255
+          ? effectiveM
+          : (effectiveM * globalAlpha + 128) >> 8
+      } else {
+        // Strict Binary 1/0 Logic
+        const isHit = invertMask
+          ? mVal === 0
+          : mVal === 1
+
+        if (!isHit) {
+          dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        weight = globalAlpha
+      }
+
+      // If calculated weight is 0, clear alpha
+      if (weight === 0) {
+        dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+      } else {
+        const d = dst32[dIdx]
+        const da = (d >>> 24)
+
+        let finalAlpha = da
+
+        if (da === 0) {
+          // Already transparent
+        } else if (weight === 255) {
+          // Identity: keep original da
+        } else if (da === 255) {
+          // Identity: result is just the weight
+          finalAlpha = weight
+        } else {
+          finalAlpha = (da * weight + 128) >> 8
+        }
+
+        dst32[dIdx] = ((d & 0x00ffffff) | (finalAlpha << 24)) >>> 0
+      }
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/blendColorPixelData.ts

@@ -0,0 +1,157 @@
+import { type Color32, type ColorBlendOptions, MaskType } from '../_types'
+import { sourceOverColor32 } from '../blend-modes'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Fills a rectangle in the destination PixelData with a single color,
+ * supporting blend modes, global alpha, and masking.
+ */
+export function blendColorPixelData(
+  dst: PixelData,
+  color: Color32,
+  opts: ColorBlendOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha: globalAlpha = 255,
+    blendFn = sourceOverColor32,
+    mask,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (globalAlpha === 0) return
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // 1. Destination Clipping
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) return
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const mPitch = mw ?? width
+  const isAlphaMask = maskType === MaskType.ALPHA
+
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const mStride = mPitch - actualW
+
+  // Pre-calculate the source color with global alpha
+  const baseSrcColor = color
+  const baseSrcAlpha = (baseSrcColor >>> 24)
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+
+      // Early exit if source pixel is already transparent
+      if (baseSrcAlpha === 0) {
+        dIdx++
+        mIdx++
+        continue
+      }
+
+      let weight = globalAlpha
+
+      if (mask) {
+        const mVal = mask[mIdx]
+
+        if (isAlphaMask) {
+        const effectiveM = invertMask
+          ? 255 - mVal
+          : mVal
+
+        // If mask is transparent, skip
+        if (effectiveM === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+
+          // globalAlpha is not a factor
+          if (globalAlpha === 255) {
+            weight = effectiveM
+            // mask is not a factor
+          } else if (effectiveM === 255) {
+            weight = globalAlpha
+          } else {
+            // use rounding-corrected multiplication
+            weight = (effectiveM * globalAlpha + 128) >> 8
+          }
+        } else {
+          const isHit = invertMask
+            ? mVal === 0
+            : mVal === 1
+
+          if (!isHit) {
+            dIdx++
+            mIdx++
+            continue
+          }
+
+          weight = globalAlpha
+        }
+
+        // Final safety check for weight (can be 0 if globalAlpha or alphaMask rounds down)
+        if (weight === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+      }
+
+      // Apply Weight to Source Alpha
+      let currentSrcAlpha = baseSrcAlpha
+      let currentSrcColor = baseSrcColor
+
+      if (weight < 255) {
+        if (baseSrcAlpha === 255) {
+          currentSrcAlpha = weight
+        } else {
+          currentSrcAlpha = (baseSrcAlpha * weight + 128) >> 8
+        }
+
+        if (currentSrcAlpha === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        currentSrcColor = ((baseSrcColor & 0x00ffffff) | (currentSrcAlpha << 24)) >>> 0 as Color32
+      }
+
+      dst32[dIdx] = blendFn(currentSrcColor, dst32[dIdx] as Color32)
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/blendPixelData.ts

@@ -0,0 +1,196 @@
+import { type Color32, MaskType, type PixelBlendOptions } from '../_types'
+import { sourceOverColor32 } from '../blend-modes'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Blits source PixelData into a destination PixelData using 32-bit integer bitwise blending.
+ * This function bypasses standard ImageData limitations by operating directly on
+ * Uint32Array views. It supports various blend modes, binary/alpha masking, and
+ * automatic clipping of both source and destination bounds.
+ * @example
+ *
+ * const dst = new PixelData(ctx.getImageData(0,0,100,100))
+ * blendImageData32(dst, sprite, {
+ *   blendFn: COLOR_32_BLEND_MODES.multiply,
+ *   mask: brushMask,
+ *   maskType: MaskType.ALPHA
+ * });
+ */
+export function blendPixelData(
+  dst: PixelData,
+  src: PixelData,
+  opts: PixelBlendOptions,
+) {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    sx: sourceX = 0,
+    sy: sourceY = 0,
+    w: width = src.width,
+    h: height = src.height,
+    alpha: globalAlpha = 255,
+    blendFn = sourceOverColor32,
+    mask,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (globalAlpha === 0) return
+
+  let x = targetX
+  let y = targetY
+  let sx = sourceX
+  let sy = sourceY
+  let w = width
+  let h = height
+
+  // 1. Source Clipping
+  if (sx < 0) {
+    x -= sx
+    w += sx
+    sx = 0
+  }
+  if (sy < 0) {
+    y -= sy
+    h += sy
+    sy = 0
+  }
+  w = Math.min(w, src.width - sx)
+  h = Math.min(h, src.height - sy)
+
+  // 2. Destination Clipping
+  if (x < 0) {
+    sx -= x
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    sy -= y
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) return
+
+  const dst32 = dst.data32
+  const src32 = src.data32
+  const dw = dst.width
+  const sw = src.width
+  const mPitch = mw ?? width
+  const isAlphaMask = maskType === MaskType.ALPHA
+
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let sIdx = sy * sw + sx
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const sStride = sw - actualW
+  const mStride = mPitch - actualW
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+      const baseSrcColor = src32[sIdx] as Color32
+      const baseSrcAlpha = (baseSrcColor >>> 24)
+
+      // Early exit if source pixel is already transparent
+      if (baseSrcAlpha === 0) {
+        dIdx++
+        sIdx++
+        mIdx++
+        continue
+      }
+
+      let weight = globalAlpha
+
+      if (mask) {
+        const mVal = mask[mIdx]
+
+        if (isAlphaMask) {
+          const effectiveM = invertMask
+            ? 255 - mVal
+            : mVal
+
+          // If mask is transparent, skip
+          if (effectiveM === 0) {
+            dIdx++
+            sIdx++
+            mIdx++
+            continue
+          }
+
+          // globalAlpha is not a factor
+          if (globalAlpha === 255) {
+            weight = effectiveM
+            // mask is not a factor
+          } else if (effectiveM === 255) {
+            weight = globalAlpha
+          } else {
+            // use rounding-corrected multiplication
+            weight = (effectiveM * globalAlpha + 128) >> 8
+          }
+        } else {
+          const isHit = invertMask
+            ? mVal === 0
+            : mVal === 1
+
+          if (!isHit) {
+            dIdx++
+            sIdx++
+            mIdx++
+            continue
+          }
+
+          weight = globalAlpha
+        }
+
+        // Final safety check for weight (can be 0 if globalAlpha or alphaMask rounds down)
+        if (weight === 0) {
+          dIdx++
+          sIdx++
+          mIdx++
+          continue
+        }
+      }
+
+      // Apply Weight to Source Alpha
+      let currentSrcAlpha = baseSrcAlpha
+      let currentSrcColor = baseSrcColor
+
+      if (weight < 255) {
+        if (baseSrcAlpha === 255) {
+          currentSrcAlpha = weight
+        } else {
+          currentSrcAlpha = (baseSrcAlpha * weight + 128) >> 8
+        }
+
+        if (currentSrcAlpha === 0) {
+          dIdx++
+          sIdx++
+          mIdx++
+          continue
+        }
+
+        currentSrcColor = ((baseSrcColor & 0x00ffffff) | (currentSrcAlpha << 24)) >>> 0 as Color32
+      }
+
+      dst32[dIdx] = blendFn(currentSrcColor, dst32[dIdx] as Color32)
+
+      dIdx++
+      sIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    sIdx += sStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/clearPixelData.ts

@@ -0,0 +1,14 @@
+import type { Color32, Rect } from '../_types'
+import type { PixelData } from '../PixelData'
+import { fillPixelData } from './fillPixelData'
+
+/**
+ * Clears a region of the PixelData to transparent (0x00000000).
+ * Internally uses the optimized fillPixelData.
+ */
+export function clearPixelData(
+  dst: PixelData,
+  rect?: Partial<Rect>,
+): void {
+  fillPixelData(dst, 0 as Color32, rect)
+}

package/src/PixelData/fillPixelData.ts

@@ -0,0 +1,56 @@
+import type { Color32, Rect } from '../_types'
+import type { PixelData } from '../PixelData'
+
+/**
+ * A high-performance solid fill for PixelData.
+ */
+export function fillPixelData(
+  dst: PixelData,
+  color: Color32,
+  rect?: Partial<Rect>,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+  } = rect || {}
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // Destination Clipping
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) {
+    return
+  }
+
+  const dst32 = dst.data32
+  const dw = dst.width
+
+  // Optimization: If filling the entire buffer, use the native .fill()
+  if (actualW === dw && actualH === dst.height && x === 0 && y === 0) {
+    dst32.fill(color)
+    return
+  }
+
+  // Row-by-row fill for partial rectangles
+  for (let iy = 0; iy < actualH; iy++) {
+    const start = (y + iy) * dw + x
+    const end = start + actualW
+    dst32.fill(color, start, end)
+  }
+}

package/src/PixelData.ts

@@ -0,0 +1,20 @@
+import type { ImageDataLike } from './_types'
+
+export class PixelData {
+  public readonly data32: Uint32Array
+  public readonly width: number
+  public readonly height: number
+
+  constructor(public readonly imageData: ImageDataLike) {
+    this.width = imageData.width
+    this.height = imageData.height
+
+    // Create the view once.
+    // Shift right by 2 is a fast bitwise division by 4.
+    this.data32 = new Uint32Array(
+      imageData.data.buffer,
+      imageData.data.byteOffset,
+      imageData.data.byteLength >> 2,
+    )
+  }
+}