pixel-data-js 0.2.0 → 0.3.0

package/src/PixelData/blendColorPixelData.ts

@@ -0,0 +1,157 @@
+import { type Color32, type ColorBlendOptions, MaskType } from '../_types'
+import { sourceOverColor32 } from '../blend-modes'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Fills a rectangle in the destination PixelData with a single color,
+ * supporting blend modes, global alpha, and masking.
+ */
+export function blendColorPixelData(
+  dst: PixelData,
+  color: Color32,
+  opts: ColorBlendOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha: globalAlpha = 255,
+    blendFn = sourceOverColor32,
+    mask,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (globalAlpha === 0) return
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // 1. Destination Clipping
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) return
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const mPitch = mw ?? width
+  const isAlphaMask = maskType === MaskType.ALPHA
+
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const mStride = mPitch - actualW
+
+  // Pre-calculate the source color with global alpha
+  const baseSrcColor = color
+  const baseSrcAlpha = (baseSrcColor >>> 24)
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+
+      // Early exit if source pixel is already transparent
+      if (baseSrcAlpha === 0) {
+        dIdx++
+        mIdx++
+        continue
+      }
+
+      let weight = globalAlpha
+
+      if (mask) {
+        const mVal = mask[mIdx]
+
+        if (isAlphaMask) {
+        const effectiveM = invertMask
+          ? 255 - mVal
+          : mVal
+
+        // If mask is transparent, skip
+        if (effectiveM === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+
+          // globalAlpha is not a factor
+          if (globalAlpha === 255) {
+            weight = effectiveM
+            // mask is not a factor
+          } else if (effectiveM === 255) {
+            weight = globalAlpha
+          } else {
+            // use rounding-corrected multiplication
+            weight = (effectiveM * globalAlpha + 128) >> 8
+          }
+        } else {
+          const isHit = invertMask
+            ? mVal === 0
+            : mVal === 1
+
+          if (!isHit) {
+            dIdx++
+            mIdx++
+            continue
+          }
+
+          weight = globalAlpha
+        }
+
+        // Final safety check for weight (can be 0 if globalAlpha or alphaMask rounds down)
+        if (weight === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+      }
+
+      // Apply Weight to Source Alpha
+      let currentSrcAlpha = baseSrcAlpha
+      let currentSrcColor = baseSrcColor
+
+      if (weight < 255) {
+        if (baseSrcAlpha === 255) {
+          currentSrcAlpha = weight
+        } else {
+          currentSrcAlpha = (baseSrcAlpha * weight + 128) >> 8
+        }
+
+        if (currentSrcAlpha === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        currentSrcColor = ((baseSrcColor & 0x00ffffff) | (currentSrcAlpha << 24)) >>> 0 as Color32
+      }
+
+      dst32[dIdx] = blendFn(currentSrcColor, dst32[dIdx] as Color32)
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/blendPixelData.ts

@@ -0,0 +1,196 @@
+import { type Color32, MaskType, type PixelBlendOptions } from '../_types'
+import { sourceOverColor32 } from '../blend-modes'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Blits source PixelData into a destination PixelData using 32-bit integer bitwise blending.
+ * This function bypasses standard ImageData limitations by operating directly on
+ * Uint32Array views. It supports various blend modes, binary/alpha masking, and
+ * automatic clipping of both source and destination bounds.
+ * @example
+ *
+ * const dst = new PixelData(ctx.getImageData(0,0,100,100))
+ * blendImageData32(dst, sprite, {
+ *   blendFn: COLOR_32_BLEND_MODES.multiply,
+ *   mask: brushMask,
+ *   maskType: MaskType.ALPHA
+ * });
+ */
+export function blendPixelData(
+  dst: PixelData,
+  src: PixelData,
+  opts: PixelBlendOptions,
+) {
+  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 = sourceOverColor32,
+    mask,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (globalAlpha === 0) return
+
+  let x = targetX
+  let y = targetY
+  let sx = sourceX
+  let sy = sourceY
+  let w = width
+  let h = height
+
+  // 1. Source Clipping
+  if (sx < 0) {
+    x -= sx
+    w += sx
+    sx = 0
+  }
+  if (sy < 0) {
+    y -= sy
+    h += sy
+    sy = 0
+  }
+  w = Math.min(w, src.width - sx)
+  h = Math.min(h, src.height - sy)
+
+  // 2. Destination Clipping
+  if (x < 0) {
+    sx -= x
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    sy -= y
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) return
+
+  const dst32 = dst.data32
+  const src32 = src.data32
+  const dw = dst.width
+  const sw = src.width
+  const mPitch = mw ?? width
+  const isAlphaMask = maskType === MaskType.ALPHA
+
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let sIdx = sy * sw + sx
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const sStride = sw - actualW
+  const mStride = mPitch - actualW
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+      const baseSrcColor = src32[sIdx] as Color32
+      const baseSrcAlpha = (baseSrcColor >>> 24)
+
+      // Early exit if source pixel is already transparent
+      if (baseSrcAlpha === 0) {
+        dIdx++
+        sIdx++
+        mIdx++
+        continue
+      }
+
+      let weight = globalAlpha
+
+      if (mask) {
+        const mVal = mask[mIdx]
+
+        if (isAlphaMask) {
+          const effectiveM = invertMask
+            ? 255 - mVal
+            : mVal
+
+          // If mask is transparent, skip
+          if (effectiveM === 0) {
+            dIdx++
+            sIdx++
+            mIdx++
+            continue
+          }
+
+          // globalAlpha is not a factor
+          if (globalAlpha === 255) {
+            weight = effectiveM
+            // mask is not a factor
+          } else if (effectiveM === 255) {
+            weight = globalAlpha
+          } else {
+            // use rounding-corrected multiplication
+            weight = (effectiveM * globalAlpha + 128) >> 8
+          }
+        } else {
+          const isHit = invertMask
+            ? mVal === 0
+            : mVal === 1
+
+          if (!isHit) {
+            dIdx++
+            sIdx++
+            mIdx++
+            continue
+          }
+
+          weight = globalAlpha
+        }
+
+        // Final safety check for weight (can be 0 if globalAlpha or alphaMask rounds down)
+        if (weight === 0) {
+          dIdx++
+          sIdx++
+          mIdx++
+          continue
+        }
+      }
+
+      // Apply Weight to Source Alpha
+      let currentSrcAlpha = baseSrcAlpha
+      let currentSrcColor = baseSrcColor
+
+      if (weight < 255) {
+        if (baseSrcAlpha === 255) {
+          currentSrcAlpha = weight
+        } else {
+          currentSrcAlpha = (baseSrcAlpha * weight + 128) >> 8
+        }
+
+        if (currentSrcAlpha === 0) {
+          dIdx++
+          sIdx++
+          mIdx++
+          continue
+        }
+
+        currentSrcColor = ((baseSrcColor & 0x00ffffff) | (currentSrcAlpha << 24)) >>> 0 as Color32
+      }
+
+      dst32[dIdx] = blendFn(currentSrcColor, dst32[dIdx] as Color32)
+
+      dIdx++
+      sIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    sIdx += sStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/clearPixelData.ts

@@ -0,0 +1,14 @@
+import type { Color32, Rect } from '../_types'
+import type { PixelData } from '../PixelData'
+import { fillPixelData } from './fillPixelData'
+
+/**
+ * Clears a region of the PixelData to transparent (0x00000000).
+ * Internally uses the optimized fillPixelData.
+ */
+export function clearPixelData(
+  dst: PixelData,
+  rect?: Partial<Rect>,
+): void {
+  fillPixelData(dst, 0 as Color32, rect)
+}

package/src/PixelData/fillPixelData.ts

@@ -0,0 +1,56 @@
+import type { Color32, Rect } from '../_types'
+import type { PixelData } from '../PixelData'
+
+/**
+ * A high-performance solid fill for PixelData.
+ */
+export function fillPixelData(
+  dst: PixelData,
+  color: Color32,
+  rect?: Partial<Rect>,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+  } = rect || {}
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // Destination Clipping
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) {
+    return
+  }
+
+  const dst32 = dst.data32
+  const dw = dst.width
+
+  // Optimization: If filling the entire buffer, use the native .fill()
+  if (actualW === dw && actualH === dst.height && x === 0 && y === 0) {
+    dst32.fill(color)
+    return
+  }
+
+  // Row-by-row fill for partial rectangles
+  for (let iy = 0; iy < actualH; iy++) {
+    const start = (y + iy) * dw + x
+    const end = start + actualW
+    dst32.fill(color, start, end)
+  }
+}

package/src/PixelData.ts

@@ -0,0 +1,20 @@
+import type { ImageDataLike } from './_types'
+
+export class PixelData {
+  public readonly data32: Uint32Array
+  public readonly width: number
+  public readonly height: number
+
+  constructor(public readonly imageData: ImageDataLike) {
+    this.width = imageData.width
+    this.height = imageData.height
+
+    // Create the view once.
+    // Shift right by 2 is a fast bitwise division by 4.
+    this.data32 = new Uint32Array(
+      imageData.data.buffer,
+      imageData.data.byteOffset,
+      imageData.data.byteLength >> 2,
+    )
+  }
+}

package/src/_types.ts

@@ -1,9 +1,15 @@
-// ALL values are 0-255 (including alpha which in CSS is 0-1)
+/** ALL values are 0-255 (including alpha which in CSS is 0-1) */
 export type RGBA = { r: number, g: number, b: number, a: number }
 
-// A 32-bit integer containing r,g,b,a data
+/** Represents a 32-bit color in 0xAABBGGRR (Little endian) */
 export type Color32 = number & { readonly __brandColor32: unique symbol }
 
+/**
+ * A function that defines how to combine a source color with a destination color.
+ * @param src - The incoming color (source).
+ * @param dst - The existing color in the buffer (destination).
+ * @returns The resulting 32-bit color to be written to the buffer.
+ */
 export type BlendColor32 = (src: Color32, dst: Color32) => Color32
 
 export type ImageDataLike = {
@@ -20,25 +26,127 @@ export type SerializedImageData = {
 
 export type Base64EncodedUInt8Array = string & { readonly __brandBase64UInt8Array: unique symbol }
 
-export type Rect = { x: number; y: number; w: number; h: number }
+/** Rectangle definition */
+export type Rect = {
+  x: number
+  y: number
+  w: number
+  h: number
+}
 
+/**
+ * Defines how mask values should be interpreted during a draw operation.
+ */
 export enum MaskType {
+  /**
+   * Values are treated as alpha weights.
+   * 0 is skipped, values > 0 are processed.
+   */
   ALPHA,
+  /**
+   *  Values are treated as on/off.
+   * 0 is fully transparent (skipped), any other value is fully opaque.
+   */
   BINARY
 }
 
-interface BaseMaskData {
-  readonly width: number
-  readonly height: number
-  readonly data: Uint8Array
+/** Strictly 0 or 1 */
+export type BinaryMask = Uint8Array & { readonly __brand: 'Binary' }
+/** Strictly 0-255 */
+export type AlphaMask = Uint8Array & { readonly __brand: 'Alpha' }
+
+export type AnyMask = BinaryMask | AlphaMask
+
+/**
+ * Configuration for pixel manipulation operations.
+ * Designed to be used by spreading a Rect object ({x, y, w, h}) directly.
+ */
+export interface PixelOptions {
+  /**
+   * The starting X coordinate in the destination buffer.
+   * @Defaults 0.
+   * */
+  x?: number
+  /**
+   * The starting Y coordinate in the destination buffer.
+   * @Default 0.
+   * */
+  y?: number
+  /**
+   * The width of the region to process.
+   * @Default Source width.
+   * */
+  w?: number
+  /**
+   * The height of the region to process.
+   * @Default Source height.
+   * */
+  h?: number
+
+  /**
+   * Overall layer opacity 0-255.
+   * @default 255
+   */
+  alpha?: number
+
+  /**
+   * Mask width.
+   * @default w
+   * */
+  mw?: number
+
+  /**
+   * X offset into the mask buffer.
+   * @default 0
+   * */
+  mx?: number
+
+  /**
+   * Y offset into the mask buffer.
+   * @default 0
+   * */
+  my?: number
+
+  /** An optional mask to restrict where pixels are written. */
+  mask?: AnyMask | null
+
+  /** The interpretation logic for the provided mask. Defaults to MaskType.Binary. */
+  maskType?: MaskType
+
+  /** If true the inverse of the mask will be applied */
+  invertMask?: boolean
 }
 
-export interface AlphaMask extends BaseMaskData {
-  readonly type: MaskType.ALPHA
+/**
+ * Configuration for blitting (copying/blending) one image into another.
+ */
+export interface PixelBlendOptions extends PixelOptions {
+  /**
+   * The source rectangle x-coordinate
+   * @default 0
+   */
+  sx?: number
+
+  /**
+   * The source rectangle y-coordinate
+   * @default 0
+   */
+  sy?: number
+
+  /** The specific blending function/algorithm to use for pixel math. */
+  blendFn?: BlendColor32
 }
 
-export interface BinaryMask extends BaseMaskData {
-  readonly type: MaskType.BINARY
+/**
+ * Configuration for operations that require color blending.
+ */
+export interface ColorBlendOptions extends PixelOptions {
+  /** The blending logic used to combine source and destination pixels. */
+  blendFn?: BlendColor32
 }
 
-export type AnyMask = AlphaMask | BinaryMask
+export type ApplyMaskOptions = Omit<PixelOptions, 'mask'>
+
+// export function invertBinaryMask(dst: BinaryMask): void
+// export function invertAlphaMask(dst: AlphaMask): void
+

package/src/{ImageData/blend-modes.ts → blend-modes.ts}

@@ -1,4 +1,4 @@
-import type { BlendColor32, Color32 } from '../_types'
+import type { BlendColor32, Color32 } from './_types'
 
 export const sourceOverColor32: BlendColor32 = (src, dst) => {
   const a = (src >>> 24) & 0xFF

package/src/index.ts

@@ -1,7 +1,7 @@
-export * from './ImageData/blend-modes'
-export * from './ImageData/blit'
-export * from './ImageData/mask'
-export * from './ImageData/read-write-pixels'
-export * from './ImageData/serialization'
 export * from './_types'
+export * from './blend-modes'
 export * from './color'
+export * from './ImageData/copyImageData'
+export * from './ImageData/extractImageData'
+export * from './ImageData/serialization'
+export * from './PixelData/blendPixelData'