@oliversalzburg/js-utils 0.7.0 → 0.7.1

package/lib/graphics/core.js

@@ -0,0 +1,146 @@
+/**
+ * The golden ratio.
+ * @see {@link https://en.wikipedia.org/wiki/Golden_ratio}
+ */
+export const GOLDEN_RATIO = 1.618033988749;
+/**
+ * Constrains a color component value to single-byte range (`0`-`255`).
+ * @param c - A color component value.
+ * @returns The input value constrained into single-byte range.
+ */
+export const safeRGBComponent = (c) => {
+    if (c < 0) {
+        c = 0;
+    }
+    if (255 < c) {
+        c = 255;
+    }
+    return Math.trunc(c);
+};
+/**
+ * Constructs a 32bit integer value that represents an RGBA color value.
+ * @param r - The R component.
+ * @param g - The G component.
+ * @param b - The B component.
+ * @param a - The A component.
+ * @returns The constructed color value.
+ */
+export const fromRGBA = (r, g, b, a) => {
+    r = safeRGBComponent(r);
+    g = safeRGBComponent(g);
+    b = safeRGBComponent(b);
+    a = safeRGBComponent(a);
+    return (r << 24) | (g << 16) | (b << 8) | a;
+};
+/**
+ * Constructs a 32bit integer value that represents an RGBA color value.
+ * The A component is fixed to `255`
+ * @param r - The R component.
+ * @param g - The G component.
+ * @param b - The B component.
+ * @returns The constructed color value.
+ */
+export const fromRGB = (r, g, b) => {
+    return fromRGBA(r, g, b, 255);
+};
+/**
+ * Extracts the R component from a color value.
+ * @param color - The color value.
+ * @returns The R component of the color value.
+ */
+export const getR = (color) => {
+    return (color >> 24) & 0xff;
+};
+/**
+ * Extracts the G component from a color value.
+ * @param color - The color value.
+ * @returns The G component of the color value.
+ */
+export const getG = (color) => {
+    return (color >> 16) & 0xff;
+};
+/**
+ * Extracts the B component from a color value.
+ * @param color - The color value.
+ * @returns The B component of the color value.
+ */
+export const getB = (color) => {
+    return (color >> 8) & 0xff;
+};
+/**
+ * Extracts the A component from a color value.
+ * @param color - The color value.
+ * @returns The A component of the color value.
+ */
+export const getA = (color) => {
+    return color & 0xff;
+};
+/**
+ * Returns a new color that is a blend between a source and a destination
+ * color linerally. The alpha component in these colors is ignored. Instead, the provided
+ * `alpha` value is used to blend between the two colors.
+ * @param src - The source color.
+ * @param dst - The destination color.
+ * @param alpha - The alpha value to use for blending.
+ * @returns The blended color.
+ */
+export const blend = (src, dst, alpha) => {
+    if (alpha >= 255) {
+        return dst;
+    }
+    if (alpha <= 0) {
+        return src;
+    }
+    src |= 0;
+    dst |= 0;
+    return fromRGB((alpha * getR(dst) + (255 - alpha) * getR(src)) >> 8, (alpha * getG(dst) + (255 - alpha) * getG(src)) >> 8, (alpha * getB(dst) + (255 - alpha) * getB(src)) >> 8);
+};
+/**
+ * Returns a new color that is a blend between a source and a destination
+ * color additively. The alpha component in these colors is ignored. Instead, the provided
+ * `alpha` value is used to blend between the two colors.
+ * @param src - The source color.
+ * @param dst - The destination color.
+ * @param alpha - The alpha value to use for blending.
+ * @returns The blended color.
+ */
+export const blendAdditive = (src, dst, alpha) => {
+    if (alpha >= 255) {
+        return dst;
+    }
+    if (alpha <= 0) {
+        return src;
+    }
+    return fromRGB(((alpha * getR(dst)) >> 8) + getR(src), ((alpha * getG(dst)) >> 8) + getG(src), ((alpha * getB(dst)) >> 8) + getB(src));
+};
+/**
+ * Returns a new color that is a blend between a source and a destination
+ * color subtractively. The alpha component in these colors is ignored. Instead, the provided
+ * `alpha` value is used to blend between the two colors.
+ * @param src - The source color.
+ * @param dst - The destination color.
+ * @param alpha - The alpha value to use for blending.
+ * @returns The blended color.
+ */
+export const blendSubtractive = (src, dst, alpha) => {
+    if (alpha >= 255) {
+        return dst;
+    }
+    if (alpha <= 0) {
+        return src;
+    }
+    const r = getR(src) - ((alpha * getR(dst)) >> 8);
+    const g = getG(src) - ((alpha * getG(dst)) >> 8);
+    const b = getB(src) - ((alpha * getB(dst)) >> 8);
+    return fromRGB(r < 0 ? 0 : r, g < 0 ? 0 : g, b < 0 ? 0 : b);
+};
+/**
+ * Converts a color value to grayscale.
+ * @param color - The color to convert.
+ * @returns The grayscale value appropriate for the color.
+ */
+export const toGrayScale = (color) => {
+    const gs = getR(color) * 0.3 + getG(color) * 0.59 + getB(color) * 0.11;
+    return fromRGBA(gs, gs, gs, getA(color));
+};
+//# sourceMappingURL=core.js.map

