pixel-data-js 0.25.2 → 0.27.0

package/src/PixelData/blendColorPixelDataAlphaMask.ts

@@ -8,27 +8,27 @@ 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 dst - The destination {@link IPixelData32} buffer to modify.
+ * @param target - The destination {@link IPixelData32} 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(
-  dst: IPixelData32,
+  target: IPixelData32,
   color: Color32,
   mask: AlphaMask,
-  opts: ColorBlendMaskOptions = {},
+  opts?: ColorBlendMaskOptions,
 ): boolean {
-  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
+  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 false
 
@@ -52,16 +52,16 @@ export function blendColorPixelDataAlphaMask(
     y = 0
   }
 
-  actualW = Math.min(actualW, dst.width - x)
-  actualH = Math.min(actualH, dst.height - y)
+  actualW = Math.min(actualW, target.width - x)
+  actualH = Math.min(actualH, target.height - y)
 
   if (actualW <= 0 || actualH <= 0) return false
 
   const dx = (x - targetX) | 0
   const dy = (y - targetY) | 0
 
-  const dst32 = dst.data32
-  const dw = dst.width
+  const dst32 = target.data32
+  const dw = target.width
   const mPitch = mask.w
   const maskData = mask.data
 

package/src/PixelData/blendColorPixelDataBinaryMask.ts

@@ -8,27 +8,27 @@ 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 dst - The destination {@link IPixelData32} buffer to modify.
+ * @param target - The destination {@link IPixelData32} 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(
-  dst: IPixelData32,
+  target: IPixelData32,
   color: Color32,
   mask: BinaryMask,
-  opts: ColorBlendMaskOptions = {},
+  opts?: ColorBlendMaskOptions,
 ): boolean {
-  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
+  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 false
 
@@ -50,8 +50,8 @@ export function blendColorPixelDataBinaryMask(
     y = 0
   }
 
-  const actualW = Math.min(w, dst.width - x)
-  const actualH = Math.min(h, dst.height - y)
+  const actualW = Math.min(w, target.width - x)
+  const actualH = Math.min(h, target.height - y)
 
   if (actualW <= 0 || actualH <= 0) return false
 
@@ -65,8 +65,8 @@ export function blendColorPixelDataBinaryMask(
 
   const dx = (x - targetX) | 0
   const dy = (y - targetY) | 0
-  const dst32 = dst.data32
-  const dw = dst.width
+  const dst32 = target.data32
+  const dw = target.width
   const mPitch = mask.w
   const maskData = mask.data
   let dIdx = (y * dw + x) | 0

package/src/PixelData/blendColorPixelDataMask.ts

@@ -0,0 +1,16 @@
+import { type Color32, type ColorBlendMaskOptions, type IPixelData32, type Mask, MaskType } from '../_types'
+import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
+import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
+
+export function blendColorPixelDataMask(
+  dst: IPixelData32,
+  color: Color32,
+  mask: Mask,
+  opts?: ColorBlendMaskOptions,
+): boolean {
+  if (mask.type === MaskType.BINARY) {
+    return blendColorPixelDataBinaryMask(dst, color, mask, opts)
+  } else {
+    return blendColorPixelDataAlphaMask(dst, color, mask, opts)
+  }
+}

package/src/PixelData/blendColorPixelDataPaintAlphaMask.ts

@@ -0,0 +1,30 @@
+import { type Color32, type IPixelData32, type PaintAlphaMask } from '../_types'
+import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
+
+const SCRATCH_OPTS = {
+  x: 0,
+  y: 0,
+  alpha: 255,
+  blendFn: sourceOverPerfect,
+}
+
+export function blendColorPixelDataPaintAlphaMask(
+  dst: IPixelData32,
+  color: Color32,
+  mask: PaintAlphaMask,
+  x: number,
+  y: number,
+  alpha = 255,
+  blendFn = sourceOverPerfect,
+): boolean {
+  const tx = x + mask.centerOffsetX
+  const ty = y + mask.centerOffsetY
+
+  SCRATCH_OPTS.x = tx
+  SCRATCH_OPTS.y = ty
+  SCRATCH_OPTS.alpha = alpha
+  SCRATCH_OPTS.blendFn = blendFn
+
+  return blendColorPixelDataAlphaMask(dst, color, mask, SCRATCH_OPTS)
+}

package/src/PixelData/blendColorPixelDataPaintBinaryMask.ts

@@ -0,0 +1,30 @@
+import { type Color32, type IPixelData32, type PaintBinaryMask } from '../_types'
+import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
+
+const SCRATCH_OPTS = {
+  x: 0,
+  y: 0,
+  alpha: 255,
+  blendFn: sourceOverPerfect,
+}
+
+export function blendColorPixelDataPaintBinaryMask(
+  dst: IPixelData32,
+  color: Color32,
+  mask: PaintBinaryMask,
+  x: number,
+  y: number,
+  alpha = 255,
+  blendFn = sourceOverPerfect,
+): boolean {
+  const tx = x + mask.centerOffsetX
+  const ty = y + mask.centerOffsetY
+
+  SCRATCH_OPTS.x = tx
+  SCRATCH_OPTS.y = ty
+  SCRATCH_OPTS.alpha = alpha
+  SCRATCH_OPTS.blendFn = blendFn
+
+  return blendColorPixelDataBinaryMask(dst, color, mask, SCRATCH_OPTS)
+}

package/src/PixelData/blendColorPixelDataPaintMask.ts

@@ -0,0 +1,35 @@
+import { type Color32, type IPixelData32, MaskType, type PaintMask } from '../_types'
+import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import { blendColorPixelDataAlphaMask } from './blendColorPixelDataAlphaMask'
+import { blendColorPixelDataBinaryMask } from './blendColorPixelDataBinaryMask'
+
+const SCRATCH_OPTS = {
+  x: 0,
+  y: 0,
+  alpha: 255,
+  blendFn: sourceOverPerfect,
+}
+
+export function blendColorPixelDataPaintMask(
+  dst: IPixelData32,
+  color: Color32,
+  mask: PaintMask,
+  x: number,
+  y: number,
+  alpha = 255,
+  blendFn = sourceOverPerfect,
+): boolean {
+  const tx = x + mask.centerOffsetX
+  const ty = y + mask.centerOffsetY
+
+  SCRATCH_OPTS.x = tx
+  SCRATCH_OPTS.y = ty
+  SCRATCH_OPTS.alpha = alpha
+  SCRATCH_OPTS.blendFn = blendFn
+
+  if (mask.type === MaskType.BINARY) {
+    return blendColorPixelDataBinaryMask(dst, color, mask, SCRATCH_OPTS)
+  } else {
+    return blendColorPixelDataAlphaMask(dst, color, mask, SCRATCH_OPTS)
+  }
+}

package/src/PixelData/blendPixelData.ts

@@ -16,20 +16,18 @@ import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
  * });
  */
 export function blendPixelData(
-  dst: IPixelData32,
+  target: IPixelData32,
   src: IPixelData32,
-  opts: PixelBlendOptions = {},
+  opts?: PixelBlendOptions,
 ): boolean {
-  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 = sourceOverPerfect,
-  } = opts
+  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 globalAlpha = opts?.alpha ?? 255
+  const blendFn = opts?.blendFn ?? sourceOverPerfect
 
   if (globalAlpha === 0) return false
 
@@ -63,13 +61,13 @@ export function blendPixelData(
     y = 0
   }
 
-  const actualW = Math.min(w, dst.width - x)
-  const actualH = Math.min(h, dst.height - y)
+  const actualW = Math.min(w, target.width - x)
+  const actualH = Math.min(h, target.height - y)
   if (actualW <= 0 || actualH <= 0) return false
 
-  const dst32 = dst.data32
+  const dst32 = target.data32
   const src32 = src.data32
-  const dw = dst.width
+  const dw = target.width
   const sw = src.width
 
   let dIdx = (y * dw + x) | 0

package/src/PixelData/blendPixelDataAlphaMask.ts

@@ -2,24 +2,22 @@ import { type AlphaMask, type Color32, type IPixelData32, type PixelBlendMaskOpt
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
 
 export function blendPixelDataAlphaMask(
-  dst: IPixelData32,
+  target: IPixelData32,
   src: IPixelData32,
   alphaMask: AlphaMask,
-  opts: PixelBlendMaskOptions = {},
+  opts?: PixelBlendMaskOptions,
 ): boolean {
-  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 = sourceOverPerfect,
-    mx = 0,
-    my = 0,
-    invertMask = false,
-  } = opts
+  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 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 false
 
@@ -54,12 +52,12 @@ export function blendPixelDataAlphaMask(
     y = 0
   }
 
-  const actualW = Math.min(w, dst.width - x)
-  const actualH = Math.min(h, dst.height - y)
+  const actualW = Math.min(w, target.width - x)
+  const actualH = Math.min(h, target.height - y)
   if (actualW <= 0 || actualH <= 0) return false
 
   // 2. Index Setup
-  const dw = dst.width
+  const dw = target.width
   const sw = src.width
   const mPitch = alphaMask.w
   const maskData = alphaMask.data
@@ -69,7 +67,7 @@ export function blendPixelDataAlphaMask(
   const dx = (x - targetX) | 0
   const dy = (y - targetY) | 0
 
-  const dst32 = dst.data32
+  const dst32 = target.data32
   const src32 = src.data32
 
   let dIdx = (y * dw + x) | 0

package/src/PixelData/blendPixelDataBinaryMask.ts

@@ -2,24 +2,22 @@ import type { BinaryMask, Color32, IPixelData32, PixelBlendMaskOptions } from '.
 import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
 
 export function blendPixelDataBinaryMask(
-  dst: IPixelData32,
+  target: IPixelData32,
   src: IPixelData32,
   binaryMask: BinaryMask,
-  opts: PixelBlendMaskOptions = {},
+  opts?: PixelBlendMaskOptions,
 ): boolean {
-  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 = sourceOverPerfect,
-    mx = 0,
-    my = 0,
-    invertMask = false,
-  } = opts
+  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 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 false
 
@@ -56,8 +54,8 @@ export function blendPixelDataBinaryMask(
     y = 0
   }
 
-  const actualW = Math.min(w, dst.width - x)
-  const actualH = Math.min(h, dst.height - y)
+  const actualW = Math.min(w, target.width - x)
+  const actualH = Math.min(h, target.height - y)
 
   if (actualW <= 0 || actualH <= 0) return false
 
@@ -67,9 +65,9 @@ export function blendPixelDataBinaryMask(
   const dx = (x - targetX) | 0
   const dy = (y - targetY) | 0
 
-  const dst32 = dst.data32
+  const dst32 = target.data32
   const src32 = src.data32
-  const dw = dst.width
+  const dw = target.width
   const sw = src.width
   const mPitch = binaryMask.w
   const maskData = binaryMask.data

package/src/PixelData/blendPixelDataMask.ts

@@ -0,0 +1,16 @@
+import { type IPixelData32, type Mask, MaskType, type PixelBlendMaskOptions } from '../_types'
+import { blendPixelDataAlphaMask } from './blendPixelDataAlphaMask'
+import { blendPixelDataBinaryMask } from './blendPixelDataBinaryMask'
+
+export function blendPixelDataMask(
+  target: IPixelData32,
+  src: IPixelData32,
+  mask: Mask,
+  opts?: PixelBlendMaskOptions,
+): boolean {
+  if (mask.type === MaskType.BINARY) {
+    return blendPixelDataBinaryMask(target, src, mask, opts)
+  } else {
+    return blendPixelDataAlphaMask(target, src, mask, opts)
+  }
+}

package/src/PixelData/blendPixelDataPaintBuffer.ts

@@ -10,8 +10,8 @@ const SCRATCH_OPTS = {
 }
 
 export function blendPixelDataPaintBuffer(
-  paintBuffer: PaintBuffer,
   target: IPixelData32,
+  paintBuffer: PaintBuffer,
   alpha = 255,
   blendFn?: BlendColor32,
   blendPixelDataFn = blendPixelData,

package/src/PixelData/{clearPixelData.ts → clearPixelDataFast.ts}

@@ -3,9 +3,9 @@ import { fillPixelDataFast } from './fillPixelDataFast'
 
 /**
  * Clears a region of the PixelData to transparent (0x00000000).
- * Internally uses the optimized fillPixelData.
+ * Internally uses the optimized fillPixelDataFast.
  */
-export function clearPixelData(
+export function clearPixelDataFast(
   dst: IPixelData32,
   rect?: Partial<BinaryMaskRect>,
 ): void {

package/src/PixelData/fillPixelDataBinaryMask.ts

@@ -5,22 +5,19 @@ const SCRATCH_RECT = makeClippedRect()
 
 /**
  * Fills a region of the {@link IPixelData32} buffer with a solid color using a mask.
- * @param dst - The target to modify.
+ * @param target - 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: IPixelData32,
+  target: IPixelData32,
   color: Color32,
   mask: BinaryMask,
-  alpha = 255,
   x = 0,
   y = 0,
 ): boolean {
-  if (alpha === 0) return false
 
   const maskW = mask.w
   const maskH = mask.h
@@ -30,8 +27,8 @@ export function fillPixelDataBinaryMask(
     y,
     maskW,
     maskH,
-    dst.width,
-    dst.height,
+    target.width,
+    target.height,
     SCRATCH_RECT,
   )
 
@@ -45,19 +42,8 @@ export function fillPixelDataBinaryMask(
   } = 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
-  }
+  const dst32 = target.data32
+  const dw = target.width
 
   let hasChanged = false
 
@@ -75,8 +61,8 @@ export function fillPixelDataBinaryMask(
 
       if (maskData[maskIndex]) {
         const current = dst32[dstRowOffset + currentX]
-        if (current !== finalCol) {
-          dst32[dstRowOffset + currentX] = finalCol
+        if (current !== color) {
+          dst32[dstRowOffset + currentX] = color
           hasChanged = true
         }
       }

package/src/PixelData/fillPixelDataFast.ts

@@ -8,13 +8,13 @@ const SCRATCH_RECT = makeClippedRect()
  * This function is faster than {@link fillPixelData} but does not
  * return a boolean value indicating changes were made.
  *
- * @param dst - The target to modify.
+ * @param target - 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 fillPixelDataFast(
-  dst: IPixelData32,
+  target: IPixelData32,
   color: Color32,
   rect?: Partial<Rect>,
 ): void

package/src/PixelData/invertPixelData.ts

@@ -4,22 +4,19 @@ import { makeClippedRect, resolveRectClipping } from '../Internal/resolveClippin
 const SCRATCH_RECT = makeClippedRect()
 
 export function invertPixelData(
-  pixelData: IPixelData32,
-  opts: PixelMutateOptions = {},
+  target: IPixelData32,
+  opts?: PixelMutateOptions,
 ): boolean {
-  const dst = pixelData
-  const {
-    x: targetX = 0,
-    y: targetY = 0,
-    w: width = pixelData.width,
-    h: height = pixelData.height,
-    mask,
-    mx = 0,
-    my = 0,
-    invertMask = false,
-  } = opts
+  const mask = opts?.mask
+  const targetX = opts?.x ?? 0
+  const targetY = opts?.y ?? 0
+  const mx = opts?.mx ?? 0
+  const my = opts?.my ?? 0
+  const width = opts?.w ?? target.width
+  const height = opts?.h ?? target.height
+  const invertMask = opts?.invertMask ?? false
 
-  const clip = resolveRectClipping(targetX, targetY, width, height, dst.width, dst.height, SCRATCH_RECT)
+  const clip = resolveRectClipping(targetX, targetY, width, height, target.width, target.height, SCRATCH_RECT)
 
   if (!clip.inBounds) return false
 
@@ -30,8 +27,8 @@ export function invertPixelData(
     h: actualH,
   } = clip
 
-  const dst32 = dst.data32
-  const dw = dst.width
+  const dst32 = target.data32
+  const dw = target.width
   const mPitch = mask?.w ?? width
 
   const dx = x - targetX

package/src/_types.ts

@@ -1,5 +1,3 @@
-import { PixelWriter, sourceOverPerfect } from './index'
-
 /** ALL values are 0-255 (including alpha which in CSS is 0-1) */
 export type RGBA = { r: number, g: number, b: number, a: number }
 
@@ -63,20 +61,22 @@ export enum MaskType {
   BINARY
 }
 
-export interface Mask {
+export interface BaseMask {
   readonly type: MaskType
   readonly data: Uint8Array
   readonly w: number
   readonly h: number
 }
 
+export type Mask = BinaryMask | AlphaMask
+
 /** Strictly 0 or 1 */
-export interface BinaryMask extends Mask {
+export interface BinaryMask extends BaseMask {
   readonly type: MaskType.BINARY
 }
 
 /** Strictly 0-255 */
-export interface AlphaMask extends Mask {
+export interface AlphaMask extends BaseMask {
   readonly type: MaskType.ALPHA
 }
 
@@ -210,6 +210,9 @@ export interface ColorBlendOptions extends PixelRect, Alpha {
 export interface ColorBlendMaskOptions extends ColorBlendOptions, MaskOffset, InvertMask {
 }
 
+export interface ColorBlendPaintMaskOptions extends Omit<ColorBlendOptions, 'w' | 'h'> {
+}
+
 export type MaskRect<T extends MaskType> = Rect & {
   type: T
   data: Uint8Array
@@ -235,8 +238,6 @@ export type NullableMaskRect = Rect & ({
   data?: null
 })
 
-export type HistoryMutator<T extends {}, D extends {}> = (writer: PixelWriter<any>, deps?: Partial<D>) => T
-
 export interface IPixelData32 {
   readonly data32: Uint32Array
   readonly width: number