pixel-data-js 0.2.0 → 0.4.0

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,18 @@
-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 './ImageData/writeImageData'
+
+export * from './Mask/copyMask'
+export * from './Mask/invertMask'
+export * from './Mask/mergeMasks'
+
+export * from './PixelData/applyMaskToPixelData'
+export * from './PixelData/blendColorPixelData'
+export * from './PixelData/blendPixelData'
+export * from './PixelData/clearPixelData'
+export * from './PixelData/fillPixelData'

package/src/ImageData/blit.ts

@@ -1,177 +0,0 @@
-import { type AnyMask, type BlendColor32, type Color32, type ImageDataLike, MaskType } from '../_types'
-import { sourceOverColor32 } from './blend-modes'
-
-export type BlendImageDataOptions = {
-  /**
-   * The x-coordinate in the destination image where the blend begins.
-   * @default 0
-   */
-  dx?: number
-
-  /**
-   * The y-coordinate in the destination image where the blend begins.
-   * @default 0
-   */
-  dy?: number
-
-  /**
-   * The x-coordinate of the top-left corner of the sub-rectangle
-   * of the source image to extract.
-   * @default 0
-   */
-  sx?: number
-
-  /**
-   * The y-coordinate of the top-left corner of the sub-rectangle
-   * of the source image to extract.
-   * @default 0
-   */
-  sy?: number
-
-  /**
-   * The width of the sub-rectangle of the source image to extract.
-   * Defaults to the full remaining width of the source.
-   */
-  sw?: number
-
-  /**
-   * The height of the sub-rectangle of the source image to extract.
-   * Defaults to the full remaining height of the source.
-   */
-  sh?: number
-
-  /**
-   * Overall layer opacity, typically ranging from 0.0 (transparent) to 1.0 (opaque).
-   * @default 1.0
-   */
-  opacity?: number
-
-  /**
-   * Same as opacity but is 0-255 and faster when processing. If Present opacity is ignored.
-   * @default undefined
-   */
-  alpha?: number
-
-  /**
-   * An optional alpha mask buffer.
-   * The values in this array (0-255) determine the intensity of the blend
-   * at each corresponding pixel.
-   */
-  mask?: AnyMask | null
-
-  /**
-   * The specific blending function/algorithm to use for pixel math
-   * (e.g., Multiply, Screen, Overlay).
-   */
-  blendFn?: BlendColor32
-};
-
-/**
- * Blits source ImageData into a destination ImageData using 32-bit integer bitwise blending.
- * This function bypasses standard Canvas API 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
- * blendImageData32(ctx.getImageData(0,0,100,100), sprite, {
- *   blendFn: COLOR_32_BLEND_MODES.multiply,
- *   mask: brushMask,
- *   maskMode: MaskMode.ALPHA
- * });
- */
-export function blendImageData(
-  dst: ImageDataLike,
-  src: ImageDataLike,
-  opts: BlendImageDataOptions,
-) {
-  let {
-    dx = 0,
-    dy = 0,
-    sx = 0,
-    sy = 0,
-    sw = src.width,
-    sh = src.height,
-    opacity = 1,
-    alpha,
-    blendFn = sourceOverColor32,
-    mask,
-  } = opts
-
-  // 1. Clip Source Area
-  if (sx < 0) {
-    dx -= sx
-    sw += sx
-    sx = 0
-  }
-  if (sy < 0) {
-    dy -= sy
-    sh += sy
-    sy = 0
-  }
-  sw = Math.min(sw, src.width - sx)
-  sh = Math.min(sh, src.height - sy)
-
-  // 2. Clip Destination Area
-  if (dx < 0) {
-    sx -= dx
-    sw += dx
-    dx = 0
-  }
-  if (dy < 0) {
-    sy -= dy
-    sh += dy
-    dy = 0
-  }
-  const actualW = Math.min(sw, dst.width - dx)
-  const actualH = Math.min(sh, dst.height - dy)
-
-  if (actualW <= 0 || actualH <= 0) return
-
-  // 32-bit views of the same memory
-  const dst32 = new Uint32Array(dst.data.buffer)
-  const src32 = new Uint32Array(src.data.buffer)
-
-  const dw = dst.width
-  const sw_orig = src.width
-
-  const gAlpha = alpha !== undefined
-    ? (alpha | 0)
-    : Math.round(opacity * 255)
-
-  const maskIsAlpha = mask?.type === MaskType.ALPHA
-
-  for (let iy = 0; iy < actualH; iy++) {
-    const dRow = (iy + dy) * dw
-    const sRow = (iy + sy) * sw_orig
-
-    for (let ix = 0; ix < actualW; ix++) {
-      const di = dRow + (ix + dx)
-      const si = sRow + (ix + sx)
-
-      let s = src32[si] as Color32
-      let sa = (s >>> 24) & 0xFF
-
-      // skip fully transparent pixel
-      if (sa === 0) continue
-
-      let activeWeight = gAlpha
-
-      if (mask) {
-        const m = mask.data[si]
-        if (m === 0) continue
-        activeWeight = maskIsAlpha ? (m * activeWeight + 128) >> 8 : activeWeight
-      }
-
-      if (activeWeight < 255) {
-        sa = (sa * activeWeight + 128) >> 8
-      }
-
-      // If combined alpha is 0 after masking/opacity, skip the blend math
-      if (sa === 0) continue
-
-      // Re-pack source with final calculated alpha
-      s = ((s & 0x00FFFFFF) | (sa << 24)) >>> 0 as Color32
-
-      dst32[di] = blendFn(s, dst32[di] as Color32)
-    }
-  }
-}

