pixel-data-js 0.16.0 → 0.17.0

package/src/History/HistoryManager.ts

@@ -0,0 +1,83 @@
+export interface HistoryAction {
+  undo: () => void
+  redo: () => void
+  dispose?: () => void
+}
+
+export class HistoryManager {
+  public undoStack: HistoryAction[]
+  public redoStack: HistoryAction[]
+  public listeners: Set<() => void>
+
+  constructor(
+    public maxSteps = 50,
+  ) {
+    this.undoStack = []
+    this.redoStack = []
+    this.listeners = new Set()
+  }
+
+  get canUndo() {
+    return this.undoStack.length > 0
+  }
+
+  get canRedo() {
+    return this.redoStack.length > 0
+  }
+
+  subscribe(fn: () => void) {
+    this.listeners.add(fn)
+    return () => this.listeners.delete(fn)
+  }
+
+  notify() {
+    this.listeners.forEach((fn) => fn())
+  }
+
+  commit(action: HistoryAction) {
+    this.undoStack.push(action)
+    this.clearRedoStack()
+
+    if (this.undoStack.length > this.maxSteps) {
+      this.undoStack.shift()?.dispose?.()
+    }
+
+    this.notify()
+  }
+
+  undo() {
+    let action = this.undoStack.pop()
+
+    if (!action) return
+
+    this.redoStack.push(action)
+    action.undo()
+
+    this.notify()
+  }
+
+  redo() {
+    let action = this.redoStack.pop()
+
+    if (!action) return
+
+    this.undoStack.push(action)
+    action.redo()
+
+    this.notify()
+  }
+
+  clearRedoStack() {
+    let length = this.redoStack.length
+
+    for (let i = 0; i < length; i++) {
+      let action = this.redoStack[i]
+
+      if (action) {
+        action.dispose?.()
+      }
+    }
+
+    this.redoStack.length = 0
+  }
+}

package/src/History/PixelAccumulator.ts

@@ -0,0 +1,191 @@
+import type { PixelData } from '../PixelData/PixelData'
+import type { PixelEngineConfig } from './PixelEngineConfig'
+import { type PixelPatchTiles, PixelTile } from './PixelPatchTiles'
+
+export class PixelAccumulator {
+  public lookup: (PixelTile | undefined)[]
+  public beforeTiles: PixelTile[]
+  public pool: PixelTile[]
+
+  constructor(
+    public target: PixelData,
+    readonly config: PixelEngineConfig,
+  ) {
+    this.lookup = []
+    this.beforeTiles = []
+    this.pool = []
+  }
+
+  getTile(
+    id: number,
+    tx: number,
+    ty: number,
+  ): PixelTile {
+    let tile = this.pool.pop()
+
+    if (tile) {
+      tile.id = id
+      tile.tx = tx
+      tile.ty = ty
+
+      return tile
+    }
+
+    return new PixelTile(
+      id,
+      tx,
+      ty,
+      this.config.tileArea,
+    )
+  }
+
+  recyclePatch(patch: PixelPatchTiles) {
+    const before = patch.beforeTiles
+
+    for (let i = 0; i < before.length; i++) {
+      let tile = before[i]
+
+      if (tile) {
+        this.pool.push(tile)
+      }
+    }
+
+    const after = patch.afterTiles
+
+    for (let i = 0; i < after.length; i++) {
+      let tile = after[i]
+
+      if (tile) {
+        this.pool.push(tile)
+      }
+    }
+  }
+
+  /**
+   * @param x pixel x coordinate
+   * @param y pixel y coordinate
+   */
+  storeTileBeforeState(x: number, y: number): void {
+    let target = this.target
+    let shift = this.config.tileShift
+    let columns = (target.width + this.config.tileMask) >> shift
+    let tx = x >> shift
+    let ty = y >> shift
+    let id = ty * columns + tx
+
+    let tile = this.lookup[id]
+
+    if (!tile) {
+      tile = this.getTile(
+        id,
+        tx,
+        ty,
+      )
+
+      this.extractState(tile)
+      this.lookup[id] = tile
+      this.beforeTiles.push(tile)
+    }
+  }
+
+  /**
+   *
+   * @param x pixel x coordinate
+   * @param y pixel y coordinate
+   * @param w pixel width
+   * @param h pixel height
+   */
+  storeRegionBeforeState(
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+  ) {
+    let target = this.target
+    let shift = this.config.tileShift
+    let columns = (target.width + this.config.tileMask) >> shift
+
+    let startX = x >> shift
+    let startY = y >> shift
+    let endX = (x + w - 1) >> shift
+    let endY = (y + h - 1) >> shift
+
+    for (let ty = startY; ty <= endY; ty++) {
+      for (let tx = startX; tx <= endX; tx++) {
+        let id = ty * columns + tx
+        let tile = this.lookup[id]
+
+        if (!tile) {
+          tile = this.getTile(
+            id,
+            tx,
+            ty,
+          )
+
+          this.extractState(tile)
+          this.lookup[id] = tile
+          this.beforeTiles.push(tile)
+        }
+      }
+    }
+  }
+
+  extractState(tile: PixelTile) {
+    let target = this.target
+    let TILE_SIZE = this.config.tileSize
+    let dst = tile.data32
+    let src = target.data32
+    let startX = tile.tx * TILE_SIZE
+    let startY = tile.ty * TILE_SIZE
+    let targetWidth = target.width
+    let targetHeight = target.height
+
+    let copyWidth = Math.max(0, Math.min(TILE_SIZE, targetWidth - startX))
+
+    for (let ly = 0; ly < TILE_SIZE; ly++) {
+      let globalY = startY + ly
+      let dstIndex = ly * TILE_SIZE
+
+      if (globalY < 0 || globalY >= targetHeight || copyWidth === 0) {
+        dst.fill(0, dstIndex, dstIndex + TILE_SIZE)
+        continue
+      }
+
+      let srcIndex = globalY * targetWidth + startX
+      let rowData = src.subarray(srcIndex, srcIndex + copyWidth)
+
+      dst.set(rowData, dstIndex)
+
+      if (copyWidth < TILE_SIZE) {
+        dst.fill(0, dstIndex + copyWidth, dstIndex + TILE_SIZE)
+      }
+    }
+  }
+
+  extractAfterTiles(): PixelTile[] {
+    let afterTiles: PixelTile[] = []
+    let length = this.beforeTiles.length
+
+    for (let i = 0; i < length; i++) {
+      let beforeTile = this.beforeTiles[i]
+
+      if (beforeTile) {
+        let afterTile = this.getTile(
+          beforeTile.id,
+          beforeTile.tx,
+          beforeTile.ty,
+        )
+
+        this.extractState(afterTile)
+        afterTiles.push(afterTile)
+      }
+    }
+
+    return afterTiles
+  }
+
+  reset() {
+    this.lookup = []
+    this.beforeTiles = []
+  }
+}