package/lib/graphics/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../source/graphics/core.ts"],"names":[],"mappings":"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"}

package/lib/graphics/palette-sampler.d.ts

@@ -0,0 +1,7 @@
+import { type Palette } from "./palette.js";
+/**
+ * Renders the colors of a palette into a canvas.
+ * @param palette - The palette to render.
+ * @param canvas - The canvas element to render to.
+ */
+export declare const renderPaletteSample: (palette: Palette, canvas: HTMLCanvasElement | OffscreenCanvas) => void;

package/lib/graphics/palette-sampler.js

@@ -0,0 +1,21 @@
+import { mustExist } from "../data/nil.js";
+import { paletteName } from "./palette.js";
+/**
+ * Renders the colors of a palette into a canvas.
+ * @param palette - The palette to render.
+ * @param canvas - The canvas element to render to.
+ */
+export const renderPaletteSample = (palette, canvas) => {
+    const context = mustExist(canvas.getContext("2d"));
+    context.globalAlpha = 255;
+    const step = canvas.width / palette.colors.length;
+    for (let x = 0; x < palette.colors.length; ++x) {
+        const fillColor = (palette.colors[x] << 8) | 0xff;
+        context.fillStyle = `#${fillColor.toString(16).padStart(8, "0")}`;
+        context.fillRect(x * step, 0, step, canvas.height);
+    }
+    context.font = "13px monospace";
+    context.fillStyle = "#ffffffff";
+    context.fillText(paletteName(palette.paletteIndex), 5, canvas.height * 0.8);
+};
+//# sourceMappingURL=palette-sampler.js.map

package/lib/graphics/palette-sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"palette-sampler.js","sourceRoot":"","sources":["../../source/graphics/palette-sampler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAgB,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAClC,OAAgB,EAChB,MAA2C,EAC1C,EAAE;IACH,MAAM,OAAO,GAAG,SAAS,CACxB,MAAM,CAAC,UAAU,CAAC,IAAI,CAGf,CACP,CAAC;IACF,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC;IAE1B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;IAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QAClD,OAAO,CAAC,SAAS,GAAG,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAChC,OAAO,CAAC,SAAS,GAAG,WAAW,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;AAC7E,CAAC,CAAC"}

package/lib/graphics/palette.d.ts

