pixel-data-js 0.23.1 → 0.25.0

package/src/PixelData/extractPixelDataBuffer.ts

@@ -1,4 +1,4 @@
-import type { IPixelData, Rect } from '../_types'
+import type { IPixelData32, Rect } from '../_types'
 import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
 
 const SCRATCH_BLIT = makeClippedBlit()
@@ -7,10 +7,10 @@ const SCRATCH_BLIT = makeClippedBlit()
  * Extracts a rectangular region of pixels from PixelData.
  * Returns a new Uint32Array containing the extracted pixels.
  */
-export function extractPixelDataBuffer(source: IPixelData, rect: Rect): Uint32Array
-export function extractPixelDataBuffer(source: IPixelData, x: number, y: number, w: number, h: number): Uint32Array
+export function extractPixelDataBuffer(source: IPixelData32, rect: Rect): Uint32Array
+export function extractPixelDataBuffer(source: IPixelData32, x: number, y: number, w: number, h: number): Uint32Array
 export function extractPixelDataBuffer(
-  source: IPixelData,
+  source: IPixelData32,
   _x: Rect | number,
   _y?: number,
   _w?: number,

package/src/PixelData/fillPixelData.ts

@@ -1,21 +1,21 @@
-import type { Color32, IPixelData, Rect } from '../_types'
+import type { Color32, IPixelData32, Rect } from '../_types'
 import { makeClippedRect, resolveRectClipping } from '../Internal/resolveClipping'
 
 const SCRATCH_RECT = makeClippedRect()
 
 /**
- * Fills a region or the {@link IPixelData} buffer with a solid color.
+ * Fills a region or the {@link IPixelData32} buffer with a solid color.
  *
  * @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.
+ * @returns true if any pixels were actually modified.
  */
 export function fillPixelData(
-  dst: IPixelData,
+  dst: IPixelData32,
   color: Color32,
   rect?: Partial<Rect>,
-): void
+): boolean
 /**
  * @param dst - The target to modify.
  * @param color - The color to apply.
@@ -25,21 +25,21 @@ export function fillPixelData(
  * @param h - Height of the fill area.
  */
 export function fillPixelData(
-  dst: IPixelData,
+  dst: IPixelData32,
   color: Color32,
   x: number,
   y: number,
   w: number,
   h: number,
-): void
+): boolean
 export function fillPixelData(
-  dst: IPixelData,
+  dst: IPixelData32,
   color: Color32,
   _x?: Partial<Rect> | number,
   _y?: number,
   _w?: number,
   _h?: number,
-): void {
+): boolean {
   let x: number
   let y: number
   let w: number
@@ -62,11 +62,18 @@ export function fillPixelData(
     h = dst.height
   }
 
-  const clip = resolveRectClipping(x, y, w, h, dst.width, dst.height, SCRATCH_RECT)
+  const clip = resolveRectClipping(
+    x,
+    y,
+    w,
+    h,
+    dst.width,
+    dst.height,
+    SCRATCH_RECT,
+  )
 
-  if (!clip.inBounds) return
+  if (!clip.inBounds) return false
 
-  // Use the clipped values
   const {
     x: finalX,
     y: finalY,
@@ -76,17 +83,20 @@ export function fillPixelData(
 
   const dst32 = dst.data32
   const dw = dst.width
+  let hasChanged = false
 
-  // Optimization: If filling the entire buffer, use the native .fill()
-  if (actualW === dw && actualH === dst.height && finalX === 0 && finalY === 0) {
-    dst32.fill(color)
-    return
-  }
-
-  // Row-by-row fill for partial rectangles
   for (let iy = 0; iy < actualH; iy++) {
-    const start = (finalY + iy) * dw + finalX
+    const rowOffset = (finalY + iy) * dw
+    const start = rowOffset + finalX
     const end = start + actualW
-    dst32.fill(color, start, end)
+
+    for (let i = start; i < end; i++) {
+      if (dst32[i] !== color) {
+        dst32[i] = color
+        hasChanged = true
+      }
+    }
   }
+
+  return hasChanged
 }

package/src/PixelData/fillPixelDataBinaryMask.ts

@@ -1,10 +1,10 @@
-import type { BinaryMask, Color32, IPixelData } from '../_types'
+import type { BinaryMask, Color32, IPixelData32 } 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.
+ * Fills a region of the {@link IPixelData32} 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.
@@ -13,14 +13,14 @@ const SCRATCH_RECT = makeClippedRect()
  * @param y - Starting vertical coordinate for the mask placement.
  */
 export function fillPixelDataBinaryMask(
-  dst: IPixelData,
+  dst: IPixelData32,
   color: Color32,
   mask: BinaryMask,
   alpha = 255,
   x = 0,
   y = 0,
-): void {
-  if (alpha === 0) return
+): boolean {
+  if (alpha === 0) return false
 
   const maskW = mask.w
   const maskH = mask.h
@@ -35,7 +35,7 @@ export function fillPixelDataBinaryMask(
     SCRATCH_RECT,
   )
 
-  if (!clip.inBounds) return
+  if (!clip.inBounds) return false
 
   const {
     x: finalX,
@@ -59,6 +59,8 @@ export function fillPixelDataBinaryMask(
     finalCol = ((colorRGB | (a << 24)) >>> 0) as Color32
   }
 
+  let hasChanged = false
+
   for (let iy = 0; iy < actualH; iy++) {
     const currentY = finalY + iy
     const maskY = currentY - y
@@ -72,8 +74,14 @@ export function fillPixelDataBinaryMask(
       const maskIndex = maskOffset + maskX
 
       if (maskData[maskIndex]) {
-        dst32[dstRowOffset + currentX] = finalCol
+        const current = dst32[dstRowOffset + currentX]
+        if (current !== finalCol) {
+          dst32[dstRowOffset + currentX] = finalCol
+          hasChanged = true
+        }
       }
     }
   }
+
+  return hasChanged
 }

package/src/PixelData/fillPixelDataFast.ts

@@ -0,0 +1,94 @@
+import type { Color32, IPixelData32, Rect } from '../_types'
+import { makeClippedRect, resolveRectClipping } from '../Internal/resolveClipping'
+
+const SCRATCH_RECT = makeClippedRect()
+
+/**
+ * Fills a region or the {@link IPixelData32} buffer with a solid color.
+ * 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 color - The color to apply.
+ * @param rect - Defines the area to fill. If omitted, the entire
+ * buffer is filled.
+ */
+export function fillPixelDataFast(
+  dst: IPixelData32,
+  color: Color32,
+  rect?: Partial<Rect>,
+): void
+/**
+ * @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.
+ */
+export function fillPixelDataFast(
+  dst: IPixelData32,
+  color: Color32,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): void
+export function fillPixelDataFast(
+  dst: IPixelData32,
+  color: Color32,
+  _x?: Partial<Rect> | number,
+  _y?: number,
+  _w?: number,
+  _h?: number,
+): void {
+  let x: number
+  let y: number
+  let w: number
+  let h: number
+
+  if (typeof _x === 'object') {
+    x = _x.x ?? 0
+    y = _x.y ?? 0
+    w = _x.w ?? dst.width
+    h = _x.h ?? dst.height
+  } else if (typeof _x === 'number') {
+    x = _x
+    y = _y!
+    w = _w!
+    h = _h!
+  } else {
+    x = 0
+    y = 0
+    w = dst.width
+    h = dst.height
+  }
+
+  const clip = resolveRectClipping(x, y, w, h, dst.width, dst.height, SCRATCH_RECT)
+
+  if (!clip.inBounds) return
+
+  // Use the clipped values
+  const {
+    x: finalX,
+    y: finalY,
+    w: actualW,
+    h: actualH,
+  } = clip
+
+  const dst32 = dst.data32
+  const dw = dst.width
+
+  // Optimization: If filling the entire buffer, use the native .fill()
+  if (actualW === dw && actualH === dst.height && finalX === 0 && finalY === 0) {
+    dst32.fill(color)
+    return
+  }
+
+  // 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/invertPixelData.ts

@@ -1,12 +1,12 @@
-import { type IPixelData, type PixelMutateOptions } from '../_types'
+import { type IPixelData32, type PixelMutateOptions } from '../_types'
 import { makeClippedRect, resolveRectClipping } from '../Internal/resolveClipping'
 
 const SCRATCH_RECT = makeClippedRect()
 
 export function invertPixelData(
-  pixelData: IPixelData,
+  pixelData: IPixelData32,
   opts: PixelMutateOptions = {},
-): void {
+): boolean {
   const dst = pixelData
   const {
     x: targetX = 0,
@@ -21,7 +21,7 @@ export function invertPixelData(
 
   const clip = resolveRectClipping(targetX, targetY, width, height, dst.width, dst.height, SCRATCH_RECT)
 
-  if (!clip.inBounds) return
+  if (!clip.inBounds) return false
 
   const {
     x,
@@ -72,4 +72,6 @@ export function invertPixelData(
       dIdx += dStride
     }
   }
+
+  return true
 }

package/src/PixelData/pixelDataToAlphaMask.ts

@@ -1,4 +1,4 @@
-import type { AlphaMask, IPixelData } from '../_types'
+import type { AlphaMask, IPixelData32 } from '../_types'
 import { makeAlphaMask } from '../Mask/AlphaMask'
 
 /**
@@ -6,7 +6,7 @@ import { makeAlphaMask } from '../Mask/AlphaMask'
  * Returns a Uint8Array branded as AlphaMask.
  */
 export function pixelDataToAlphaMask(
-  pixelData: IPixelData,
+  pixelData: IPixelData32,
 ): AlphaMask {
   const {
     data32,

package/src/PixelData/reflectPixelData.ts

@@ -1,6 +1,6 @@
-import type { IPixelData } from '../_types'
+import type { IPixelData32 } from '../_types'
 
-export function reflectPixelDataHorizontal(pixelData: IPixelData): void {
+export function reflectPixelDataHorizontal(pixelData: IPixelData32): void {
   const width = pixelData.width
   const height = pixelData.height
   const data = pixelData.data32
@@ -20,7 +20,7 @@ export function reflectPixelDataHorizontal(pixelData: IPixelData): void {
   }
 }
 
-export function reflectPixelDataVertical(pixelData: IPixelData): void {
+export function reflectPixelDataVertical(pixelData: IPixelData32): void {
   const width = pixelData.width
   const height = pixelData.height
   const data = pixelData.data32

package/src/PixelData/resamplePixelData.ts

@@ -1,4 +1,4 @@
-import { type IPixelData, PixelData } from '../index'
+import { type IPixelData32, PixelData } from '../index'
 import { resample32 } from '../Internal/resample32'
 
 /**
@@ -6,7 +6,7 @@ import { resample32 } from '../Internal/resample32'
  * Factor > 1 upscales, Factor < 1 downscales.
  */
 export function resamplePixelData(
-  pixelData: IPixelData,
+  pixelData: IPixelData32,
   factor: number,
 ): PixelData {
   const { data, width, height } = resample32(pixelData.data32, pixelData.width, pixelData.height, factor)

package/src/PixelData/writePaintBufferToPixelData.ts

@@ -0,0 +1,26 @@
+import type { IPixelData } from '../_types'
+import type { PaintBuffer } from '../Paint/PaintBuffer'
+import { writePixelDataBuffer } from './writePixelDataBuffer'
+
+/**
+ * @param writePixelDataBufferFn - @hidden
+ */
+export function writePaintBufferToPixelData(
+  target: IPixelData,
+  paintBuffer: PaintBuffer,
+  writePixelDataBufferFn = writePixelDataBuffer,
+) {
+  const tileShift = paintBuffer.config.tileShift
+  const lookup = paintBuffer.lookup
+
+  for (let i = 0; i < lookup.length; i++) {
+    const tile = lookup[i]
+
+    if (tile) {
+      const dx = tile.tx << tileShift
+      const dy = tile.ty << tileShift
+
+      writePixelDataBufferFn(target, tile.data32, dx, dy, tile.width, tile.height)
+    }
+  }
+}

package/src/PixelData/writePixelDataBuffer.ts

@@ -1,21 +1,21 @@
-import { type IPixelData, type Rect } from '../_types'
+import { type IPixelData32, type Rect } from '../_types'
 import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
 
 const SCRATCH_BLIT = makeClippedBlit()
 
 /**
- * Copies a pixel buffer into a specific region of a {@link IPixelData} object.
+ * Copies a pixel buffer into a specific region of a {@link IPixelData32} object.
  *
  * This function performs a direct memory copy from a {@link Uint32Array}
  * into the target buffer.
  */
 export function writePixelDataBuffer(
-  target: IPixelData,
+  target: IPixelData32,
   data: Uint32Array,
   rect: Rect,
 ): void
 export function writePixelDataBuffer(
-  target: IPixelData,
+  target: IPixelData32,
   data: Uint32Array,
   x: number,
   y: number,
@@ -23,7 +23,7 @@ export function writePixelDataBuffer(
   h: number,
 ): void
 export function writePixelDataBuffer(
-  target: IPixelData,
+  target: IPixelData32,
   data: Uint32Array,
   _x: Rect | number,
   _y?: number,

package/src/PixelTile/PixelTile.ts

@@ -0,0 +1,21 @@
+import type { IPixelData } from '../_types'
+
+export class PixelTile implements IPixelData {
+  readonly data32: Uint32Array
+  readonly width: number
+  readonly height: number
+  readonly imageData: ImageData
+
+  constructor(
+    public id: number,
+    public tx: number,
+    public ty: number,
+    tileSize: number,
+    tileArea: number,
+  ) {
+    this.width = this.height = tileSize
+    this.data32 = new Uint32Array(tileArea)
+    const data8 = new Uint8ClampedArray(this.data32.buffer) as Uint8ClampedArray<ArrayBuffer>
+    this.imageData = new ImageData(data8, tileSize, tileSize)
+  }
+}

package/src/PixelTile/PixelTilePool.ts

@@ -0,0 +1,63 @@
+import type { PixelEngineConfig } from '../History/PixelEngineConfig'
+
+import { PixelTile } from './PixelTile'
+
+export class PixelTilePool {
+  public pool: PixelTile[]
+
+  private tileSize: number
+  private tileArea: number
+
+  constructor(
+    config: PixelEngineConfig,
+  ) {
+    this.pool = []
+    this.tileSize = config.tileSize
+    this.tileArea = config.tileArea
+  }
+
+  getTile(
+    id: number,
+    tx: number,
+    ty: number,
+  ): PixelTile {
+    let tile = this.pool.pop()
+
+    if (tile) {
+      tile.id = id
+      tile.tx = tx
+      tile.ty = ty
+
+      // Wipe dirty memory from previous uses before handing it out
+      tile.data32.fill(0)
+
+      return tile
+    }
+
+    return new PixelTile(
+      id,
+      tx,
+      ty,
+      this.tileSize,
+      this.tileArea,
+    )
+  }
+
+  releaseTile(tile: PixelTile): void {
+    this.pool.push(tile)
+  }
+
+  releaseTiles(tiles: (PixelTile | undefined)[]): void {
+    let length = tiles.length
+
+    for (let i = 0; i < length; i++) {
+      let tile = tiles[i]
+
+      if (tile) {
+        this.pool.push(tile)
+      }
+    }
+
+    tiles.length = 0
+  }
+}

package/src/Rect/trimMaskRectBounds.ts

@@ -0,0 +1,121 @@
+import type { NullableMaskRect, Rect } from '../_types'
+import { extractMaskBuffer } from '../Mask/extractMaskBuffer'
+
+/**
+ * Intersects a target rectangle with a boundary, trimming dimensions and masks in-place.
+ * This utility calculates the axis-aligned intersection between the `target` and `bounds`.
+ * If the `target` includes a `mask` (as in a {@link NullableMaskRect}), the mask is physically
+ * cropped and re-aligned using `extractMaskBuffer` to match the new dimensions.
+ * @param target - The rectangle or selection object to be trimmed. **Note:** This object is mutated in-place.
+ * @param bounds - The boundary rectangle defining the maximum allowable area (e.g., canvas dimensions).
+ * @example
+ * const selection = { x: -10, y: -10, w: 50, h: 50, mask: new Uint8Array(2500) };
+ * const canvas = { x: 0, y: 0, w: 100, h: 100 };
+ * // Selection will be moved to (0,0) and resized to 40x40.
+ * // The mask is cropped by 10 px on the top and left.
+ * trimRectBounds(selection, canvas);
+ */
+export function trimMaskRectBounds<T extends NullableMaskRect>(
+  target: T,
+  bounds: Rect,
+): void {
+  const originalX = target.x
+  const originalY = target.y
+  const originalW = target.w
+
+  const intersectedX = Math.max(target.x, bounds.x)
+  const intersectedY = Math.max(target.y, bounds.y)
+
+  const intersectedMaxX = Math.min(
+    target.x + target.w,
+    bounds.x + bounds.w,
+  )
+  const intersectedMaxY = Math.min(
+    target.y + target.h,
+    bounds.y + bounds.h,
+  )
+
+  // Intersection check
+  if (intersectedMaxX <= intersectedX || intersectedMaxY <= intersectedY) {
+    target.w = 0
+    target.h = 0
+
+    if ('data' in target && target.data) {
+      target.data = new Uint8Array(0)
+    }
+
+    return
+  }
+
+  const intersectedW = intersectedMaxX - intersectedX
+  const intersectedH = intersectedMaxY - intersectedY
+  const offsetX = intersectedX - originalX
+  const offsetY = intersectedY - originalY
+
+  target.x = intersectedX
+  target.y = intersectedY
+  target.w = intersectedW
+  target.h = intersectedH
+
+  if ('data' in target && target.data) {
+    const currentMaskBuffer = extractMaskBuffer(
+      target.data,
+      originalW,
+      offsetX,
+      offsetY,
+      intersectedW,
+      intersectedH,
+    )
+
+    let minX = intersectedW
+    let maxX = -1
+    let minY = intersectedH
+    let maxY = -1
+
+    // Scan for content
+    for (let y = 0; y < intersectedH; y++) {
+      for (let x = 0; x < intersectedW; x++) {
+        if (currentMaskBuffer[y * intersectedW + x] !== 0) {
+          if (x < minX) minX = x
+          if (x > maxX) maxX = x
+          if (y < minY) minY = y
+          if (y > maxY) maxY = y
+        }
+      }
+    }
+
+    // If no content is found (all zeros)
+    if (maxX === -1) {
+      target.w = 0
+      target.h = 0
+      target.data = new Uint8Array(0)
+
+      return
+    }
+
+    const finalW = maxX - minX + 1
+    const finalH = maxY - minY + 1
+
+    // Only shift and crop if the content is smaller than the intersection
+    if (finalW !== intersectedW || finalH !== intersectedH) {
+      const newMaskBuffer = extractMaskBuffer(
+        currentMaskBuffer,
+        intersectedW,
+        minX,
+        minY,
+        finalW,
+        finalH,
+      )
+
+      target.x += minX
+      target.y += minY
+      target.w = finalW
+      target.h = finalH
+      target.data = newMaskBuffer
+    } else {
+      target.w = finalW
+      target.h = finalH
+      target.data = currentMaskBuffer
+    }
+  }
+}