pixel-data-js 0.31.0 → 0.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-data-js",
   "type": "module",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "packageManager": "pnpm@10.33.0",
   "description": "JS Pixel and ImageData operations",
   "author": {

package/src/ImageData/extractImageData.ts

@@ -0,0 +1,55 @@
+import type { Rect } from '../Rect/_rect-types'
+import type { ImageDataLike } from './_ImageData-types'
+import { extractImageDataBuffer } from './extractImageDataBuffer'
+
+/**
+ * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
+ * source into a new {@link Uint8ClampedArray}.
+ *
+ * This is a "read-only" operation that returns a copy of the pixel data.
+ *
+ * @param imageData - The source image data to read from.
+ * @param rect - A rect defining the region to extract.
+ * @returns A buffer containing the RGBA pixel data of the region.
+ */
+export function extractImageData(
+  imageData: ImageDataLike,
+  rect: Rect,
+): ImageData | null
+/**
+ * @param imageData - The source image data to read from.
+ * @param x - The starting horizontal coordinate.
+ * @param y - The starting vertical coordinate.
+ * @param w - The width of the region to extract.
+ * @param h - The height of the region to extract.
+ * @returns A buffer containing the RGBA pixel data of the region.
+ */
+export function extractImageData(
+  imageData: ImageDataLike,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): ImageData | null
+export function extractImageData(
+  imageData: ImageDataLike,
+  _x: Rect | number,
+  _y?: number,
+  _w?: number,
+  _h?: number,
+): ImageData | null {
+  const { x, y, w, h } = typeof _x === 'object'
+    ? _x
+    : { x: _x, y: _y!, w: _w!, h: _h! }
+
+  if (w <= 0) return null
+  if (h <= 0) return null
+
+  const result = new ImageData(w, h)
+
+  const buffer = extractImageDataBuffer(imageData, x, y, w, h)
+  result.data.set(buffer)
+
+  return result
+
+}

package/src/ImageData/extractImageDataBuffer.ts

@@ -1,9 +1,6 @@
 import type { Rect } from '../Rect/_rect-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
 import type { ImageDataLike } from './_ImageData-types'
 
-const SCRATCH_BLIT = makeClippedBlit()
-
 /**
  * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
  * source into a new {@link Uint8ClampedArray}.
@@ -43,37 +40,69 @@ export function extractImageDataBuffer(
   const { x, y, w, h } = typeof _x === 'object'
     ? _x
     : { x: _x, y: _y!, w: _w!, h: _h! }
+  if (w <= 0) return new Uint8ClampedArray(0)
+  if (h <= 0) return new Uint8ClampedArray(0)
+
+  const srcW = imageData.width
+  const srcH = imageData.height
+  const src = imageData.data
+
+  const outLen = w * h * 4
+  const out = new Uint8ClampedArray(outLen)
+
+  let srcX = x
+  let srcY = y
+  let dstX = 0
+  let dstY = 0
+  let copyW = w
+  let copyH = h
+
+  if (srcX < 0) {
+    dstX = -srcX
+    copyW += srcX
+    srcX = 0
+  }
+
+  if (srcY < 0) {
+    dstY = -srcY
+    copyH += srcY
+    srcY = 0
+  }
+
+  copyW = Math.min(copyW, srcW - srcX)
+  copyH = Math.min(copyH, srcH - srcY)
+
+  if (copyW <= 0) return out
+  if (copyH <= 0) return out
 
-  const { width: srcW, height: srcH, data: src } = imageData
-  // Safety check for invalid dimensions
-  if (w <= 0 || h <= 0) return new Uint8ClampedArray(0)
-  const out = new Uint8ClampedArray(w * h * 4)
+  // 2. Perform high-speed block copy
+  // Attempt to use a 32-bit view if the buffer is memory-aligned.
+  // This reduces loop iterations and arithmetic by 4x.
+  const isAligned = src.byteOffset % 4 === 0
 
-  const clip = resolveBlitClipping(
-    0,
-    0,
-    x,
-    y,
-    w,
-    h,
-    w,
-    h,
-    srcW,
-    srcH,
-    SCRATCH_BLIT,
-  )
+  if (isAligned) {
+    const srcLen32 = src.byteLength / 4
+    const src32 = new Uint32Array(src.buffer, src.byteOffset, srcLen32)
+    const out32 = new Uint32Array(out.buffer)
 
-  if (!clip.inBounds) return out
+    for (let row = 0; row < copyH; row++) {
+      const srcStart = (srcY + row) * srcW + srcX
+      const dstStart = (dstY + row) * w + dstX
+      const chunk = src32.subarray(srcStart, srcStart + copyW)
 
-  const { x: dstX, y: dstY, sx: srcX, sy: srcY, w: copyW, h: copyH } = clip
-  const rowLen = copyW * 4
+      out32.set(chunk, dstStart)
+    }
+  } else {
+    // Fallback for unaligned data
+    const rowLen = copyW * 4
 
-  for (let row = 0; row < copyH; row++) {
-    const srcStart = ((srcY + row) * srcW + srcX) * 4
-    const dstStart = ((dstY + row) * w + dstX) * 4
+    for (let row = 0; row < copyH; row++) {
+      const srcStart = ((srcY + row) * srcW + srcX) * 4
+      const dstStart = ((dstY + row) * w + dstX) * 4
+      const chunk = src.subarray(srcStart, srcStart + rowLen)
 
-    // Perform the high-speed bulk copy
-    out.set(src.subarray(srcStart, srcStart + rowLen), dstStart)
+      out.set(chunk, dstStart)
+    }
   }
 
   return out

package/src/ImageData/writeImageData.ts

@@ -1,8 +1,3 @@
-import { MaskType } from '../Mask/_mask-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
-
-const SCRATCH_BLIT = makeClippedBlit()
-
 /**
  * Writes image data from a source to a target with support for clipping and alpha masking.
  *
@@ -10,88 +5,72 @@ const SCRATCH_BLIT = makeClippedBlit()
  * @param source - The source ImageData to read from.
  * @param x - The x-coordinate in the target where drawing starts.
  * @param y - The y-coordinate in the target where drawing starts.
- * @param sx - The x-coordinate in the source to start copying from.
- * @param sy - The y-coordinate in the source to start copying from.
- * @param sw - The width of the rectangle to copy.
- * @param sh - The height of the rectangle to copy.
- * @param mask - An optional Uint8Array mask (0-255). 0 is transparent, 255 is opaque.
- * @param maskType - type of mask
  */
 export function writeImageData(
   target: ImageData,
   source: ImageData,
   x: number,
   y: number,
-  sx: number = 0,
-  sy: number = 0,
-  sw: number = source.width,
-  sh: number = source.height,
-  mask: Uint8Array | null = null,
-  maskType: MaskType = MaskType.BINARY,
 ): void {
   const dstW = target.width
   const dstH = target.height
-  const dstData = target.data
+  const dst = target.data
+
   const srcW = source.width
-  const srcData = source.data
+  const srcH = source.height
+  const src = source.data
 
-  const clip = resolveBlitClipping(
-    x, y, sx, sy, sw, sh,
-    dstW, dstH, srcW, source.height,
-    SCRATCH_BLIT,
-  )
+  let dstX = x
+  let dstY = y
+  let srcX = 0
+  let srcY = 0
+  let copyW = srcW
+  let copyH = srcH
 
-  if (!clip.inBounds) return
+  if (dstX < 0) {
+    srcX = -dstX
+    copyW += dstX
+    dstX = 0
+  }
 
-  const {
-    x: dstX,
-    y: dstY,
-    sx: srcX,
-    sy: srcY,
-    w: copyW,
-    h: copyH,
-  } = clip
+  if (dstY < 0) {
+    srcY = -dstY
+    copyH += dstY
+    dstY = 0
+  }
+
+  copyW = Math.min(copyW, dstW - dstX)
+  copyH = Math.min(copyH, dstH - dstY)
 
-  const useMask = !!mask
+  if (copyW <= 0) return
+  if (copyH <= 0) return
 
-  for (let row = 0; row < copyH; row++) {
-    const currentDstY = dstY + row
-    const currentSrcY = srcY + row
+  const isDstAligned = dst.byteOffset % 4 === 0
+  const isSrcAligned = src.byteOffset % 4 === 0
 
-    const dstStart = (currentDstY * dstW + dstX) * 4
-    const srcStart = (currentSrcY * srcW + srcX) * 4
+  if (isDstAligned && isSrcAligned) {
+    const dstLen32 = dst.byteLength / 4
+    const dst32 = new Uint32Array(dst.buffer, dst.byteOffset, dstLen32)
 
-    if (useMask && mask) {
-      for (let ix = 0; ix < copyW; ix++) {
-        const mi = currentSrcY * srcW + (srcX + ix)
-        const alpha = mask[mi]
+    const srcLen32 = src.byteLength / 4
+    const src32 = new Uint32Array(src.buffer, src.byteOffset, srcLen32)
 
-        if (alpha === 0) {
-          continue
-        }
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = (dstY + row) * dstW + dstX
+      const srcStart = (srcY + row) * srcW + srcX
+      const chunk = src32.subarray(srcStart, srcStart + copyW)
 
-        const di = dstStart + (ix * 4)
-        const si = srcStart + (ix * 4)
+      dst32.set(chunk, dstStart)
+    }
+  } else {
+    const rowLen = copyW * 4
 
-        if (maskType === MaskType.BINARY || alpha === 255) {
-          dstData[di] = srcData[si]
-          dstData[di + 1] = srcData[si + 1]
-          dstData[di + 2] = srcData[si + 2]
-          dstData[di + 3] = srcData[si + 3]
-        } else {
-          const a = alpha / 255
-          const invA = 1 - a
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = ((dstY + row) * dstW + dstX) * 4
+      const srcStart = ((srcY + row) * srcW + srcX) * 4
+      const chunk = src.subarray(srcStart, srcStart + rowLen)
 
-          dstData[di] = srcData[si] * a + dstData[di] * invA
-          dstData[di + 1] = srcData[si + 1] * a + dstData[di + 1] * invA
-          dstData[di + 2] = srcData[si + 2] * a + dstData[di + 2] * invA
-          dstData[di + 3] = srcData[si + 3] * a + dstData[di + 3] * invA
-        }
-      }
-    } else {
-      const byteLen = copyW * 4
-      const sub = srcData.subarray(srcStart, srcStart + byteLen)
-      dstData.set(sub, dstStart)
+      dst.set(chunk, dstStart)
     }
   }
 }

package/src/ImageData/writeImageDataBuffer.ts

@@ -1,7 +1,4 @@
 import type { Rect } from '../Rect/_rect-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
-
-const SCRATCH_BLIT = makeClippedBlit()
 
 /**
  * Copies a pixel buffer into a specific region of an {@link ImageData} object.
@@ -43,43 +40,84 @@ export function writeImageDataBuffer(
   _w?: number,
   _h?: number,
 ): void {
-  const { x, y, w, h } = typeof _x === 'object'
-    ? _x
-    : { x: _x, y: _y!, w: _w!, h: _h! }
-
-  const { width: dstW, height: dstH, data: dst } = target
-
-  const clip = resolveBlitClipping(
-    x,
-    y,
-    0,
-    0,
-    w,
-    h,
-    dstW,
-    dstH,
-    w,
-    h,
-    SCRATCH_BLIT,
-  )
-
-  if (!clip.inBounds) return
-
-  const {
-    x: dstX,
-    y: dstY,
-    sx: srcX,
-    sy: srcY,
-    w: copyW,
-    h: copyH,
-  } = clip
-
-  const rowLen = copyW * 4
-
-  for (let row = 0; row < copyH; row++) {
-    const dstStart = ((dstY + row) * dstW + dstX) * 4
-    const srcStart = ((srcY + row) * w + srcX) * 4
-
-    dst.set(data.subarray(srcStart, srcStart + rowLen), dstStart)
+  let x: number
+  let y: number
+  let w: number
+  let h: number
+
+  if (typeof _x === 'object') {
+    x = _x.x
+    y = _x.y
+    w = _x.w
+    h = _x.h
+  } else {
+    x = _x
+    y = _y!
+    w = _w!
+    h = _h!
+  }
+
+  if (w <= 0) return
+  if (h <= 0) return
+
+  const dstW = target.width
+  const dstH = target.height
+  const dst = target.data
+
+  // Inline clipping logic for destination boundaries
+  let dstX = x
+  let dstY = y
+  let srcX = 0
+  let srcY = 0
+  let copyW = w
+  let copyH = h
+
+  if (dstX < 0) {
+    srcX = -dstX
+    copyW += dstX
+    dstX = 0
+  }
+
+  if (dstY < 0) {
+    srcY = -dstY
+    copyH += dstY
+    dstY = 0
+  }
+
+  copyW = Math.min(copyW, dstW - dstX)
+  copyH = Math.min(copyH, dstH - dstY)
+
+  if (copyW <= 0) return
+  if (copyH <= 0) return
+
+  // Fast-path: Both arrays must be 4-byte aligned to use Uint32Array safely
+  const isDstAligned = dst.byteOffset % 4 === 0
+  const isSrcAligned = data.byteOffset % 4 === 0
+
+  if (isDstAligned && isSrcAligned) {
+    const dstLen32 = dst.byteLength / 4
+    const dst32 = new Uint32Array(dst.buffer, dst.byteOffset, dstLen32)
+
+    const srcLen32 = data.byteLength / 4
+    const src32 = new Uint32Array(data.buffer, data.byteOffset, srcLen32)
+
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = (dstY + row) * dstW + dstX
+      const srcStart = (srcY + row) * w + srcX
+      const chunk = src32.subarray(srcStart, srcStart + copyW)
+
+      dst32.set(chunk, dstStart)
+    }
+  } else {
+    // Fallback for unaligned data arrays
+    const rowLen = copyW * 4
+
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = ((dstY + row) * dstW + dstX) * 4
+      const srcStart = ((srcY + row) * w + srcX) * 4
+      const chunk = data.subarray(srcStart, srcStart + rowLen)
+
+      dst.set(chunk, dstStart)
+    }
   }
 }

package/src/PixelData/extractPixelDataBuffer.ts

@@ -1,15 +1,21 @@
 import type { Rect } from '../Rect/_rect-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
 import type { PixelData32 } from './_pixelData-types'
 
-const SCRATCH_BLIT = makeClippedBlit()
-
 /**
  * Extracts a rectangular region of pixels from PixelData.
  * Returns a new Uint32Array containing the extracted pixels.
  */
-export function extractPixelDataBuffer(source: PixelData32, rect: Rect): Uint32Array
-export function extractPixelDataBuffer(source: PixelData32, x: number, y: number, w: number, h: number): Uint32Array
+export function extractPixelDataBuffer(
+  source: PixelData32,
+  rect: Rect,
+): Uint32Array
+export function extractPixelDataBuffer(
+  source: PixelData32,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): Uint32Array
 export function extractPixelDataBuffer(
   source: PixelData32,
   _x: Rect | number,
@@ -17,56 +23,63 @@ export function extractPixelDataBuffer(
   _w?: number,
   _h?: number,
 ): Uint32Array {
-  const { x, y, w, h } = typeof _x === 'object'
-    ? _x
-    : { x: _x, y: _y!, w: _w!, h: _h! }
+  let x: number
+  let y: number
+  let w: number
+  let h: number
+
+  if (typeof _x === 'object') {
+    x = _x.x
+    y = _x.y
+    w = _x.w
+    h = _x.h
+  } else {
+    x = _x
+    y = _y!
+    w = _w!
+    h = _h!
+  }
 
   const srcW = source.w
   const srcH = source.h
   const srcData = source.data
 
-  // Safety check for empty or invalid dimensions
-  if (w <= 0 || h <= 0) {
-    return new Uint32Array(0)
-  }
+  if (w <= 0) return new Uint32Array(0)
+  if (h <= 0) return new Uint32Array(0)
 
   const dstData = new Uint32Array(w * h)
 
-  // We map from Source (srcW, srcH) at (x,y)
-  // To Dest (w, h) at (0,0)
-  // Note: resolveBlitClipping usually takes (dstX, dstY, srcX, srcY...)
-  // Here we are "blitting" FROM x,y TO 0,0.
-  const clip = resolveBlitClipping(
-    0,
-    0,
-    x,
-    y,
-    w,
-    h,
-    w,
-    h,
-    srcW,
-    srcH,
-    SCRATCH_BLIT,
-  )
+  // Inline clipping logic to avoid object allocations
+  let srcX = x
+  let srcY = y
+  let dstX = 0
+  let dstY = 0
+  let copyW = w
+  let copyH = h
+
+  if (srcX < 0) {
+    dstX = -srcX
+    copyW += srcX
+    srcX = 0
+  }
 
-  if (!clip.inBounds) return dstData
+  if (srcY < 0) {
+    dstY = -srcY
+    copyH += srcY
+    srcY = 0
+  }
 
-  const {
-    x: dstX,
-    y: dstY,
-    sx: srcX,
-    sy: srcY,
-    w: copyW,
-    h: copyH,
-  } = clip
+  copyW = Math.min(copyW, srcW - srcX)
+  copyH = Math.min(copyH, srcH - srcY)
+
+  if (copyW <= 0) return dstData
+  if (copyH <= 0) return dstData
 
   for (let row = 0; row < copyH; row++) {
     const srcStart = (srcY + row) * srcW + srcX
     const dstStart = (dstY + row) * w + dstX
-
-    // Perform the high-speed 32-bit bulk copy
     const chunk = srcData.subarray(srcStart, srcStart + copyW)
+
     dstData.set(chunk, dstStart)
   }
 

package/src/PixelData/fillPixelData.ts

@@ -1,10 +1,7 @@
 import type { Color32 } from '../_types'
 import type { Rect } from '../Rect/_rect-types'
-import { makeClippedRect, resolveRectClipping } from '../Rect/resolveClipping'
 import type { PixelData32 } from './_pixelData-types'
 
-const SCRATCH_RECT = makeClippedRect()
-
 /**
  * Fills a region or the {@link PixelData32} buffer with a solid color.
  *
@@ -42,6 +39,9 @@ export function fillPixelData(
   _w?: number,
   _h?: number,
 ): boolean {
+  const dstW = dst.w
+  const dstH = dst.h
+
   let x: number
   let y: number
   let w: number
@@ -50,8 +50,8 @@ export function fillPixelData(
   if (typeof _x === 'object') {
     x = _x.x ?? 0
     y = _x.y ?? 0
-    w = _x.w ?? dst.w
-    h = _x.h ?? dst.h
+    w = _x.w ?? dstW
+    h = _x.h ?? dstH
   } else if (typeof _x === 'number') {
     x = _x
     y = _y!
@@ -60,37 +60,55 @@ export function fillPixelData(
   } else {
     x = 0
     y = 0
-    w = dst.w
-    h = dst.h
+    w = dstW
+    h = dstH
+  }
+
+  // Inline bounds clipping
+  let dstX = x
+  let dstY = y
+  let fillW = w
+  let fillH = h
+
+  if (dstX < 0) {
+    fillW += dstX
+    dstX = 0
   }
 
-  const clip = resolveRectClipping(
-    x,
-    y,
-    w,
-    h,
-    dst.w,
-    dst.h,
-    SCRATCH_RECT,
-  )
+  if (dstY < 0) {
+    fillH += dstY
+    dstY = 0
+  }
 
-  if (!clip.inBounds) return false
+  fillW = Math.min(fillW, dstW - dstX)
+  fillH = Math.min(fillH, dstH - dstY)
 
-  const {
-    x: finalX,
-    y: finalY,
-    w: actualW,
-    h: actualH,
-  } = clip
+  if (fillW <= 0) return false
+  if (fillH <= 0) return false
 
   const dst32 = dst.data
-  const dw = dst.w
   let hasChanged = false
 
-  for (let iy = 0; iy < actualH; iy++) {
-    const rowOffset = (finalY + iy) * dw
-    const start = rowOffset + finalX
-    const end = start + actualW
+  // Fast-path: If the area spans the full width, we can treat it as a contiguous 1D array
+  if (dstX === 0 && fillW === dstW) {
+    const start = dstY * dstW
+    const end = start + fillW * fillH
+
+    for (let i = start; i < end; i++) {
+      if (dst32[i] !== color) {
+        dst32[i] = color
+        hasChanged = true
+      }
+    }
+
+    return hasChanged
+  }
+
+  // Standard path: row-by-row
+  for (let iy = 0; iy < fillH; iy++) {
+    const rowOffset = (dstY + iy) * dstW
+    const start = rowOffset + dstX
+    const end = start + fillW
 
     for (let i = start; i < end; i++) {
       if (dst32[i] !== color) {