package/src/ImageData/mask.ts

@@ -1,150 +0,0 @@
-import type { AlphaMask, BinaryMask, ImageDataLike } from '../_types'
-
-export type ApplyMaskOptions = {
-  /**
-   * The x-coordinate in the destination image where the mask begins.
-   * @default 0
-   */
-  dx?: number
-
-  /**
-   * The y-coordinate in the destination image where the mask begins.
-   * @default 0
-   */
-  dy?: number
-
-  /**
-   * The x-coordinate of the top-left corner of the sub-rectangle
-   * of the source image to extract.
-   * @default 0
-   */
-  sx?: number
-
-  /**
-   * The y-coordinate of the top-left corner of the sub-rectangle
-   * of the source image to extract.
-   * @default 0
-   */
-  sy?: number
-
-  /**
-   * The width of the sub-rectangle of the source image to extract.
-   * Defaults to the full remaining width of the source.
-   */
-  sw?: number
-
-  /**
-   * The height of the sub-rectangle of the source image to extract.
-   * Defaults to the full remaining height of the source.
-   */
-  sh?: number;
-}
-
-/**
- * Applies a binary (on/off) mask to an RGBA buffer.
- * If mask value is 0, pixel becomes transparent.
- */
-export function applyBinaryMask(
-  dst: ImageDataLike,
-  mask: BinaryMask,
-  opts: ApplyMaskOptions = {},
-) {
-  const { width: maskWidth, height: maskHeight } = mask
-
-  const { dx = 0, dy = 0, sx = 0, sy = 0, sw = maskWidth, sh = maskHeight } = opts
-
-  // 1. Calculate intersection boundaries
-  const x0 = Math.max(0, dx, dx + (0 - sx))
-  const y0 = Math.max(0, dy, dy + (0 - sy))
-  const x1 = Math.min(dst.width, dx + sw, dx + (maskWidth - sx))
-  const y1 = Math.min(dst.height, dy + sh, dy + (maskHeight - sy))
-
-  if (x1 <= x0 || y1 <= y0) return
-
-  const { data: dstData, width: dstW } = dst
-
-  for (let y = y0; y < y1; y++) {
-    const maskY = y - dy + sy
-    const dstRowOffset = y * dstW * 4
-    const maskRowOffset = maskY * maskWidth
-
-    for (let x = x0; x < x1; x++) {
-      const maskX = x - dx + sx
-      const mIdx = maskRowOffset + maskX
-
-      // Binary check: If mask is 0, kill the alpha
-      if (mask.data[mIdx] === 0) {
-        const aIdx = dstRowOffset + (x * 4) + 3
-        dstData[aIdx] = 0
-      }
-    }
-  }
-
-  return dst
-}
-
-/**
- * Applies a smooth alpha mask to an RGBA buffer.
- * Multiplies existing Alpha by (maskValue / 255).
- */
-export function applyAlphaMask(
-  dst: ImageData,
-  mask: AlphaMask,
-  opts: ApplyMaskOptions = {},
-): void {
-  let { dx = 0, dy = 0, sx = 0, sy = 0, sw = mask.width, sh = mask.height } = opts
-
-  // 1. Clipping Logic
-  if (dx < 0) {
-    sx -= dx
-    sw += dx
-    dx = 0
-  }
-  if (dy < 0) {
-    sy -= dy
-    sh += dy
-    dy = 0
-  }
-  if (sx < 0) {
-    dx -= sx
-    sw += sx
-    sx = 0
-  }
-  if (sy < 0) {
-    dy -= sy
-    sh += sy
-    sy = 0
-  }
-  const actualW = Math.min(sw, dst.width - dx, mask.width - sx)
-  const actualH = Math.min(sh, dst.height - dy, mask.height - sy)
-
-  if (actualW <= 0 || actualH <= 0) return
-
-  const dData = dst.data
-  const mData = mask.data
-  const dW = dst.width
-  const mW = mask.width
-
-  for (let y = 0; y < actualH; y++) {
-    const dOffset = ((dy + y) * dW + dx) << 2
-    const mOffset = (sy + y) * mW + sx
-
-    for (let x = 0; x < actualW; x++) {
-      const mVal = mData[mOffset + x]
-
-      if (mVal === 255) continue
-
-      const aIdx = dOffset + (x << 2) + 3
-
-      // --- BRANCH: Zero Alpha ---
-      if (mVal === 0) {
-        dData[aIdx] = 0
-        continue
-      }
-
-      // To get 101 from 200 * 128, we use the bias (a * m + 257) >> 8
-      // 25600 + 257 = 25857. 25857 >> 8 = 101.
-      dData[aIdx] = (dData[aIdx] * mVal + 257) >> 8
-    }
-  }
-}