pixel-data-js 0.0.3 → 0.2.0

package/dist/index.prod.d.ts

@@ -1,7 +1,17 @@
+type RGBA = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+type Color32 = number & {
+    readonly __brandColor32: unique symbol;
+};
+type BlendColor32 = (src: Color32, dst: Color32) => Color32;
 type ImageDataLike = {
     width: number;
     height: number;
-    data: Uint8ClampedArray;
+    data: Uint8ClampedArray<ArrayBuffer>;
 };
 type SerializedImageData = {
     width: number;
@@ -11,9 +21,204 @@ type SerializedImageData = {
 type Base64EncodedUInt8Array = string & {
     readonly __brandBase64UInt8Array: unique symbol;
 };
+type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+declare enum MaskType {
+    ALPHA = 0,
+    BINARY = 1
+}
+interface BaseMaskData {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+}
+interface AlphaMask extends BaseMaskData {
+    readonly type: MaskType.ALPHA;
+}
+interface BinaryMask extends BaseMaskData {
+    readonly type: MaskType.BINARY;
+}
+type AnyMask = AlphaMask | BinaryMask;
+
+declare const sourceOverColor32: BlendColor32;
+/**
+ * Screen: Lightens the destination (inverse of Multiply).
+ * Result = 1 - ((1 - Src) * (1 - Dst))
+ */
+declare const screenColor32: BlendColor32;
+/**
+ * Linear Dodge (Additive): Simply adds the source to the destination.
+ * Clamps at 255.
+ */
+declare const linearDodgeColor32: BlendColor32;
+/**
+ * Multiply: Darkens the destination based on the source color.
+ * Result = (Src * Dst) / 255
+ */
+declare const multiplyColor32: BlendColor32;
+/**
+ * Difference: Subtracts the darker color from the lighter color.
+ * Result = |Src - Dst|
+ */
+declare const differenceColor32: BlendColor32;
+/**
+ * Hard Light: Decides Multiply vs Screen based on SOURCE brightness.
+ * Acts like a harsh spotlight.
+ */
+declare const hardLightColor32: BlendColor32;
+/**
+ * Color Burn: Darkens the destination to reflect the source color.
+ * Intense saturation in the darks.
+ */
+declare const colorBurnColor32: BlendColor32;
+/**
+ * Overlay: The classic "Contrast" mode.
+ * Decides Multiply vs Screen based on DESTINATION brightness.
+ */
+declare const overlayColor32: BlendColor32;
+declare const COLOR_32_BLEND_MODES: {
+    sourceOver: BlendColor32;
+    screen: BlendColor32;
+    linearDodge: BlendColor32;
+    multiply: BlendColor32;
+    difference: BlendColor32;
+    overlay: BlendColor32;
+    hardLight: BlendColor32;
+    colorBurn: BlendColor32;
+};
+
+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
+ * });
+ */
+declare function blendImageData(dst: ImageDataLike, src: ImageDataLike, opts: BlendImageDataOptions): void;
+
+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.
+ */
+declare function applyBinaryMask(dst: ImageDataLike, mask: BinaryMask, opts?: ApplyMaskOptions): ImageDataLike | undefined;
+/**
+ * Applies a smooth alpha mask to an RGBA buffer.
+ * Multiplies existing Alpha by (maskValue / 255).
+ */
+declare function applyAlphaMask(dst: ImageData, mask: AlphaMask, opts?: ApplyMaskOptions): void;
+
+declare function makeImageDataColor32Adapter(imageData: ImageDataLike): {
+    inBounds: (x: number, y: number) => boolean;
+    imageData: ImageDataLike;
+    data32: Uint32Array<ArrayBuffer>;
+    setPixel: (x: number, y: number, color: Color32) => void;
+    getPixel: (x: number, y: number) => Color32 | undefined;
+};
+declare function extractPixelData(imageData: ImageDataLike, rect: Rect): Uint8ClampedArray;
+declare function extractPixelData(imageData: ImageDataLike, x: number, y: number, w: number, h: number): Uint8ClampedArray;
+declare function copyImageData({ data, width, height }: ImageDataLike): ImageData;
+declare function copyImageDataLike({ data, width, height }: ImageDataLike): ImageDataLike;
 
 declare function base64EncodeArrayBuffer(buffer: ArrayBufferLike): Base64EncodedUInt8Array;
