pixel-data-js 0.20.0 → 0.22.2

package/src/PixelData/applyCircleBrushToPixelData.ts

@@ -1,99 +1,91 @@
-import type { BlendColor32, Color32, IPixelData, Rect } from '../_types'
+import {
+  type BlendColor32,
+  type CircleBrushMask,
+  type Color32,
+  type ColorBlendMaskOptions,
+  type IPixelData,
+  MaskType,
+  type Rect,
+} from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
 import { getCircleBrushOrPencilBounds } from '../Rect/getCircleBrushOrPencilBounds'
+import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
+import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
 
 /**
- * Applies a circular brush to pixel data, blending a color with optional falloff.
+ * Applies a circular brush to pixel data using a pre-calculated alpha mask.
  *
  * @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 brushSize The diameter of the brush.
+ * @param brush The pre-calculated CircleBrushAlphaMask.
  * @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 scratchOptions
  * @param bounds precalculated result from {@link getCircleBrushOrPencilBounds}
- * @default sourceOverPerfect
  */
 export function applyCircleBrushToPixelData(
   target: IPixelData,
   color: Color32,
   centerX: number,
   centerY: number,
-  brushSize: number,
+  brush: CircleBrushMask,
   alpha = 255,
-  fallOff: (dist: number) => number,
   blendFn: BlendColor32 = sourceOverPerfect,
+  scratchOptions: ColorBlendMaskOptions = {},
   bounds?: Rect,
 ): void {
-  const targetWidth = target.width
-  const targetHeight = target.height
-
-  // Use provided bounds OR calculate them once
   const b = bounds ?? getCircleBrushOrPencilBounds(
     centerX,
     centerY,
-    brushSize,
-    targetWidth,
-    targetHeight,
+    brush.size,
+    target.width,
+    target.height,
   )
 
   if (b.w <= 0 || b.h <= 0) return
 
-  const data32 = target.data32
-  const r = brushSize / 2
-  const rSqr = r * r
-  const invR = 1 / r
-
-  const centerOffset = (brushSize % 2 === 0) ? 0.5 : 0
-
-  const endX = b.x + b.w
-  const endY = b.y + b.h
+  const unclippedStartX = Math.floor(centerX + brush.minOffset)
+  const unclippedStartY = Math.floor(centerY + brush.minOffset)
 
-  // 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
+  // Calculate the intersection between the unclipped mask rect and the allowed bounds
+  const ix = Math.max(unclippedStartX, b.x)
+  const iy = Math.max(unclippedStartY, b.y)
+  const ir = Math.min(unclippedStartX + brush.w, b.x + b.w)
+  const ib = Math.min(unclippedStartY + brush.h, b.y + b.h)
 
-  for (let cy = b.y; cy < endY; cy++) {
-    const relY = (cy - fCenterY) + centerOffset
-    const dySqr = relY * relY
-    const rowOffset = cy * targetWidth
+  const iw = ir - ix
+  const ih = ib - iy
 
-    for (let cx = b.x; cx < endX; cx++) {
-      const relX = (cx - fCenterX) + centerOffset
-      const dSqr = relX * relX + dySqr
+  // If the mask falls entirely outside the bounds, exit
+  if (iw <= 0 || ih <= 0) return
 
-      if (dSqr <= rSqr) {
-        const idx = rowOffset + cx
-        let weight = alpha
+  // Apply the intersected coordinates and internal mask offsets
+  scratchOptions.x = ix
+  scratchOptions.y = iy
+  scratchOptions.w = iw
+  scratchOptions.h = ih
+  scratchOptions.mx = ix - unclippedStartX
+  scratchOptions.my = iy - unclippedStartY
+  scratchOptions.alpha = alpha
+  scratchOptions.blendFn = blendFn
 
-        const strength = fallOff(1 - (Math.sqrt(dSqr) * invR))
-        const maskVal = (strength * 255) | 0
-        if (maskVal === 0) continue
-
-        // Match Blitter's weight calculation exactly
-        if (isOpaque) {
-          weight = maskVal
-        } else if (maskVal !== 255) {
-          weight = (maskVal * alpha + 128) >> 8
-        }
-
-        // 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
-        }
+  if (brush.type === MaskType.ALPHA) {
+    blendColorPixelDataAlphaMask(
+      target,
+      color,
+      brush,
+      scratchOptions,
+    )
+  }
 
-        data32[idx] = blendFn(finalCol, data32[idx] as Color32)
-      }
-    }
+  if (brush.type === MaskType.BINARY) {
+    blendColorPixelDataBinaryMask(
+      target,
+      color,
+      brush,
+      scratchOptions,
+    )
   }
 }