package/src/History/PixelEngineConfig.ts

@@ -0,0 +1,18 @@
+export class PixelEngineConfig {
+  public readonly tileSize: number
+  public readonly tileShift: number
+  public readonly tileMask: number
+  public readonly tileArea: number
+
+  constructor(tileSize: number = 256) {
+    // Ensure it's a power of 2 to guarantee bitwise math works
+    if ((tileSize & (tileSize - 1)) !== 0) {
+      throw new Error('tileSize must be a power of 2')
+    }
+
+    this.tileSize = tileSize
+    this.tileShift = Math.log2(tileSize)
+    this.tileMask = tileSize - 1
+    this.tileArea = tileSize * tileSize
+  }
+}

package/src/History/PixelMutator/mutatorApplyMask.ts

@@ -0,0 +1,20 @@
+import { type AnyMask, type ApplyMaskOptions } from '../../_types'
+import { applyMaskToPixelData } from '../../PixelData/applyMaskToPixelData'
+import { PixelWriter } from '../PixelWriter'
+
+export function mutatorApplyMask(writer: PixelWriter<any>) {
+  return {
+    applyMask: (mask: AnyMask, opts: ApplyMaskOptions = {}) => {
+      let target = writer.target
+      const {
+        x = 0,
+        y = 0,
+        w = writer.target.width,
+        h = writer.target.height,
+      } = opts
+
+      writer.accumulator.storeRegionBeforeState(x, y, w, h)
+      applyMaskToPixelData(target, mask, opts)
+    },
+  }
+}

package/src/History/PixelMutator/mutatorBlendColor.ts

@@ -0,0 +1,22 @@
+import type { Color32, ColorBlendOptions } from '../../_types'
+import { blendColorPixelData } from '../../PixelData/blendColorPixelData'
+import { PixelWriter } from '../PixelWriter'
+
+export function mutatorBlendColor(writer: PixelWriter<any>) {
+  return {
+    blendColor(
+      color: Color32,
+      opts: ColorBlendOptions = {},
+    ) {
+
+      const {
+        x = 0,
+        y = 0,
+        w = writer.target.width,
+        h = writer.target.height,
+      } = opts
+      writer.accumulator.storeRegionBeforeState(x, y, w, h)
+      blendColorPixelData(writer.target, color, opts)
+    },
+  }
+}