@@ -0,0 +1,120 @@
+import { type Random } from "../data/random.js";
+/**
+ * Color palettes that can be used to quickly colorize a drawing.
+ */
+export declare const PALETTES: number[][];
+/**
+ * The indices of pre-defined palettes, with friendly names.
+ * @see {@linkcode PALETTES}
+ */
+export declare const NamedPalettes: {
+    /**
+     * ![Autumn lake colors](../../docs/media/palette-autumn-lake.png)
+     */
+    AutumnLake: number;
+    /**
+     * ![Camouflage colors](../../docs/media/palette-camouflage.png)
+     */
+    Camouflage: number;
+    /**
+     * ![Frog pond colors](../../docs/media/palette-frog-pond.png)
+     */
+    FrogPond: number;
+    /**
+     * ![Lillypads colors](../../docs/media/palette-lillypads.png)
+     */
+    Lillypads: number;
+    /**
+     * ![Midnight colors](../../docs/media/palette-midnight.png)
+     */
+    Midnight: number;
+    /**
+     * ![Plight colors](../../docs/media/palette-plight.png)
+     */
+    Plight: number;
+    /**
+     * ![Riverside colors](../../docs/media/palette-riverside.png)
+     */
+    Riverside: number;
+    /**
+     * ![Seaside colors](../../docs/media/palette-seaside.png)
+     */
+    Seaside: number;
+    /**
+     * ![Spring colors](../../docs/media/palette-spring.png)
+     */
+    Spring: number;
+    /**
+     * ![Sunflower field colors](../../docs/media/palette-sunflower-field.png)
+     */
+    SunflowerField: number;
+    /**
+     * ![Terminator colors](../../docs/media/palette-terminator.png)
+     */
+    Terminator: number;
+    /**
+     * ![Terra colors](../../docs/media/palette-terra.png)
+     */
+    Terra: number;
+    /**
+     * ![Tundra colors](../../docs/media/palette-tundra.png)
+     */
+    Tundra: number;
+};
+/**
+ * Retrieves a friendly name for a pallete index.
+ * @param paletteIndex - The index of the pre-defined palette.
+ * @returns The friendly name of the palette, or `"<unknown>"`.
+ */
+export declare const paletteName: (paletteIndex: number) => string;
+/**
+ * Provides pre-defined color values for drawing operations.
+ */
+export declare class Palette {
+    #private;
+    /**
+     * Retrieve the index of the currently selected, pre-defined palette values.
+     * @see {@linkcode PALETTES}
+     * @returns The index of the currently selected, pre-defined palette values.
+     */
+    get paletteIndex(): number;
+    /**
+     * Retrieve the 24bit color values of the currently selected palette.
+     * @returns The colors in the palette.
+     */
+    get colors(): ReadonlyArray<number>;
+    /**
+     * Constructs a new palette.
+     * @param paletteIndex - The index of the pre-defined palette to use.
+     */
+    constructor(paletteIndex?: number);
+    /**
+     * Uses the next pre-defined color value set for this palette.
+     * @returns This instance.
+     */
+    nextPalette(): this;
+    /**
+     * Retrieve a random color from the palette.
+     * @param randomInstance - The PRNG to use. Ideally, supply your own.
+     * @returns A random color from the palette.
+     */
+    someColor(randomInstance?: Random): number;
+}
+/**
+ * A pre-constructed palette instance, for convenience.
+ */
+export declare const palette: Palette;
+/**
+ * Retrieves a random color from the current global palette.
+ * Uses the global {@linkcode random} object.
+ * @returns A random color.
+ */
+export declare const someColor: () => number;
+/**
+ * Switches the global palette to the next available preset.
+ * @returns The new new global palette.
+ * @deprecated Use {@linkcode Palette} instead.
+ */
+export declare const nextPalette: () => number[];
+export declare const hslPalette: (entries: number, shift?: number, saturation?: number, luminance?: number) => Array<[number, number, number]>;
+export declare const hsvPalette: (entries: number, shift?: number, saturation?: number, value?: number) => Array<[number, number, number]>;