package/src/PixelData/blendColorPixelDataAlphaMask.ts

@@ -1,26 +1,35 @@
 import type { AlphaMask, Color32, ColorBlendMaskOptions, IPixelData } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
 
+/**
+ * Blends a solid color into a target pixel buffer using an alpha mask.
+ *
+ * @remarks
+ * If the width (`w`) or height (`h`) are omitted from the options, they will safely
+ * default to the dimensions of the provided mask to prevent out-of-bounds memory access.
+ *
+ * @param dst - The destination {@link IPixelData} buffer to modify.
+ * @param color - The solid color to apply.
+ * @param mask - The mask defining the per-pixel opacity of the target area.
+ * @param opts - Configuration options including placement coordinates, bounds, global alpha, and mask offsets.
+ */
 export function blendColorPixelDataAlphaMask(
   dst: IPixelData,
   color: Color32,
   mask: AlphaMask,
-  opts: ColorBlendMaskOptions,
-) {
-  const {
-    x: targetX = 0,
-    y: targetY = 0,
-    w: width = dst.width,
-    h: height = dst.height,
-    alpha: globalAlpha = 255,
-    blendFn = sourceOverPerfect,
-    mw = width,
-    mx = 0,
-    my = 0,
-    invertMask = false,
-  } = opts
-
-  if (globalAlpha === 0 || !mask) return
+  opts: ColorBlendMaskOptions = {},
+): void {
+  const targetX = opts.x ?? 0
+  const targetY = opts.y ?? 0
+  const w = opts.w ?? mask.w
+  const h = opts.h ?? mask.h
+  const globalAlpha = opts.alpha ?? 255
+  const blendFn = opts.blendFn ?? sourceOverPerfect
+  const mx = opts.mx ?? 0
+  const my = opts.my ?? 0
+  const invertMask = opts.invertMask ?? false
+
+  if (globalAlpha === 0) return
 
   const baseSrcAlpha = (color >>> 24)
   const isOverwrite = (blendFn as any).isOverwrite || false
@@ -29,21 +38,21 @@ export function blendColorPixelDataAlphaMask(
 
   let x = targetX
   let y = targetY
-  let w = width
-  let h = height
+  let actualW = w
+  let actualH = h
 
   if (x < 0) {
-    w += x
+    actualW += x
     x = 0
   }
 
   if (y < 0) {
-    h += y
+    actualH += y
     y = 0
   }
 
-  const actualW = Math.min(w, dst.width - x)
-  const actualH = Math.min(h, dst.height - y)
+  actualW = Math.min(actualW, dst.width - x)
+  actualH = Math.min(actualH, dst.height - y)
 
   if (actualW <= 0 || actualH <= 0) return
 
@@ -52,7 +61,8 @@ export function blendColorPixelDataAlphaMask(
 
   const dst32 = dst.data32
   const dw = dst.width
-  const mPitch = mw
+  const mPitch = mask.w
+  const maskData = mask.data
 
   let dIdx = (y * dw + x) | 0
   let mIdx = ((my + dy) * mPitch + (mx + dx)) | 0
@@ -64,7 +74,7 @@ export function blendColorPixelDataAlphaMask(
 
   for (let iy = 0; iy < actualH; iy++) {
     for (let ix = 0; ix < actualW; ix++) {
-      const mVal = mask[mIdx]
+      const mVal = maskData[mIdx]
       const effM = invertMask ? 255 - mVal : mVal
 
       if (effM === 0) {
@@ -96,7 +106,7 @@ export function blendColorPixelDataAlphaMask(
           mIdx++
           continue
         }
-        finalCol = (colorRGB | (a << 24)) >>> 0 as Color32
+        finalCol = ((colorRGB | (a << 24)) >>> 0) as Color32
       }
 
       dst32[dIdx] = blendFn(finalCol, dst32[dIdx] as Color32)

package/src/PixelData/blendColorPixelDataBinaryMask.ts

@@ -1,26 +1,35 @@
 import type { BinaryMask, Color32, ColorBlendMaskOptions, IPixelData } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
 
+/**
+ * Blends a solid color into a target pixel buffer using a binary mask.
+ *
+ * @remarks
+ * If the width (`w`) or height (`h`) are omitted from the options, they will safely
+ * default to the dimensions of the provided mask to prevent out-of-bounds memory access.
+ *
+ * @param dst - The destination {@link IPixelData} buffer to modify.
+ * @param color - The solid color to apply.
+ * @param mask - The mask defining the per-pixel opacity of the target area.
+ * @param opts - Configuration options including placement coordinates, bounds, global alpha, and mask offsets.
+ */
 export function blendColorPixelDataBinaryMask(
   dst: IPixelData,
   color: Color32,
   mask: BinaryMask,
   opts: ColorBlendMaskOptions = {},
 ) {
-  const {
-    x: targetX = 0,
-    y: targetY = 0,
-    w: width = dst.width,
-    h: height = dst.height,
-    alpha: globalAlpha = 255,
-    blendFn = sourceOverPerfect,
-    mw = width,
-    mx = 0,
-    my = 0,
-    invertMask = false,
-  } = opts
-
-  if (globalAlpha === 0 || !mask) return
+  const targetX = opts.x ?? 0
+  const targetY = opts.y ?? 0
+  let w = opts.w ?? mask.w
+  let h = opts.h ?? mask.h
+  const globalAlpha = opts.alpha ?? 255
+  const blendFn = opts.blendFn ?? sourceOverPerfect
+  const mx = opts.mx ?? 0
+  const my = opts.my ?? 0
+  const invertMask = opts.invertMask ?? false
+
+  if (globalAlpha === 0) return
 
   const baseSrcAlpha = (color >>> 24)
   const isOverwrite = (blendFn as any).isOverwrite || false
@@ -29,8 +38,6 @@ export function blendColorPixelDataBinaryMask(
 
   let x = targetX
   let y = targetY
-  let w = width
-  let h = height
 
   if (x < 0) {
     w += x
@@ -60,8 +67,8 @@ export function blendColorPixelDataBinaryMask(
 
   const dst32 = dst.data32
   const dw = dst.width
-  const mPitch = mw
-
+  const mPitch = mask.w
+  const maskData = mask.data
   let dIdx = (y * dw + x) | 0
   let mIdx = ((my + dy) * mPitch + (mx + dx)) | 0
 
@@ -71,7 +78,7 @@ export function blendColorPixelDataBinaryMask(
 
   for (let iy = 0; iy < actualH; iy++) {
     for (let ix = 0; ix < actualW; ix++) {
-      if (mask[mIdx] === skipVal) {
+      if (maskData[mIdx] === skipVal) {
         dIdx++
         mIdx++
         continue

package/src/PixelData/blendPixelDataAlphaMask.ts

@@ -16,7 +16,6 @@ export function blendPixelDataAlphaMask(
     h: height = src.height,
     alpha: globalAlpha = 255,
     blendFn = sourceOverPerfect,
-    mw = src.width,
     mx = 0,
     my = 0,
     invertMask = false,
@@ -62,7 +61,8 @@ export function blendPixelDataAlphaMask(
   // 2. Index Setup
   const dw = dst.width
   const sw = src.width
-  const mPitch = mw
+  const mPitch = alphaMask.w
+  const maskData = alphaMask.data
 
   // dx/dy is the displacement from requested start to clipped start.
   // This keeps the mask locked to the source content during cross-clipping.
@@ -85,7 +85,7 @@ export function blendPixelDataAlphaMask(
 
   for (let iy = 0; iy < actualH; iy++) {
     for (let ix = 0; ix < actualW; ix++) {
-      const mVal = alphaMask[mIdx]
+      const mVal = maskData[mIdx]
       const effM = invertMask ? 255 - mVal : mVal
 
       // Early exit if mask is fully transparent

package/src/PixelData/blendPixelDataBinaryMask.ts

@@ -16,7 +16,6 @@ export function blendPixelDataBinaryMask(
     h: height = src.height,
     alpha: globalAlpha = 255,
     blendFn = sourceOverPerfect,
-    mw = src.width,
     mx = 0,
     my = 0,
     invertMask = false,
@@ -72,7 +71,8 @@ export function blendPixelDataBinaryMask(
   const src32 = src.data32
   const dw = dst.width
   const sw = src.width
-  const mPitch = mw
+  const mPitch = binaryMask.w
+  const maskData = binaryMask.data
 
   let dIdx = (y * dw + x) | 0
   let sIdx = (sy * sw + sx) | 0
@@ -89,7 +89,7 @@ export function blendPixelDataBinaryMask(
   for (let iy = 0; iy < actualH; iy++) {
     for (let ix = 0; ix < actualW; ix++) {
       // Binary Mask Check (Earliest exit)
-      if (binaryMask[mIdx] === skipVal) {
+      if (maskData[mIdx] === skipVal) {
         dIdx++
         sIdx++
         mIdx++

package/src/PixelData/clearPixelData.ts

@@ -1,4 +1,4 @@
-import type { Color32, IPixelData, Rect } from '../_types'
+import type { BinaryMaskRect, Color32, IPixelData } from '../_types'
 import { fillPixelData } from './fillPixelData'
 
 /**
@@ -7,7 +7,7 @@ import { fillPixelData } from './fillPixelData'
  */
 export function clearPixelData(
   dst: IPixelData,
-  rect?: Partial<Rect>,
+  rect?: Partial<BinaryMaskRect>,
 ): void {
   fillPixelData(dst, 0 as Color32, rect)
 }

package/src/PixelData/fillPixelData.ts

@@ -1,29 +1,28 @@
-import type { BinaryMask, BinaryMaskRect, Color32, IPixelData } from '../_types'
+import type { Color32, IPixelData, Rect } from '../_types'
 import { makeClippedRect, resolveRectClipping } from '../Internal/resolveClipping'
-import type { PixelData } from './PixelData'
 
 const SCRATCH_RECT = makeClippedRect()
 
 /**
- * Fills a region or the {@link PixelData} buffer with a solid color.
+ * Fills a region or the {@link IPixelData} buffer with a solid color.
  *
- * @param dst - The target {@link PixelData} to modify.
- * @param color - The {@link Color32} value to apply.
- * @param rect - A {@link BinaryMaskRect} defining the area to fill.
+ * @param dst - The target to modify.
+ * @param color - The color to apply.
+ * @param rect - Defines the area to fill. If omitted, the entire
+ * buffer is filled.
  */
 export function fillPixelData(
   dst: IPixelData,
   color: Color32,
-  rect?: Partial<BinaryMaskRect>,
+  rect?: Partial<Rect>,
 ): void
 /**
- * @param dst - The target {@link PixelData} to modify.
- * @param color - The {@link Color32} value to apply.
+ * @param dst - The target to modify.
+ * @param color - The color to apply.
  * @param x - Starting horizontal coordinate.
  * @param y - Starting vertical coordinate.
  * @param w - Width of the fill area.
  * @param h - Height of the fill area.
- * @param mask - A {@link BinaryMaskRect} defining the area to fill
  */
 export function fillPixelData(
   dst: IPixelData,
@@ -32,36 +31,30 @@ export function fillPixelData(
   y: number,
   w: number,
   h: number,
-  mask?: BinaryMask,
 ): void
 export function fillPixelData(
   dst: IPixelData,
   color: Color32,
-  _x?: Partial<BinaryMaskRect> | number,
+  _x?: Partial<Rect> | number,
   _y?: number,
   _w?: number,
   _h?: number,
-  _mask?: BinaryMask,
 ): void {
   let x: number
   let y: number
   let w: number
   let h: number
-  let mask: BinaryMask | undefined
 
   if (typeof _x === 'object') {
     x = _x.x ?? 0
     y = _x.y ?? 0
     w = _x.w ?? dst.width
     h = _x.h ?? dst.height
-    mask = _x.mask
-
   } else if (typeof _x === 'number') {
     x = _x
     y = _y!
     w = _w!
     h = _h!
-    mask = _mask
   } else {
     x = 0
     y = 0
@@ -90,30 +83,10 @@ export function fillPixelData(
     return
   }
 
-  if (mask) {
-    for (let iy = 0; iy < actualH; iy++) {
-      const currentY = finalY + iy
-      const maskY = currentY - y
-      const maskOffset = maskY * w
-
-      for (let ix = 0; ix < actualW; ix++) {
-        const currentX = finalX + ix
-        const maskX = currentX - x
-        const maskIndex = maskOffset + maskX
-        const isMasked = mask[maskIndex]
-
-        if (isMasked) {
-          const dstIndex = currentY * dw + currentX
-          dst32[dstIndex] = color
-        }
-      }
-    }
-  } else {
-    // Row-by-row fill for partial rectangles
-    for (let iy = 0; iy < actualH; iy++) {
-      const start = (finalY + iy) * dw + finalX
-      const end = start + actualW
-      dst32.fill(color, start, end)
-    }
+  // Row-by-row fill for partial rectangles
+  for (let iy = 0; iy < actualH; iy++) {
+    const start = (finalY + iy) * dw + finalX
+    const end = start + actualW
+    dst32.fill(color, start, end)
   }
 }

package/src/PixelData/fillPixelDataBinaryMask.ts

@@ -0,0 +1,79 @@
+import type { BinaryMask, Color32, IPixelData } from '../_types'
+import { makeClippedRect, resolveRectClipping } from '../Internal/resolveClipping'
+
+const SCRATCH_RECT = makeClippedRect()
+
+/**
+ * Fills a region of the {@link IPixelData} buffer with a solid color using a mask.
+ * @param dst - The target to modify.
+ * @param color - The color to apply.
+ * @param mask - The mask defining the area to fill.
+ * @param alpha - The overall opacity of the fill (0-255).
+ * @param x - Starting horizontal coordinate for the mask placement.
+ * @param y - Starting vertical coordinate for the mask placement.
+ */
+export function fillPixelDataBinaryMask(
+  dst: IPixelData,
+  color: Color32,
+  mask: BinaryMask,
+  alpha = 255,
+  x = 0,
+  y = 0,
+): void {
+  if (alpha === 0) return
+
+  const maskW = mask.w
+  const maskH = mask.h
+
+  const clip = resolveRectClipping(
+    x,
+    y,
+    maskW,
+    maskH,
+    dst.width,
+    dst.height,
+    SCRATCH_RECT,
+  )
+
+  if (!clip.inBounds) return
+
+  const {
+    x: finalX,
+    y: finalY,
+    w: actualW,
+    h: actualH,
+  } = clip
+
+  const maskData = mask.data
+  const dst32 = dst.data32
+  const dw = dst.width
+
+  // Pre-calculate the alpha-adjusted color once outside the loop
+  let finalCol = color
+
+  if (alpha < 255) {
+    const baseSrcAlpha = color >>> 24
+    const colorRGB = color & 0x00ffffff
+    const a = (baseSrcAlpha * alpha + 128) >> 8
+
+    finalCol = ((colorRGB | (a << 24)) >>> 0) as Color32
+  }
+
+  for (let iy = 0; iy < actualH; iy++) {
+    const currentY = finalY + iy
+    const maskY = currentY - y
+    const maskOffset = maskY * maskW
+
+    const dstRowOffset = currentY * dw
+
+    for (let ix = 0; ix < actualW; ix++) {
+      const currentX = finalX + ix
+      const maskX = currentX - x
+      const maskIndex = maskOffset + maskX
+
+      if (maskData[maskIndex]) {
+        dst32[dstRowOffset + currentX] = finalCol
+      }
+    }
+  }
+}

package/src/PixelData/invertPixelData.ts

@@ -14,7 +14,6 @@ export function invertPixelData(
     w: width = pixelData.width,
     h: height = pixelData.height,
     mask,
-    mw,
     mx = 0,
     my = 0,
     invertMask = false,
@@ -33,7 +32,7 @@ export function invertPixelData(
 
   const dst32 = dst.data32
   const dw = dst.width
-  const mPitch = mw ?? width
+  const mPitch = mask?.w ?? width
 
   const dx = x - targetX
   const dy = y - targetY
@@ -46,9 +45,10 @@ export function invertPixelData(
 
   // Optimization: Split loops to avoid checking `if (mask)` for every pixel.
   if (mask) {
+    const maskData = mask.data
     for (let iy = 0; iy < actualH; iy++) {
       for (let ix = 0; ix < actualW; ix++) {
-        const mVal = mask[mIdx]
+        const mVal = maskData[mIdx]
         const isHit = invertMask
           ? mVal === 0
           : mVal === 1

package/src/PixelData/pixelDataToAlphaMask.ts

@@ -1,4 +1,5 @@
 import type { AlphaMask, IPixelData } from '../_types'
+import { makeAlphaMask } from '../Mask/AlphaMask'
 
 /**
  * Extracts the alpha channel from PixelData into a single-channel mask.
@@ -13,14 +14,15 @@ export function pixelDataToAlphaMask(
     height,
   } = pixelData
   const len = data32.length
-  const mask = new Uint8Array(width * height) as AlphaMask
+  const mask = makeAlphaMask(width, height)
+  const maskData = mask.data
 
   for (let i = 0; i < len; i++) {
     const val = data32[i]
 
     // Extract the Alpha byte (top 8 bits in ABGR / Little-Endian)
     // Shift right by 24 moves the 4th byte to the 1st position
-    mask[i] = (val >>> 24) & 0xff
+    maskData[i] = (val >>> 24) & 0xff
   }
 
   return mask

package/src/PixelData/writePixelDataBuffer.ts

@@ -1,14 +1,13 @@
 import { type IPixelData, type Rect } from '../_types'
 import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
-import type { PixelData } from './PixelData'
 
 const SCRATCH_BLIT = makeClippedBlit()
 
 /**
- * Copies a pixel buffer into a specific region of a {@link PixelData} object.
+ * Copies a pixel buffer into a specific region of a {@link IPixelData} object.
  *
  * This function performs a direct memory copy from a {@link Uint32Array}
- * into the target {@link PixelData} buffer.
+ * into the target buffer.
  */
 export function writePixelDataBuffer(
   target: IPixelData,