package/src/History/PixelMutator/mutatorBlendPixel.ts

@@ -0,0 +1,37 @@
+import type { BlendColor32, Color32 } from '../../_types'
+import { overwriteFast } from '../../BlendModes/blend-modes-fast'
+import { PixelWriter } from '../PixelWriter'
+
+export function mutatorBlendPixel(writer: PixelWriter<any>) {
+  return {
+    blendPixel(
+      x: number,
+      y: number,
+      color: Color32,
+      alpha: number = 255,
+      blendFn: BlendColor32 = overwriteFast,
+    ) {
+      let target = writer.target
+      let width = target.width
+      let height = target.height
+
+      if (x < 0 || x >= width || y < 0 || y >= height) return
+
+      writer.accumulator.storeTileBeforeState(x, y)
+
+      let index = y * width + x
+      let bg = target.data32[index] as Color32
+
+      let finalColor = color
+
+      if (alpha < 255) {
+        let baseSrcAlpha = color >>> 24
+        let finalAlpha = (baseSrcAlpha * alpha + 128) >> 8
+
+        finalColor = (((color & 0x00ffffff) | (finalAlpha << 24)) >>> 0) as Color32
+      }
+
+      target.data32[index] = blendFn(finalColor, bg)
+    },
+  }
+}

package/src/History/PixelMutator/mutatorBlendPixelData.ts

@@ -0,0 +1,24 @@
+import type { PixelBlendOptions } from '../../_types'
+import { blendPixelData } from '../../PixelData/blendPixelData'
+import type { PixelData } from '../../PixelData/PixelData'
+import { PixelWriter } from '../PixelWriter'
+
+export function mutatorBlendPixelData(writer: PixelWriter<any>) {
+  return {
+    blendPixelData(
+      src: PixelData,
+      opts: PixelBlendOptions,
+    ) {
+      const {
+        x = 0,
+        y = 0,
+        w = src.width,
+        h = src.height,
+      } = opts
+      writer.accumulator.storeRegionBeforeState(x, y, w, h)
+
+      blendPixelData(writer.target, src, opts)
+    },
+  }
+}
+

package/src/History/PixelMutator/mutatorFillPixelData.ts

@@ -0,0 +1,21 @@
+import type { Color32, Rect } from '../../_types'
+import { fillPixelData } from '../../PixelData/fillPixelData'
+import { PixelWriter } from '../PixelWriter'
+
+export function mutatorFill(writer: PixelWriter<any>) {
+  return {
+    fill(
+      color: Color32,
+      rect: Partial<Rect> = {},
+    ) {
+      const {
+        x = 0,
+        y = 0,
+        w = writer.target.width,
+        h = writer.target.height,
+      } = rect
+      writer.accumulator.storeRegionBeforeState(x, y, w, h)
+      fillPixelData(writer.target, color, x, y, w, h)
+    },
+  }
+}

package/src/History/PixelMutator/mutatorInvert.ts

@@ -0,0 +1,18 @@
+import type { PixelMutateOptions } from '../../_types'
+import { invertPixelData } from '../../PixelData/invertPixelData'
+import { PixelWriter } from '../PixelWriter'
+
+export function mutatorInvert(writer: PixelWriter<any>) {
+  return {
+    invert(opts: PixelMutateOptions = {}) {
+      const {
+        x = 0,
+        y = 0,
+        w = writer.target.width,
+        h = writer.target.height,
+      } = opts
+      writer.accumulator.storeRegionBeforeState(x, y, w, h)
+      invertPixelData(writer.target, opts)
+    },
+  }
+}

package/src/History/PixelMutator.ts

@@ -0,0 +1,18 @@
+import { mutatorApplyMask } from './PixelMutator/mutatorApplyMask'
+import { mutatorBlendColor } from './PixelMutator/mutatorBlendColor'
+import { mutatorBlendPixel } from './PixelMutator/mutatorBlendPixel'
+import { mutatorBlendPixelData } from './PixelMutator/mutatorBlendPixelData'
+import { mutatorFill } from './PixelMutator/mutatorFillPixelData'
+import { mutatorInvert } from './PixelMutator/mutatorInvert'
+import type { PixelWriter } from './PixelWriter'
+
+export function makeFullPixelMutator(writer: PixelWriter<any>) {
+  return {
+    ...mutatorApplyMask(writer),
+    ...mutatorBlendPixelData(writer),
+    ...mutatorBlendColor(writer),
+    ...mutatorBlendPixel(writer),
+    ...mutatorFill(writer),
+    ...mutatorInvert(writer),
+  }
+}