-declare function base64DecodeArrayBuffer(encoded: Base64EncodedUInt8Array): Uint8ClampedArray;
+declare function base64DecodeArrayBuffer(encoded: Base64EncodedUInt8Array): Uint8ClampedArray<ArrayBuffer>;
 /**
  * Serialize for use in JSON. Pixel data is stored as base64 encoded string.
  */
@@ -23,4 +228,45 @@ declare function deserializeRawImageData<T extends SerializedImageData>(serializ
 declare function deserializeImageData<T extends SerializedImageData>(serialized: T): ImageData;
 declare function deserializeNullableImageData<T extends SerializedImageData | null>(serialized: T): T extends null ? null : ImageData;
 
-export { base64DecodeArrayBuffer, base64EncodeArrayBuffer, deserializeImageData, deserializeNullableImageData, deserializeRawImageData, serializeImageData, serializeNullableImageData };
+/**
+ * Packs RGBA into a 32-bit integer compatible with
+ * Little-Endian Uint32Array views on ImageData.
+ */
+declare function packColor(r: number, g: number, b: number, a: number): Color32;
+declare function packRGBA({ r, g, b, a }: RGBA): Color32;
+declare const unpackRed: (packed: Color32) => number;
+declare const unpackGreen: (packed: Color32) => number;
+declare const unpackBlue: (packed: Color32) => number;
+declare const unpackAlpha: (packed: Color32) => number;
+declare function unpackColor(packed: Color32): RGBA;
+declare function unpackColorTo(packed: Color32, scratch?: RGBA): RGBA;
+declare function colorDistance(a: Color32, b: Color32): number;
+/**
+ * Linearly interpolates between two 32-bit colors using a floating-point weight.
+ * * This is the preferred method for UI animations or scenarios where high
+ * precision is required. It uses the standard `a + t * (b - a)` formula
+ * for each channel.
+ * @param a - The starting color as a 32-bit integer (AABBGGRR).
+ * @param b - The target color as a 32-bit integer (AABBGGRR).
+ * @param t - The interpolation factor between 0.0 and 1.0.
+ * @returns The interpolated 32-bit color.
+ */
+declare function lerpColor32(a: Color32, b: Color32, t: number): Color32;
+/**
+ * Linearly interpolates between two 32-bit colors using integer fixed-point math.
+ * Highly optimized for image processing and real-time blitting. It processes
+ * channels in parallel using bitmasks (RB and GA pairs).
+ * @note Subject to a 1-bit drift (rounding down) due to fast bit-shift division.
+ * @param src - The source (foreground) color as a 32-bit integer.
+ * @param dst - The destination (background) color as a 32-bit integer.
+ * @param w - The blend weight as a byte value from 0 to 255. Where 0 is 100% dst and 255 is 100% src
+ * @returns The blended 32-bit color.
+ */ declare function lerpColor32Fast(src: Color32, dst: Color32, w: number): Color32;
+declare function color32ToHex(color: Color32): string;
+/**
+ * Converts a 32-bit integer (0xAABBGGRR) to a CSS rgba() string.
+ * Example: 0xFF0000FF -> "rgba(255,0,0,1)"
+ */
+declare function color32ToCssRGBA(color: Color32): string;
+
+export { type AlphaMask, type AnyMask, type ApplyMaskOptions, type Base64EncodedUInt8Array, type BinaryMask, type BlendColor32, type BlendImageDataOptions, COLOR_32_BLEND_MODES, type Color32, type ImageDataLike, MaskType, type RGBA, type Rect, type SerializedImageData, applyAlphaMask, applyBinaryMask, base64DecodeArrayBuffer, base64EncodeArrayBuffer, blendImageData, color32ToCssRGBA, color32ToHex, colorBurnColor32, colorDistance, copyImageData, copyImageDataLike, deserializeImageData, deserializeNullableImageData, deserializeRawImageData, differenceColor32, extractPixelData, hardLightColor32, lerpColor32, lerpColor32Fast, linearDodgeColor32, makeImageDataColor32Adapter, multiplyColor32, overlayColor32, packColor, packRGBA, screenColor32, serializeImageData, serializeNullableImageData, sourceOverColor32, unpackAlpha, unpackBlue, unpackColor, unpackColorTo, unpackGreen, unpackRed };