pixel-data-js 0.26.0 → 0.28.0

package/src/PixelData/PixelData.ts

@@ -1,23 +1,19 @@
-import type { ImageDataLike, IPixelData } from '../_types'
-import { imageDataToUInt32Array } from '../ImageData/imageDataToUInt32Array'
+import type { ImageDataLike } from '../ImageData/_ImageData-types'
+import { _macro_imageDataToUint32Array } from '../ImageData/imageDataToUint32Array'
+import type { PixelData } from './_pixelData-types'
 
-export class PixelData<T extends ImageDataLike = ImageData> implements IPixelData<T> {
-  readonly data32: Uint32Array
-  readonly imageData: T
-  readonly width: number
-  readonly height: number
-
-  constructor(imageData: T) {
-    this.data32 = imageDataToUInt32Array(imageData)
-    this.imageData = imageData
-    this.width = imageData.width
-    this.height = imageData.height
+export function makePixelData<T extends ImageDataLike = ImageData>(imageData: T): PixelData<T> {
+  return {
+    data: _macro_imageDataToUint32Array(imageData),
+    imageData,
+    w: imageData.width,
+    h: imageData.height,
   }
+}
 
-  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
-  }
+export function setPixelData(target: PixelData, imageData: ImageData) {
+  ;(target as any).data = _macro_imageDataToUint32Array(imageData)
+  ;(target as any).imageData = imageData
+  ;(target as any).w = imageData.width
+  ;(target as any).h = imageData.height
 }

package/src/PixelData/ReusablePixelData.ts

@@ -0,0 +1,36 @@
+import type { PixelData } from './_pixelData-types'
+import { setPixelData } from './PixelData'
+
+export type ReusablePixelData = ReturnType<typeof makeReusablePixelData>
+
+/**
+ * Creates a factory function that manages a single, reusable PixelData instance.
+ * This is used to minimize garbage collection overhead by recycling the
+ * underlying pixel buffer across multiple operations.
+ * @returns A function that takes width and height and returns a pooled PixelData instance.
+ */
+export function makeReusablePixelData() {
+  const pixelData = {
+    w: 0,
+    h: 0,
+    data: null as unknown as Uint32Array,
+    imageData: null as unknown as ImageData,
+  }
+
+  /**
+   * Retrieves a PixelData instance of the requested dimensions.
+   * If the requested dimensions differ from the cached instance, a new one is allocated.
+   * @param width - The desired width in pixels.
+   * @param height - The desired height in pixels.
+   * @returns The cached PixelData object.
+   */
+  return function getReusablePixelData(width: number, height: number): PixelData {
+    if (pixelData.w !== width || pixelData.h !== height) {
+      setPixelData(pixelData, new ImageData(width, height))
+    } else {
+      pixelData.data.fill(0)
+    }
+
+    return pixelData
+  }
+}

package/src/PixelData/_pixelData-types.ts

@@ -0,0 +1,17 @@
+import type { ImageDataLike } from '../ImageData/_ImageData-types'
+
+export interface PixelData32 {
+  readonly data: Uint32Array
+  readonly w: number
+  readonly h: number
+}
+
+export interface MutablePixelData32 {
+  data: Uint32Array
+  w: number
+  h: number
+}
+
+export interface PixelData<T extends ImageDataLike = ImageData> extends PixelData32 {
+  readonly imageData: T
+}

package/src/PixelData/applyAlphaMaskToPixelData.ts

@@ -1,4 +1,6 @@
-import { type AlphaMask, type ApplyMaskToPixelDataOptions, type Color32, type IPixelData32 } from '../_types'
+import { type ApplyMaskToPixelDataOptions } from '../_types'
+import type { AlphaMask } from '../Mask/_mask-types'
+import type { PixelData32 } from './_pixelData-types'
 
 /**
  * Directly applies a mask to a region of PixelData,
@@ -6,14 +8,14 @@ import { type AlphaMask, type ApplyMaskToPixelDataOptions, type Color32, type IP
  * @returns true if any pixels were actually modified.
  */
 export function applyAlphaMaskToPixelData(
-  target: IPixelData32,
+  target: PixelData32,
   mask: AlphaMask,
   opts?: ApplyMaskToPixelDataOptions,
 ): boolean {
   const targetX = opts?.x ?? 0
   const targetY = opts?.y ?? 0
-  const width = opts?.w ?? target.width
-  const height = opts?.h ?? target.height
+  const width = opts?.w ?? target.w
+  const height = opts?.h ?? target.h
   const globalAlpha = opts?.alpha ?? 255
   const mx = opts?.mx ?? 0
   const my = opts?.my ?? 0
@@ -37,8 +39,8 @@ export function applyAlphaMaskToPixelData(
     y = 0
   }
 
-  w = Math.min(w, target.width - x)
-  h = Math.min(h, target.height - y)
+  w = Math.min(w, target.w - x)
+  h = Math.min(h, target.h - y)
 
   if (w <= 0) return false
   if (h <= 0) return false
@@ -70,8 +72,8 @@ export function applyAlphaMaskToPixelData(
   const xShift = sX0 - startX
   const yShift = sY0 - startY
 
-  const dst32 = target.data32
-  const dw = target.width
+  const dst32 = target.data
+  const dw = target.w
   const dStride = dw - finalW
   const mStride = mPitch - finalW
   const maskData = mask.data
@@ -80,51 +82,86 @@ export function applyAlphaMaskToPixelData(
   let mIdx = sY0 * mPitch + sX0
 
   let didChange = false
-  for (let iy = 0; iy < h; iy++) {
-    for (let ix = 0; ix < w; ix++) {
-      const mVal = maskData[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
-        didChange = true
-      } else if (weight !== 255) {
-        // Merge alpha channel
-        const d = dst32[dIdx]
-        const da = d >>> 24
+  if (invertMask) {
+    for (let iy = 0; iy < finalH; iy++) {
+      for (let ix = 0; ix < finalW; ix++) {
+        const effectiveM = 255 - maskData[mIdx]
 
-        if (da !== 0) {
-          const finalAlpha = da === 255 ? weight : (da * weight + 128) >> 8
+        if (effectiveM === 0) {
+          const current = dst32[dIdx]
+          const next = (current & 0x00ffffff) >>> 0
 
-          const current = dst32[dIdx] as Color32
-          const next = ((d & 0x00ffffff) | (finalAlpha << 24)) >>> 0
           if (current !== next) {
             dst32[dIdx] = next
             didChange = true
           }
+        } else {
+          const t1 = effectiveM * globalAlpha + 128
+          const weight = (t1 + (t1 >> 8)) >> 8
+
+          if (weight < 255) {
+            const current = dst32[dIdx]
+            const da = current >>> 24
+
+            if (da !== 0) {
+              const t2 = da * weight + 128
+              const finalAlpha = (t2 + (t2 >> 8)) >> 8
+              const next = ((current & 0x00ffffff) | (finalAlpha << 24)) >>> 0
+
+              if (current !== next) {
+                dst32[dIdx] = next
+                didChange = true
+              }
+            }
+          }
         }
-      }
 
-      dIdx++
-      mIdx++
+        dIdx++
+        mIdx++
+      }
+      dIdx += dStride
+      mIdx += mStride
     }
+  } else {
+    for (let iy = 0; iy < finalH; iy++) {
+      for (let ix = 0; ix < finalW; ix++) {
+        const effectiveM = maskData[mIdx]
+
+        if (effectiveM === 0) {
+          const current = dst32[dIdx]
+          const next = (current & 0x00ffffff) >>> 0
 
-    dIdx += dStride
-    mIdx += mStride
+          if (current !== next) {
+            dst32[dIdx] = next
+            didChange = true
+          }
+        } else {
+          const t1 = effectiveM * globalAlpha + 128
+          const weight = (t1 + (t1 >> 8)) >> 8
+
+          if (weight < 255) {
+            const current = dst32[dIdx]
+            const da = current >>> 24
+
+            if (da !== 0) {
+              const t2 = da * weight + 128
+              const finalAlpha = (t2 + (t2 >> 8)) >> 8
+              const next = ((current & 0x00ffffff) | (finalAlpha << 24)) >>> 0
+
+              if (current !== next) {
+                dst32[dIdx] = next
+                didChange = true
+              }
+            }
+          }
+        }
+
+        dIdx++
+        mIdx++
+      }
+      dIdx += dStride
+      mIdx += mStride
+    }
   }
   return didChange
 }

package/src/PixelData/applyBinaryMaskToPixelData.ts

@@ -1,4 +1,6 @@
-import { type ApplyMaskToPixelDataOptions, type BinaryMask, type IPixelData32 } from '../_types'
+import { type ApplyMaskToPixelDataOptions } from '../_types'
+import type { BinaryMask } from '../Mask/_mask-types'
+import type { PixelData32 } from './_pixelData-types'
 
 /**
  * Directly applies a mask to a region of PixelData,
@@ -6,14 +8,14 @@ import { type ApplyMaskToPixelDataOptions, type BinaryMask, type IPixelData32 }
  * @returns true if any pixels were actually modified.
  */
 export function applyBinaryMaskToPixelData(
-  target: IPixelData32,
+  target: PixelData32,
   mask: BinaryMask,
   opts?: ApplyMaskToPixelDataOptions,
 ): boolean {
   const targetX = opts?.x ?? 0
   const targetY = opts?.y ?? 0
-  const width = opts?.w ?? target.width
-  const height = opts?.h ?? target.height
+  const width = opts?.w ?? target.w
+  const height = opts?.h ?? target.h
   const globalAlpha = opts?.alpha ?? 255
   const mx = opts?.mx ?? 0
   const my = opts?.my ?? 0
@@ -36,8 +38,8 @@ export function applyBinaryMaskToPixelData(
     y = 0
   }
 
-  w = Math.min(w, target.width - x)
-  h = Math.min(h, target.height - y)
+  w = Math.min(w, target.w - x)
+  h = Math.min(h, target.h - y)
 
   if (w <= 0 || h <= 0) return false
 
@@ -67,8 +69,8 @@ export function applyBinaryMaskToPixelData(
   const xShift = sX0 - startX
   const yShift = sY0 - startY
 
-  const dst32 = target.data32
-  const dw = target.width
+  const dst32 = target.data
+  const dw = target.w
   const dStride = dw - finalW
   const mStride = mPitch - finalW
   const maskData = mask.data

package/src/PixelData/applyMaskToPixelData.ts

@@ -1,16 +1,11 @@
-import {
-  type AlphaMask,
-  type ApplyMaskToPixelDataOptions,
-  type BinaryMask,
-  type IPixelData32,
-  type Mask,
-  MaskType,
-} from '../_types'
+import { type ApplyMaskToPixelDataOptions } from '../_types'
+import { type AlphaMask, type BinaryMask, type Mask, MaskType } from '../Mask/_mask-types'
+import type { PixelData32 } from './_pixelData-types'
 import { applyAlphaMaskToPixelData } from './applyAlphaMaskToPixelData'
 import { applyBinaryMaskToPixelData } from './applyBinaryMaskToPixelData'
 
 export function applyMaskToPixelData(
-  dst: IPixelData32,
+  dst: PixelData32,
   mask: Mask,
   opts?: ApplyMaskToPixelDataOptions,
 ): boolean {

package/src/PixelData/blendColorPixelData.ts

@@ -1,19 +1,20 @@
-import { type Color32, type ColorBlendOptions, type IPixelData32 } from '../_types'
+import { type Color32, type ColorBlendOptions } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { PixelData32 } from './_pixelData-types'
 
 /**
  * Blends a solid color into a target pixel buffer.
  * @returns true if any pixels were actually modified.
  */
 export function blendColorPixelData(
-  target: IPixelData32,
+  target: PixelData32,
   color: Color32,
   opts?: ColorBlendOptions,
 ): boolean {
   const targetX = opts?.x ?? 0
   const targetY = opts?.y ?? 0
-  const width = opts?.w ?? target.width
-  const height = opts?.h ?? target.height
+  const width = opts?.w ?? target.w
+  const height = opts?.h ?? target.h
   const globalAlpha = opts?.alpha ?? 255
   const blendFn = opts?.blendFn ?? sourceOverPerfect
   if (globalAlpha === 0) return false
@@ -39,8 +40,8 @@ export function blendColorPixelData(
     y = 0
   }
 
-  const actualW = Math.min(w, target.width - x)
-  const actualH = Math.min(h, target.height - y)
+  const actualW = Math.min(w, target.w - x)
+  const actualH = Math.min(h, target.h - y)
 
   if (actualW <= 0 || actualH <= 0) return false
 
@@ -53,8 +54,8 @@ export function blendColorPixelData(
     finalSrcColor = ((color & 0x00ffffff) | (a << 24)) >>> 0 as Color32
   }
 
-  const dst32 = target.data32
-  const dw = target.width
+  const dst32 = target.data
+  const dw = target.w
   let dIdx = (y * dw + x) | 0
   const dStride = (dw - actualW) | 0
   let didChange = false

package/src/PixelData/blendColorPixelDataAlphaMask.ts

@@ -1,5 +1,7 @@
-import type { AlphaMask, Color32, ColorBlendMaskOptions, IPixelData32 } from '../_types'
+import type { Color32, ColorBlendMaskOptions } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { AlphaMask } from '../Mask/_mask-types'
+import type { PixelData32 } from './_pixelData-types'
 
 /**
  * Blends a solid color into a target pixel buffer using an alpha mask.
@@ -8,14 +10,14 @@ import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
  * 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 target - The destination {@link IPixelData32} buffer to modify.
+ * @param target - The destination {@link PixelData32} 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.
  * @returns true if any pixels were actually modified.
  */
 export function blendColorPixelDataAlphaMask(
-  target: IPixelData32,
+  target: PixelData32,
   color: Color32,
   mask: AlphaMask,
   opts?: ColorBlendMaskOptions,
@@ -52,16 +54,16 @@ export function blendColorPixelDataAlphaMask(
     y = 0
   }
 
-  actualW = Math.min(actualW, target.width - x)
-  actualH = Math.min(actualH, target.height - y)
+  actualW = Math.min(actualW, target.w - x)
+  actualH = Math.min(actualH, target.h - y)
 
   if (actualW <= 0 || actualH <= 0) return false
 
   const dx = (x - targetX) | 0
   const dy = (y - targetY) | 0
 
-  const dst32 = target.data32
-  const dw = target.width
+  const dst32 = target.data
+  const dw = target.w
   const mPitch = mask.w
   const maskData = mask.data
 

package/src/PixelData/blendColorPixelDataBinaryMask.ts

@@ -1,5 +1,7 @@
-import type { BinaryMask, Color32, ColorBlendMaskOptions, IPixelData32 } from '../_types'
+import type { Color32, ColorBlendMaskOptions } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { BinaryMask } from '../Mask/_mask-types'
+import type { PixelData32 } from './_pixelData-types'
 
 /**
  * Blends a solid color into a target pixel buffer using a binary mask.
@@ -8,14 +10,14 @@ import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
  * 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 target - The destination {@link IPixelData32} buffer to modify.
+ * @param target - The destination {@link PixelData32} 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.
  * @returns true if any pixels were actually modified.
  */
 export function blendColorPixelDataBinaryMask(
-  target: IPixelData32,
+  target: PixelData32,
   color: Color32,
   mask: BinaryMask,
   opts?: ColorBlendMaskOptions,
@@ -50,8 +52,8 @@ export function blendColorPixelDataBinaryMask(
     y = 0
   }
 
-  const actualW = Math.min(w, target.width - x)
-  const actualH = Math.min(h, target.height - y)
+  const actualW = Math.min(w, target.w - x)
+  const actualH = Math.min(h, target.h - y)
 
   if (actualW <= 0 || actualH <= 0) return false
 
@@ -65,8 +67,8 @@ export function blendColorPixelDataBinaryMask(
 
   const dx = (x - targetX) | 0
   const dy = (y - targetY) | 0
-  const dst32 = target.data32
-  const dw = target.width
+  const dst32 = target.data
+  const dw = target.w
   const mPitch = mask.w
   const maskData = mask.data
   let dIdx = (y * dw + x) | 0

package/src/PixelData/blendColorPixelDataMask.ts

@@ -1,9 +1,11 @@
-import { type Color32, type ColorBlendMaskOptions, type IPixelData32, type Mask, MaskType } from '../_types'
+import { type Color32, type ColorBlendMaskOptions } from '../_types'
+import { type Mask, MaskType } from '../Mask/_mask-types'
+import type { PixelData32 } from './_pixelData-types'
 import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
 import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
 
 export function blendColorPixelDataMask(
-  dst: IPixelData32,
+  dst: PixelData32,
   color: Color32,
   mask: Mask,
   opts?: ColorBlendMaskOptions,

package/src/PixelData/blendColorPixelDataPaintAlphaMask.ts

@@ -1,5 +1,7 @@
-import { type Color32, type IPixelData32, type PaintAlphaMask } from '../_types'
+import { type Color32 } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { PaintAlphaMask } from '../Paint/_paint-types'
+import type { PixelData32 } from './_pixelData-types'
 import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
 
 const SCRATCH_OPTS = {
@@ -10,7 +12,7 @@ const SCRATCH_OPTS = {
 }
 
 export function blendColorPixelDataPaintAlphaMask(
-  dst: IPixelData32,
+  dst: PixelData32,
   color: Color32,
   mask: PaintAlphaMask,
   x: number,

package/src/PixelData/blendColorPixelDataPaintBinaryMask.ts

@@ -1,5 +1,7 @@
-import { type Color32, type IPixelData32, type PaintBinaryMask } from '../_types'
+import { type Color32 } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { PaintBinaryMask } from '../Paint/_paint-types'
+import type { PixelData32 } from './_pixelData-types'
 import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
 
 const SCRATCH_OPTS = {
@@ -10,7 +12,7 @@ const SCRATCH_OPTS = {
 }
 
 export function blendColorPixelDataPaintBinaryMask(
-  dst: IPixelData32,
+  dst: PixelData32,
   color: Color32,
   mask: PaintBinaryMask,
   x: number,

package/src/PixelData/blendColorPixelDataPaintMask.ts

@@ -1,5 +1,8 @@
-import { type Color32, type IPixelData32, MaskType, type PaintMask } from '../_types'
+import { type Color32 } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import { MaskType } from '../Mask/_mask-types'
+import type { PaintMask } from '../Paint/_paint-types'
+import type { PixelData32 } from './_pixelData-types'
 import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
 import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
 
@@ -11,7 +14,7 @@ const SCRATCH_OPTS = {
 }
 
 export function blendColorPixelDataPaintMask(
-  dst: IPixelData32,
+  dst: PixelData32,
   color: Color32,
   mask: PaintMask,
   x: number,

package/src/PixelData/blendPixel.ts

@@ -1,8 +1,9 @@
-import type { BlendColor32, Color32, IPixelData32 } from '../_types'
+import type { BlendColor32, Color32 } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { PixelData32 } from './_pixelData-types'
 
 export function blendPixel(
-  target: IPixelData32,
+  target: PixelData32,
   x: number,
   y: number,
   color: Color32,
@@ -11,8 +12,8 @@ export function blendPixel(
 ): boolean {
   if (alpha === 0) return false
 
-  let width = target.width
-  let height = target.height
+  let width = target.w
+  let height = target.h
 
   if (x < 0 || x >= width || y < 0 || y >= height) return false
 
@@ -22,7 +23,7 @@ export function blendPixel(
   // Early exit for transparent source unless we are in an overwrite mode
   if (srcAlpha === 0 && !isOverwrite) return false
 
-  let dst32 = target.data32
+  let dst32 = target.data
   let index = y * width + x
   let finalColor = color
 

package/src/PixelData/blendPixelData.ts

@@ -1,5 +1,6 @@
-import { type Color32, type IPixelData32, type PixelBlendOptions } from '../_types'
+import { type Color32, type PixelBlendOptions } from '../_types'
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { PixelData32 } from './_pixelData-types'
 
 /**
  * Blits source PixelData into a destination PixelData using 32-bit integer bitwise blending.
@@ -16,16 +17,16 @@ import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
  * });
  */
 export function blendPixelData(
-  target: IPixelData32,
-  src: IPixelData32,
+  target: PixelData32,
+  src: PixelData32,
   opts?: PixelBlendOptions,
 ): boolean {
   const targetX = opts?.x ?? 0
   const targetY = opts?.y ?? 0
   const sourceX = opts?.sx ?? 0
   const sourceY = opts?.sy ?? 0
-  const width = opts?.w ?? src.width
-  const height = opts?.h ?? src.height
+  const width = opts?.w ?? src.w
+  const height = opts?.h ?? src.h
   const globalAlpha = opts?.alpha ?? 255
   const blendFn = opts?.blendFn ?? sourceOverPerfect
 
@@ -48,8 +49,8 @@ export function blendPixelData(
     h += sy
     sy = 0
   }
-  w = Math.min(w, src.width - sx)
-  h = Math.min(h, src.height - sy)
+  w = Math.min(w, src.w - sx)
+  h = Math.min(h, src.h - sy)
   if (x < 0) {
     sx -= x
     w += x
@@ -61,14 +62,14 @@ export function blendPixelData(
     y = 0
   }
 
-  const actualW = Math.min(w, target.width - x)
-  const actualH = Math.min(h, target.height - y)
+  const actualW = Math.min(w, target.w - x)
+  const actualH = Math.min(h, target.h - y)
   if (actualW <= 0 || actualH <= 0) return false
 
-  const dst32 = target.data32
-  const src32 = src.data32
-  const dw = target.width
-  const sw = src.width
+  const dst32 = target.data
+  const src32 = src.data
+  const dw = target.w
+  const sw = src.w
 
   let dIdx = (y * dw + x) | 0
   let sIdx = (sy * sw + sx) | 0