package/src/History/PixelPatchTiles.ts

@@ -0,0 +1,52 @@
+import type { PixelData } from '../PixelData/PixelData'
+
+export type PixelPatchTiles = {
+  beforeTiles: PixelTile[]
+  afterTiles: PixelTile[]
+}
+
+export class PixelTile {
+  public data32: Uint32Array
+
+  constructor(
+    public id: number,
+    public tx: number,
+    public ty: number,
+    tileArea: number,
+  ) {
+    this.data32 = new Uint32Array(tileArea)
+  }
+}
+
+export function applyPatchTiles(target: PixelData, tiles: PixelTile[], tileSize: number = 256) {
+  for (let i = 0; i < tiles.length; i++) {
+    const tile = tiles[i]
+
+    if (!tile) continue
+
+    const dst = target.data32
+    const src = tile.data32
+    const dstWidth = target.width
+    const dstHeight = target.height
+    const startX = tile.tx * tileSize
+    const startY = tile.ty * tileSize
+
+    // Calculate clamping to prevent wrapping artifacts on image edges
+    const copyWidth = Math.max(0, Math.min(tileSize, dstWidth - startX))
+
+    if (copyWidth <= 0) return
+
+    for (let ly = 0; ly < tileSize; ly++) {
+      const globalY = startY + ly
+
+      // Stop if we go below the image
+      if (globalY >= dstHeight) break
+
+      const dstIndex = globalY * dstWidth + startX
+      const srcIndex = ly * tileSize
+      const rowData = src.subarray(srcIndex, srcIndex + copyWidth)
+
+      dst.set(rowData, dstIndex)
+    }
+  }
+}

package/src/History/PixelWriter.ts

@@ -0,0 +1,79 @@
+import type { PixelData } from '../PixelData/PixelData'
+import { type HistoryAction, HistoryManager } from './HistoryManager'
+import { PixelAccumulator } from './PixelAccumulator'
+import { PixelEngineConfig } from './PixelEngineConfig'
+import { applyPatchTiles, type PixelPatchTiles } from './PixelPatchTiles'
+
+export interface PixelWriterOptions {
+  maxHistorySteps?: number
+  tileSize?: number
+  historyManager?: HistoryManager
+}
+
+/**
+ * @example
+ * const targ = new PixelData(new ImageData(10, 10))
+ * const writer = new PixelWriter(targ, (writer) => {
+ *   return {
+ *     ...mutatorApplyMask(writer),
+ *     ...mutatorBlendPixelData(writer),
+ *     ...mutatorBlendColor(writer),
+ *     ...mutatorBlendPixel(writer),
+ *     ...mutatorFill(writer),
+ *   }
+ * })
+ *
+ * // to import all mutator functions
+ * const writer = new PixelWriter(targ, makeFullPixelMutator)
+ *
+ * writer.withHistory((mutator) => {
+ *   mutator.applyMask()
+ *   mutator.blendPixelData()
+ * })
+ */
+export class PixelWriter<M> {
+  public target: PixelData
+  public historyManager: HistoryManager
+  public accumulator: PixelAccumulator
+  protected config: PixelEngineConfig
+  private mutator: M
+
+  constructor(target: PixelData, mutatorFactory: (writer: PixelWriter<any>) => M, {
+    tileSize = 256,
+    maxHistorySteps = 50,
+    historyManager = new HistoryManager(maxHistorySteps),
+  }: PixelWriterOptions = {}) {
+    this.target = target
+    this.config = new PixelEngineConfig(tileSize)
+    this.historyManager = historyManager
+    this.accumulator = new PixelAccumulator(target, this.config)
+    this.mutator = mutatorFactory(this)
+  }
+
+  withHistory(cb: (mutator: M) => void) {
+    cb(this.mutator)
+
+    const beforeTiles = this.accumulator.beforeTiles
+    if (beforeTiles.length === 0) return
+
+    const afterTiles = this.accumulator.extractAfterTiles()
+
+    const patch: PixelPatchTiles = {
+      beforeTiles: beforeTiles,
+      afterTiles: afterTiles,
+    }
+
+    const target = this.target
+    const tileSize = this.config.tileSize
+    const accumulator = this.accumulator
+
+    const action: HistoryAction = {
+      undo: () => applyPatchTiles(target, patch.beforeTiles, tileSize),
+      redo: () => applyPatchTiles(target, patch.afterTiles, tileSize),
+      dispose: () => accumulator.recyclePatch(patch),
+    }
+
+    this.historyManager.commit(action)
+    this.accumulator.reset()
+  }
+}

