pixel-data-js 0.18.0 → 0.19.0

package/src/PixelData/PixelData.ts

@@ -1,44 +1,49 @@
+import type { ImageDataLike, ImageDataLikeConstructor, IPixelData } from '../_types'
 import { imageDataToUInt32Array } from '../ImageData/imageDataToUInt32Array'
 
-export class PixelData {
-  public data32: Uint32Array
-  public imageData!: ImageData
+export class PixelData<T extends ImageDataLike = ImageData> implements IPixelData {
+  readonly data32: Uint32Array
+  readonly imageData: T
+  readonly width: number
+  readonly height: number
 
-  get width(): number {
-    return this.imageData.width
-  }
-
-  get height(): number {
-    return this.imageData.height
-  }
-
-  constructor(imageData: ImageData) {
+  constructor(imageData: T) {
     this.data32 = imageDataToUInt32Array(imageData)
     this.imageData = imageData
+    this.width = imageData.width
+    this.height = imageData.height
   }
 
-  set(imageData: ImageData): void {
-    this.imageData = imageData
-    this.data32 = imageDataToUInt32Array(imageData)
+  set(imageData: T): void {
+    ;(this as any).imageData = imageData
+    ;(this as any).data32 = imageDataToUInt32Array(imageData)
+    ;(this as any).width = imageData.width
+    ;(this as any).height = imageData.height
   }
 
-  /**
-   * Creates a deep copy of the PixelData using the environment's ImageData constructor.
-   */
-  copy(): PixelData {
-    const buffer = new Uint8ClampedArray(this.imageData.data)
-
-    // Fallback to the object's own constructor if the global ImageData is missing (Node tests)
-    const ImageConstructor = (typeof ImageData !== 'undefined'
-      ? ImageData
-      : (this.imageData.constructor as typeof ImageData))
-
-    const newImageData = new ImageConstructor(
-      buffer,
-      this.width,
-      this.height,
-    )
-
-    return new PixelData(newImageData)
+  // should only be used for debug and testing
+  copy(): PixelData<T> {
+    const data = this.imageData.data
+    const buffer = new Uint8ClampedArray(data)
+    const Ctor = this.imageData.constructor
+    const isCtorValid = typeof Ctor === 'function'
+
+    let newImageData: T
+    if (isCtorValid && Ctor !== Object) {
+      const ImageConstructor = Ctor as ImageDataLikeConstructor<T>
+      newImageData = new ImageConstructor(
+        buffer,
+        this.width,
+        this.height,
+      )
+    } else {
+      newImageData = {
+        width: this.width,
+        height: this.height,
+        data: buffer,
+      } as unknown as T
+    }
+
+    return new PixelData<T>(newImageData)
   }
 }

package/src/PixelData/applyAlphaMaskToPixelData.ts

@@ -0,0 +1,119 @@
+import { type AlphaMask, type ApplyMaskToPixelDataOptions, type IPixelData } from '../_types'
+
+export function applyAlphaMaskToPixelData(
+  dst: IPixelData,
+  mask: AlphaMask,
+  opts: ApplyMaskToPixelDataOptions = {},
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha: globalAlpha = 255,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (globalAlpha === 0) return
+
+  // 1. Initial Destination Clipping
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  w = Math.min(w, dst.width - x)
+  h = Math.min(h, dst.height - y)
+
+  if (w <= 0) return
+  if (h <= 0) return
+
+  // 2. Determine Source Dimensions
+  const mPitch = mw ?? width
+  if (mPitch <= 0) return
+  const maskHeight = (mask.length / mPitch) | 0
+
+  // 3. Source Bounds Clipping
+  // Calculate where we would start reading in the mask
+  const startX = mx + (x - targetX)
+  const startY = my + (y - targetY)
+
+  // Find the safe overlap between the requested region and the mask bounds
+  const sX0 = Math.max(0, startX)
+  const sY0 = Math.max(0, startY)
+  const sX1 = Math.min(mPitch, startX + w)
+  const sY1 = Math.min(maskHeight, startY + h)
+
+  const finalW = sX1 - sX0
+  const finalH = sY1 - sY0
+
+  // This is where your failing tests are now caught
+  if (finalW <= 0) return
+  if (finalH <= 0) return
+
+  // 4. Align Destination with Source Clipping
+  // If the source was clipped on the top/left, we must shift the destination start
+  const xShift = sX0 - startX
+  const yShift = sY0 - startY
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const dStride = dw - finalW
+  const mStride = mPitch - finalW
+
+  let dIdx = (y + yShift) * dw + (x + xShift)
+  let mIdx = sY0 * mPitch + sX0
+
+  for (let iy = 0; iy < h; iy++) {
+    for (let ix = 0; ix < w; ix++) {
+      const mVal = mask[mIdx]
+      // Unified logic branch inside the hot path
+      const effectiveM = invertMask ? 255 - mVal : mVal
+
+      let weight = 0
+
+      if (effectiveM === 0) {
+        weight = 0
+      } else if (effectiveM === 255) {
+        weight = globalAlpha
+      } else if (globalAlpha === 255) {
+        weight = effectiveM
+      } else {
+        weight = (effectiveM * globalAlpha + 128) >> 8
+      }
+
+      if (weight === 0) {
+        // Clear alpha channel
+        dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+      } else if (weight !== 255) {
+        // Merge alpha channel
+        const d = dst32[dIdx]
+        const da = d >>> 24
+
+        if (da !== 0) {
+          const finalAlpha = da === 255 ? weight : (da * weight + 128) >> 8
+          dst32[dIdx] = ((d & 0x00ffffff) | (finalAlpha << 24)) >>> 0
+        }
+      }
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/applyBinaryMaskToPixelData.ts

@@ -0,0 +1,111 @@
+import { type ApplyMaskToPixelDataOptions, type BinaryMask, type IPixelData } from '../_types'
+
+/**
+ * Directly applies a mask to a region of PixelData,
+ * modifying the destination's alpha channel in-place.
+ */
+export function applyBinaryMaskToPixelData(
+  dst: IPixelData,
+  mask: BinaryMask,
+  opts: ApplyMaskToPixelDataOptions = {},
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha = 255,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (alpha === 0) return
+
+  // 1. Initial Destination Clipping
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  w = Math.min(w, dst.width - x)
+  h = Math.min(h, dst.height - y)
+
+  if (w <= 0) return
+  if (h <= 0) return
+
+  // 2. Determine Source Dimensions
+  const mPitch = mw ?? width
+  if (mPitch <= 0) return
+  const maskHeight = (mask.length / mPitch) | 0
+
+  // 3. Source Bounds Clipping
+  // Calculate where we would start reading in the mask
+  const startX = mx + (x - targetX)
+  const startY = my + (y - targetY)
+
+  // Find the safe overlap between the requested region and the mask bounds
+  const sX0 = Math.max(0, startX)
+  const sY0 = Math.max(0, startY)
+  const sX1 = Math.min(mPitch, startX + w)
+  const sY1 = Math.min(maskHeight, startY + h)
+
+  const finalW = sX1 - sX0
+  const finalH = sY1 - sY0
+
+  // This is where your failing tests are now caught
+  if (finalW <= 0) return
+  if (finalH <= 0) return
+
+  // 4. Align Destination with Source Clipping
+  // If the source was clipped on the top/left, we must shift the destination start
+  const xShift = sX0 - startX
+  const yShift = sY0 - startY
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const dStride = dw - finalW
+  const mStride = mPitch - finalW
+
+  let dIdx = (y + yShift) * dw + (x + xShift)
+  let mIdx = sY0 * mPitch + sX0
+
+  for (let iy = 0; iy < h; iy++) {
+    for (let ix = 0; ix < w; ix++) {
+      const mVal = mask[mIdx]
+      // Consistently determines if this pixel should be "masked out" (cleared)
+      const isMaskedOut = invertMask ? mVal !== 0 : mVal === 0
+
+      if (isMaskedOut) {
+        // Clear alpha channel only (keep RGB)
+        dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+      } else if (alpha !== 255) {
+        const d = dst32[dIdx]
+        const da = d >>> 24
+
+        // If pixel isn't already fully transparent, apply global alpha
+        if (da !== 0) {
+          const finalAlpha = da === 255 ? alpha : (da * alpha + 128) >> 8
+          dst32[dIdx] = ((d & 0x00ffffff) | (finalAlpha << 24)) >>> 0
+        }
+      }
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/applyCircleBrushToPixelData.ts

@@ -1,6 +1,6 @@
-import type { BlendColor32, Color32, Rect } from '../_types'
+import type { BlendColor32, Color32, IPixelData, Rect } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
-import type { PixelData } from './PixelData'
+import { getCircleBrushOrPencilBounds } from '../Rect/getCircleBrushOrPencilBounds'
 
 /**
  * Applies a circular brush to pixel data, blending a color with optional falloff.
@@ -14,17 +14,17 @@ import type { PixelData } from './PixelData'
  * @default 255
  * @param fallOff A function that returns an alpha multiplier (0-1) based on the normalized distance (0-1) from the circle's center.
  * @param blendFn
- * @param bounds precalculated result from {@link getCircleBrushBounds}
+ * @param bounds precalculated result from {@link getCircleBrushOrPencilBounds}
  * @default sourceOverPerfect
  */
 export function applyCircleBrushToPixelData(
-  target: PixelData,
+  target: IPixelData,
   color: Color32,
   centerX: number,
   centerY: number,
   brushSize: number,
   alpha = 255,
-  fallOff?: (dist: number) => number,
+  fallOff: (dist: number) => number,
   blendFn: BlendColor32 = sourceOverPerfect,
   bounds?: Rect,
 ): void {
@@ -32,12 +32,12 @@ export function applyCircleBrushToPixelData(
   const targetHeight = target.height
 
   // Use provided bounds OR calculate them once
-  const b = bounds ?? getCircleBrushBounds(
+  const b = bounds ?? getCircleBrushOrPencilBounds(
     centerX,
     centerY,
     brushSize,
     targetWidth,
-    targetHeight
+    targetHeight,
   )
 
   if (b.w <= 0 || b.h <= 0) return
@@ -48,8 +48,6 @@ export function applyCircleBrushToPixelData(
   const invR = 1 / r
 
   const centerOffset = (brushSize % 2 === 0) ? 0.5 : 0
-  const baseColor = color & 0x00ffffff
-  const constantSrc = ((alpha << 24) | baseColor) >>> 0 as Color32
 
   const endX = b.x + b.w
   const endY = b.y + b.h
@@ -57,6 +55,10 @@ export function applyCircleBrushToPixelData(
   // Anchor the math to the floor of the center for exact pixel art parity
   const fCenterX = Math.floor(centerX)
   const fCenterY = Math.floor(centerY)
+  const baseSrcAlpha = (color >>> 24)
+  const colorRGB = color & 0x00ffffff
+  const isOpaque = alpha === 255
+  const isOverwrite = (blendFn as any).isOverwrite
 
   for (let cy = b.y; cy < endY; cy++) {
     const relY = (cy - fCenterY) + centerOffset
@@ -69,56 +71,29 @@ export function applyCircleBrushToPixelData(
 
       if (dSqr <= rSqr) {
         const idx = rowOffset + cx
+        let weight = alpha
 
-        if (fallOff) {
-          const strength = fallOff(Math.sqrt(dSqr) * invR)
-          const fAlpha = (alpha * strength) & 0xFF
-          const src = ((fAlpha << 24) | baseColor) >>> 0 as Color32
-          data32[idx] = blendFn(src, data32[idx] as Color32)
-        } else {
-          data32[idx] = blendFn(constantSrc, data32[idx] as Color32)
-        }
-      }
-    }
-  }
-}
+        const strength = fallOff(1 - (Math.sqrt(dSqr) * invR))
+        const maskVal = (strength * 255) | 0
+        if (maskVal === 0) continue
 
-export function getCircleBrushBounds(
-  centerX: number,
-  centerY: number,
-  brushSize: number,
-  targetWidth?: number,
-  targetHeight?: number,
-  out?: Rect,
-): Rect {
-  const r = brushSize / 2
-
-  // These offsets match your getPerfectCircleCoords exactly
-  const minOffset = -Math.ceil(r - 0.5)
-  const maxOffset = Math.floor(r - 0.5)
+        // Match Blitter's weight calculation exactly
+        if (isOpaque) {
+          weight = maskVal
+        } else if (maskVal !== 255) {
+          weight = (maskVal * alpha + 128) >> 8
+        }
 
-  // start is inclusive, end is exclusive
-  const startX = Math.floor(centerX + minOffset)
-  const startY = Math.floor(centerY + minOffset)
-  const endX = Math.floor(centerX + maxOffset) + 1
-  const endY = Math.floor(centerY + maxOffset) + 1
+        // Match Blitter's final color calculation exactly
+        let finalCol = color
+        if (weight < 255) {
+          const a = (baseSrcAlpha * weight + 128) >> 8
+          if (a === 0 && !isOverwrite) continue
+          finalCol = (colorRGB | (a << 24)) >>> 0 as Color32
+        }
 
-  const res = out ?? {
-    x: 0,
-    y: 0,
-    w: 0,
-    h: 0,
+        data32[idx] = blendFn(finalCol, data32[idx] as Color32)
+      }
+    }
   }
-
-  const cStartX = targetWidth !== undefined ? Math.max(0, startX) : startX
-  const cStartY = targetHeight !== undefined ? Math.max(0, startY) : startY
-  const cEndX = targetWidth !== undefined ? Math.min(targetWidth, endX) : endX
-  const cEndY = targetHeight !== undefined ? Math.min(targetHeight, endY) : endY
-
-  res.x = cStartX
-  res.y = cStartY
-  res.w = Math.max(0, cEndX - cStartX)
-  res.h = Math.max(0, cEndY - cStartY)
-
-  return res
 }

package/src/PixelData/applyRectBrushToPixelData.ts

@@ -1,117 +1,85 @@
-import type { BlendColor32, Color32, Rect } from '../_types'
+import type { BlendColor32, Color32, IPixelData, Rect } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
-import { PixelData } from './PixelData'
-
-/**
- * Applies a rectangular brush to pixel data, blending a color with optional falloff.
- *
- * @param target The PixelData to modify.
- * @param color The brush color.
- * @param centerX The center x-coordinate of the brush.
- * @param centerY The center y-coordinate of the brush.
- * @param brushWidth
- * @param brushHeight
- * @param alpha The overall opacity of the brush (0-255).
- * @default 255
- * @param fallOff A function that returns an alpha multiplier (0-1) based on the normalized distance (0-1) from the circle's center.
- * @param blendFn
- * @param bounds precalculated result from {@link getRectBrushBounds}
- * @default sourceOverPerfect
- */
+import { getRectBrushOrPencilBounds } from '../Rect/getRectBrushOrPencilBounds'
+
 export function applyRectBrushToPixelData(
-  target: PixelData,
+  target: IPixelData,
   color: Color32,
   centerX: number,
   centerY: number,
   brushWidth: number,
   brushHeight: number,
   alpha = 255,
-  fallOff?: (dist: number) => number,
+  fallOff: (dist: number) => number,
   blendFn: BlendColor32 = sourceOverPerfect,
   bounds?: Rect,
 ): void {
   const targetWidth = target.width
   const targetHeight = target.height
 
-  // Use provided bounds or compute once
-  const b = bounds ?? getRectBrushBounds(
+  const b = bounds ?? getRectBrushOrPencilBounds(
     centerX,
     centerY,
     brushWidth,
     brushHeight,
     targetWidth,
-    targetHeight
+    targetHeight,
   )
 
   if (b.w <= 0 || b.h <= 0) return
 
   const data32 = target.data32
   const baseColor = color & 0x00ffffff
-  const constantSrc = ((alpha << 24) | baseColor) >>> 0 as Color32
+  const baseSrcAlpha = color >>> 24
+  const isOpaque = alpha === 255
 
   const invHalfW = 1 / (brushWidth / 2)
   const invHalfH = 1 / (brushHeight / 2)
+
+  // Restore the pixel-art centering logic
+  const centerOffsetX = (brushWidth % 2 === 0) ? 0.5 : 0
+  const centerOffsetY = (brushHeight % 2 === 0) ? 0.5 : 0
+  const fCenterX = Math.floor(centerX)
+  const fCenterY = Math.floor(centerY)
+
   const endX = b.x + b.w
   const endY = b.y + b.h
+  const isOverwrite = (blendFn as any).isOverwrite
 
   for (let py = b.y; py < endY; py++) {
     const rowOffset = py * targetWidth
-
-    // Y-distance check for falloff (center of pixel to center of brush)
-    const dy = fallOff ? Math.abs(py + 0.5 - centerY) * invHalfH : 0
+    const dy = Math.abs((py - fCenterY) + centerOffsetY) * invHalfH
 
     for (let px = b.x; px < endX; px++) {
       const idx = rowOffset + px
 
-      if (fallOff) {
-        const dx = Math.abs(px + 0.5 - centerX) * invHalfW
-        const dist = dx > dy ? dx : dy
+      const dx = Math.abs((px - fCenterX) + centerOffsetX) * invHalfW
+      const dist = dx > dy ? dx : dy
+
+      const strength = fallOff(dist)
+      const maskVal = (strength * 255) | 0
 
-        const strength = fallOff(dist)
-        const fAlpha = (alpha * strength) | 0
-        const src = ((fAlpha << 24) | baseColor) >>> 0 as Color32
+      if (maskVal <= 0) continue
 
-        data32[idx] = blendFn(src, data32[idx] as Color32)
-      } else {
-        data32[idx] = blendFn(constantSrc, data32[idx] as Color32)
+      let weight = alpha
+
+      if (isOpaque) {
+        weight = maskVal
+      } else if (maskVal !== 255) {
+        weight = (maskVal * alpha + 128) >> 8
       }
-    }
-  }
-}
 
-export function getRectBrushBounds(
-  centerX: number,
-  centerY: number,
-  brushWidth: number,
-  brushHeight: number,
-  targetWidth?: number,
-  targetHeight?: number,
-  out?: Rect,
-): Rect {
-  const startX = Math.floor(centerX - brushWidth / 2)
-  const startY = Math.floor(centerY - brushHeight / 2)
-  const endX = startX + brushWidth
-  const endY = startY + brushHeight
-
-  const res = out ?? {
-    x: 0,
-    y: 0,
-    w: 0,
-    h: 0,
-  }
+      let finalCol = color
 
-  const cStartX = targetWidth !== undefined ? Math.max(0, startX) : startX
-  const cStartY = targetHeight !== undefined ? Math.max(0, startY) : startY
-  const cEndX = targetWidth !== undefined ? Math.min(targetWidth, endX) : endX
-  const cEndY = targetHeight !== undefined ? Math.min(targetHeight, endY) : endY
+      if (weight < 255) {
+        const a = (baseSrcAlpha * weight + 128) >> 8
 
-  const w = cEndX - cStartX
-  const h = cEndY - cStartY
+        if (a === 0 && !isOverwrite) continue
 
-  res.x = cStartX
-  res.y = cStartY
-  res.w = w < 0 ? 0 : w
-  res.h = h < 0 ? 0 : h
+        finalCol = ((a << 24) | baseColor) >>> 0 as Color32
+      }
 
-  return res
+      data32[idx] = blendFn(finalCol, data32[idx] as Color32)
+    }
+  }
 }