package/src/ImageData/{writeImageDataPixels.ts → writeImageDataBuffer.ts}

@@ -11,7 +11,7 @@ import type { Rect } from '../_types'
  * @param data - The source pixel data (RGBA).
  * @param rect - A {@link Rect} object defining the destination region.
  */
-export function writeImageDataPixels(
+export function writeImageDataBuffer(
   imageData: ImageData,
   data: Uint8ClampedArray,
   rect: Rect,
@@ -24,7 +24,7 @@ export function writeImageDataPixels(
  * @param w - The width of the region to write.
  * @param h - The height of the region to write.
  */
-export function writeImageDataPixels(
+export function writeImageDataBuffer(
   imageData: ImageData,
   data: Uint8ClampedArray,
   x: number,
@@ -32,7 +32,7 @@ export function writeImageDataPixels(
   w: number,
   h: number,
 ): void
-export function writeImageDataPixels(
+export function writeImageDataBuffer(
   imageData: ImageData,
   data: Uint8ClampedArray,
   _x: Rect | number,

package/src/PixelData/applyCircleBrushToPixelData.ts

@@ -0,0 +1,69 @@
+import type { BlendColor32, Color32 } from '../_types'
+import { sourceOverPerfect } from '../BlendModes/blend-modes-perfect'
+import type { PixelData } from './PixelData'
+
+/**
+ * Applies a circular brush to pixel data, blending a color with optional falloff.
+ *
+ * @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 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
+ * @default sourceOverPerfect
+ */
+export function applyCircleBrushToPixelData(
+  target: PixelData,
+  color: Color32,
+  centerX: number,
+  centerY: number,
+  brushSize: number,
+  alpha = 255,
+  fallOff?: (dist: number) => number,
+  blendFn: BlendColor32 = sourceOverPerfect,
+): void {
+  const r = brushSize / 2
+  const rSqr = r * r
+  const centerOffset = (brushSize % 2 === 0) ? 0.5 : 0
+
+  const xStart = Math.max(0, Math.ceil(centerX - r))
+  const xEnd = Math.min(target.width - 1, Math.floor(centerX + r))
+  const yStart = Math.max(0, Math.ceil(centerY - r))
+  const yEnd = Math.min(target.height - 1, Math.floor(centerY + r))
+
+  const data32 = target.data32
+  const targetWidth = target.width
+  const baseColor = color & 0x00ffffff
+  const invR = 1 / r
+
+  // Pre-calculate the constant source for cases where fallOff is null
+  const constantSrc = ((alpha << 24) | baseColor) >>> 0 as Color32
+
+  for (let cy = yStart; cy <= yEnd; cy++) {
+    const dy = cy - centerY + centerOffset
+    const dySqr = dy * dy
+    const rowOffset = cy * targetWidth
+
+    for (let cx = xStart; cx <= xEnd; cx++) {
+      const dx = cx - centerX + centerOffset
+      const dSqr = dx * dx + dySqr
+
+      if (dSqr <= rSqr) {
+        const idx = rowOffset + cx
+
+        if (fallOff) {
+          const strength = fallOff(Math.sqrt(dSqr) * invR)
+          const fAlpha = (alpha * strength) & 0xFF
+          const src = ((fAlpha << 24) | baseColor) >>> 0 as Color32
+          data32[idx] = blendFn(src, data32[idx] as Color32)
+        } else {
+          data32[idx] = blendFn(constantSrc, data32[idx] as Color32)
+        }
+      }
+    }
+  }
+}

package/src/PixelData/applyMaskToPixelData.ts

@@ -8,7 +8,7 @@ import type { PixelData } from './PixelData'
 export function applyMaskToPixelData(
   dst: PixelData,
   mask: AnyMask,
-  opts: ApplyMaskOptions,
+  opts: ApplyMaskOptions = {},
 ): void {
   const {
     x: targetX = 0,