@carbonenginejs/runtime-utils 0.1.0

package/src/bytes.js

@@ -0,0 +1,56 @@
+/** Returns a zero-copy Uint8Array view over supported byte input. */
+export function asUint8Array(value, label = "value")
+{
+    if (value instanceof Uint8Array)
+    {
+        return value;
+    }
+
+    if (value instanceof ArrayBuffer)
+    {
+        return new Uint8Array(value);
+    }
+
+    if (ArrayBuffer.isView(value))
+    {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+
+    throw new TypeError(`${label} must be a Uint8Array, ArrayBuffer, or ArrayBuffer view.`);
+}
+
+/** Returns an owned copy of supported byte input. */
+export function copyBytes(value, label = "value")
+{
+    return asUint8Array(value, label).slice();
+}
+
+/** Copies exactly the visible byte range into a standalone ArrayBuffer. */
+export function toArrayBuffer(value, label = "value")
+{
+    const bytes = asUint8Array(value, label);
+
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+
+/** Tests whether byte input starts with the complete supplied prefix. */
+export function hasBytePrefix(value, prefix)
+{
+    const bytes = asUint8Array(value, "value");
+    const expected = asUint8Array(prefix, "prefix");
+
+    if (bytes.byteLength < expected.byteLength)
+    {
+        return false;
+    }
+
+    for (let index = 0; index < expected.byteLength; index++)
+    {
+        if (bytes[index] !== expected[index])
+        {
+            return false;
+        }
+    }
+
+    return true;
+}

package/src/compression.js

@@ -0,0 +1,56 @@
+import { asUint8Array, hasBytePrefix } from "./bytes.js";
+
+const GZIP_PREFIX = new Uint8Array([ 0x1f, 0x8b ]);
+
+/** Returns whether byte input has the gzip magic prefix. */
+export function isGzip(value)
+{
+    return hasBytePrefix(value, GZIP_PREFIX);
+}
+
+/** Decompresses bytes with the platform DecompressionStream API. */
+export async function decompressBytes(value, format, options = {})
+{
+    const DecompressionStreamClass = Object.hasOwn(options, "decompressionStreamClass")
+        ? options.decompressionStreamClass
+        : globalThis.DecompressionStream;
+    const ResponseClass = Object.hasOwn(options, "responseClass")
+        ? options.responseClass
+        : globalThis.Response;
+
+    if (typeof DecompressionStreamClass !== "function" || typeof ResponseClass !== "function")
+    {
+        const error = new Error(
+            `DecompressionStream support for ${JSON.stringify(format)} is unavailable in this environment.`
+        );
+
+        error.code = "CJS_DECOMPRESSION_UNSUPPORTED";
+        throw error;
+    }
+
+    const source = new ResponseClass(asUint8Array(value, "compressed input"));
+
+    if (!source.body)
+    {
+        throw new Error("The platform Response did not expose a readable byte stream.");
+    }
+
+    const stream = source.body.pipeThrough(new DecompressionStreamClass(String(format)));
+    const output = await new ResponseClass(stream).arrayBuffer();
+
+    return new Uint8Array(output);
+}
+
+/** Decompresses one gzip byte sequence. */
+export function decompressGzip(value, options = {})
+{
+    return decompressBytes(value, "gzip", options);
+}
+
+/** Decompresses gzip input and returns an unchanged view for plain bytes. */
+export function decompressGzipIfNeeded(value, options = {})
+{
+    const bytes = asUint8Array(value, "input");
+
+    return isGzip(bytes) ? decompressGzip(bytes, options) : Promise.resolve(bytes);
+}

package/src/constants/index.js

@@ -0,0 +1,6 @@
+export * from "../media/index.js";
+export * from "../graphics/index.js";
+export * from "../audio/index.js";
+export * from "../shader/index.js";
+export * from "../d3d/index.js";
+export * from "../webgpu/index.js";

package/src/constants.js

@@ -0,0 +1,15 @@
+/**
+ * Small WebGL numeric constants used by the typed-array pool helpers.
+ *
+ * These stay local to keep the math subpaths independently browser-friendly:
+ * importing the old ccpwgl `constant` alias would pull the package back toward
+ * an application-specific module graph.
+ */
+
+export const GL_BYTE = 5120;
+export const GL_UNSIGNED_BYTE = 5121;
+export const GL_SHORT = 5122;
+export const GL_UNSIGNED_SHORT = 5123;
+export const GL_INT = 5124;
+export const GL_UNSIGNED_INT = 5125;
+export const GL_FLOAT = 5126;

package/src/curve.js

@@ -0,0 +1,419 @@
+export const curve = {};
+
+/**
+ * Evaluates a curve
+ *
+ * @param {{}|Tw2GeometryCurve} curve
+ * @param {Array} curve.knots
+ * @param {number} curve.degree
+ * @param {Array} curve.controls
+ * @param {number} curve.dimension
+ * @param {number} time
+ * @param {*} value
+ * @param {Boolean} cycle
+ * @param {number} duration
+ */
+curve.evaluate = function(curve, time, value, cycle, duration)
+{
+    let count = curve.knots.length;
+    if (!count || !curve.dimension || !curve.controls.length) return value;
+
+    const lastKnot = curve.knots[count - 1];
+    if (cycle)
+    {
+        duration = duration > 0 ? duration : lastKnot;
+        if (duration > 0)
+        {
+            time = ((time % duration) + duration) % duration;
+        }
+    }
+    else if (time <= curve.knots[0] || time >= lastKnot)
+    {
+        const control = time <= curve.knots[0] ? 0 : count - 1;
+        for (let i = 0; i < curve.dimension; ++i)
+        {
+            value[i] = curve.controls[control * curve.dimension + i];
+        }
+        return value;
+    }
+
+    let knot = count - 1;
+    let t = 0;
+    if (cycle && (time < curve.knots[0] || time >= lastKnot))
+    {
+        knot = 0;
+    }
+    else for (let i = 0; i < curve.knots.length; ++i)
+    {
+        if (curve.knots[i] > time)
+        {
+            knot = i;
+            break;
+        }
+    }
+
+    if (curve.degree === 0)
+    {
+        for (let i = 0; i < curve.dimension; ++i)
+        {
+            value[i] = curve.controls[knot * curve.dimension + i];
+        }
+    }
+    else if (curve.degree === 1)
+    {
+        const knot0 = cycle ? (knot + count - 1) % count : knot === 0 ? 0 : knot - 1;
+        let
+            start = curve.knots[knot0],
+            end = curve.knots[knot],
+            localTime = time;
+
+        if (cycle && end < start)
+        {
+            end += duration;
+        }
+        if (cycle && localTime < start)
+        {
+            localTime += duration;
+        }
+        t = end !== start ? (localTime - start) / (end - start) : 0;
+
+        for (let i = 0; i < curve.dimension; ++i)
+        {
+            value[i] = curve.controls[knot0 * curve.dimension + i] * (1 - t) + curve.controls[knot * curve.dimension + i] * t;
+        }
+    }
+    else
+    {
+        let k_2 = cycle ? (knot + count - 2) % count : knot === 0 ? 0 : Math.max(0, knot - 2);
+        let k_1 = cycle ? (knot + count - 1) % count : knot === 0 ? 0 : knot - 1;
+
+        let p1 = (k_2) * curve.dimension;
+        let p2 = (k_1) * curve.dimension;
+        let p3 = knot * curve.dimension;
+
+        let ti_2 = curve.knots[k_2];
+        let ti_1 = curve.knots[k_1];
+        let ti = curve.knots[knot];
+        let ti1 = curve.knots[(knot + 1) % count];
+
+        if (ti_2 > ti)
+        {
+            ti += duration;
+            ti1 += duration;
+            time += duration;
+        }
+
+        if (ti_1 > ti)
+        {
+            ti += duration;
+            ti1 += duration;
+            time += duration;
+        }
+
+        if (ti1 < ti)
+        {
+            ti1 += duration;
+        }
+
+        let tmti_1 = (time - ti_1);
+        let tmti_2 = (time - ti_2);
+        let dL0 = ti - ti_1;
+        let dL1_1 = ti - ti_2;
+        let dL1_2 = ti1 - ti_1;
+
+        let L0 = dL0 !== 0 ? tmti_1 / dL0 : 0;
+        let L1_1 = dL1_1 !== 0 ? tmti_2 / dL1_1 : 0;
+        let L1_2 = dL1_2 !== 0 ? tmti_1 / dL1_2 : 0;
+
+        let ci_2 = (L1_1 + L0) - L0 * L1_1;
+        let ci = L0 * L1_2;
+        let ci_1 = ci_2 - ci;
+        ci_2 = 1 - ci_2;
+
+        for (let i = 0; i < curve.dimension; ++i)
+        {
+            value[i] = ci_2 * curve.controls[p1 + i] + ci_1 * curve.controls[p2 + i] + ci * curve.controls[p3 + i];
+        }
+    }
+    return value;
+};
+
+/**
+ * ag_horner1
+ *
+ * @param P
+ * @param deg
+ * @param s
+ * @returns {*}
+ */
+curve.ag_horner1 = function(P, deg, s)
+{
+    let h = P[deg];
+    while (--deg >= 0) h = (s * h) + P[deg];
+    return (h);
+};
+
+/**
+ * ag_zeroin2
+ *
+ * @param a
+ * @param b
+ * @param fa
+ * @param fb
+ * @param tol
+ * @param pars
+ * @returns {*}
+ */
+curve.ag_zeroin2 = function(a, b, fa, fb, tol, pars)
+{
+    let test;
+    let c, d, e, fc, del, m, machtol, p, q, r, s;
+
+    /* initialization */
+    machtol = 1.192092896e-07;
+    let label1 = true;
+
+    /* start iteration */
+    while (true)
+    {
+        if (label1)
+        {
+            c = a;
+            fc = fa;
+            d = b - a;
+            e = d;
+        }
+
+        if (Math.abs(fc) < Math.abs(fb))
+        {
+            a = b;
+            b = c;
+            c = a;
+            fa = fb;
+            fb = fc;
+            fc = fa;
+        }
+        label1 = false;
+
+        /* convergence test */
+        del = 2.0 * machtol * Math.abs(b) + 0.5 * tol;
+        m = 0.5 * (c - b);
+        test = ((Math.abs(m) > del) && (fb !== 0.0));
+        if (test)
+        {
+            if ((Math.abs(e) < del) || (Math.abs(fa) <= Math.abs(fb)))
+            {
+                /* bisection */
+                d = m;
+                e = d;
+            }
+            else
+            {
+                s = fb / fa;
+                if (a === c)
+                {
+                    /* linear interpolation */
+                    p = 2.0 * m * s;
+                    q = 1.0 - s;
+                }
+                else
+                {
+                    /* inverse quadratic interpolation */
+                    q = fa / fc;
+                    r = fb / fc;
+                    p = s * (2.0 * m * q * (q - r) - (b - a) * (r - 1.0));
+                    q = (q - 1.0) * (r - 1.0) * (s - 1.0);
+                }
+                /* adjust the sign */
+                if (p > 0.0) q = -q;
+                else p = -p;
+                /* check if interpolation is acceptable */
+                s = e;
+                e = d;
+                if ((2.0 * p < 3.0 * m * q - Math.abs(del * q)) && (p < Math.abs(0.5 * s * q)))
+                {
+                    d = p / q;
+                }
+                else
+                {
+                    d = m;
+                    e = d;
+                }
+            }
+            /* complete step */
+            a = b;
+            fa = fb;
+            if (Math.abs(d) > del) b += d;
+            else if (m > 0.0) b += del;
+            else b -= del;
+            fb = curve.ag_horner1(pars.p, pars.deg, b);
+            if (fb * (fc / Math.abs(fc)) > 0.0)
+            {
+                label1 = true;
+            }
+        }
+        else
+        {
+            break;
+        }
+    }
+    return (b);
+};
+
+/**
+ * ag_zeroin
+ *
+ * @param a
+ * @param b
+ * @param tol
+ * @param pars
+ * @returns {*}
+ */
+curve.ag_zeroin = function(a, b, tol, pars)
+{
+    let fa, fb;
+
+    fa = curve.ag_horner1(pars.p, pars.deg, a);
+    if (Math.abs(fa) < 1.192092896e-07) return (a);
+
+    fb = curve.ag_horner1(pars.p, pars.deg, b);
+    if (Math.abs(fb) < 1.192092896e-07) return (b);
+
+    return (curve.ag_zeroin2(a, b, fa, fb, tol, pars));
+};
+
+/**
+ * polyZeroes
+ *
+ * @param Poly
+ * @param deg
+ * @param a
+ * @param a_closed
+ * @param b
+ * @param b_closed
+ * @param Roots
+ * @returns {*}
+ */
+curve.polyZeroes = function(Poly, deg, a, a_closed, b, b_closed, Roots)
+{
+    let i, left_ok, right_ok, nr, ndr, skip;
+
+    let e, f, s, pe, ps, tol, p, p_x = new Array(22),
+        d, d_x = new Array(22),
+        dr, dr_x = new Array(22);
+
+    let ply = {
+        p: [],
+        deg: 0
+    };
+
+    e = pe = 0.0;
+    f = 0.0;
+
+    for (i = 0; i < deg + 1; ++i)
+    {
+        f += Math.abs(Poly[i]);
+    }
+    tol = (Math.abs(a) + Math.abs(b)) * (deg + 1) * 1.192092896e-07;
+
+    /* Zero polynomial to tolerance? */
+    if (f <= tol) return (-1);
+
+    p = p_x;
+    d = d_x;
+    dr = dr_x;
+    for (i = 0; i < deg + 1; ++i)
+    {
+        p[i] = 1.0 / f * Poly[i];
+    }
+
+    /* determine true degree */
+    while (Math.abs(p[deg]) < tol) deg--;
+
+    /* Identically zero poly already caught so constant fn !== 0 */
+    nr = 0;
+    if (deg === 0) return (nr);
+
+    /* check for linear case */
+    if (deg === 1)
+    {
+        Roots[0] = -p[0] / p[1];
+        left_ok = (a_closed) ? (a < Roots[0] + tol) : (a < Roots[0] - tol);
+        right_ok = (b_closed) ? (b > Roots[0] - tol) : (b > Roots[0] + tol);
+        nr = (left_ok && right_ok) ? 1 : 0;
+        if (nr)
+        {
+            if (a_closed && Roots[0] < a) Roots[0] = a;
+            else if (b_closed && Roots[0] > b) Roots[0] = b;
+        }
+        return nr;
+    }
+    /* handle non-linear case */
+    else
+    {
+        ply.p = p;
+        ply.deg = deg;
+
+        /* compute derivative */
+        for (i = 1; i <= deg; i++) d[i - 1] = i * p[i];
+
+        /* find roots of derivative */
+        ndr = curve.polyZeroes(d, deg - 1, a, 0, b, 0, dr);
+        if (ndr.length === 0) return (0);
+
+        /* find roots between roots of the derivative */
+        for (i = skip = 0; i <= ndr; i++)
+        {
+            if (nr > deg) return (nr);
+            if (i === 0)
+            {
+                s = a;
+                ps = curve.ag_horner1(p, deg, s);
+                if (Math.abs(ps) <= tol && a_closed) Roots[nr++] = a;
+            }
+            else
+            {
+                s = e;
+                ps = pe;
+            }
+            if (i === ndr)
+            {
+                e = b;
+                skip = 0;
+            }
+            else e = dr[i];
+            pe = curve.ag_horner1(p, deg, e);
+            if (skip) skip = 0;
+            else
+            {
+                if (Math.abs(pe) < tol)
+                {
+                    if (i !== ndr || b_closed)
+                    {
+                        Roots[nr++] = e;
+                        skip = 1;
+                    }
+                }
+                else if ((ps < 0 && pe > 0) || (ps > 0 && pe < 0))
+                {
+                    Roots[nr++] = curve.ag_zeroin(s, e, 0.0, ply);
+                    if ((nr > 1) && Roots[nr - 2] >= Roots[nr - 1] - tol)
+                    {
+                        Roots[nr - 2] = (Roots[nr - 2] + Roots[nr - 1]) * 0.5;
+                        nr--;
+                    }
+                }
+            }
+        }
+    }
+
+    return (nr);
+};
+
+export const {
+    evaluate,
+    ag_horner1,
+    ag_zeroin2,
+    ag_zeroin,
+    polyZeroes
+} = curve;

package/src/d3d/dxgiFormats.js

@@ -0,0 +1,46 @@
+/**
+ * Small DXGI_FORMAT numeric mirror for formats currently needed by readers.
+ *
+ * Values match the public DXGI_FORMAT enum.
+ */
+export const DxgiFormat = Object.freeze({
+    UNKNOWN: 0,
+    R32G32B32A32_FLOAT: 2,
+    R32G32_FLOAT: 16,
+    R32_FLOAT: 41,
+    R16G16B16A16_FLOAT: 10,
+    R8G8_UNORM: 49,
+    R8G8B8A8_UNORM: 28,
+    R8G8B8A8_UNORM_SRGB: 29,
+    R16_FLOAT: 54,
+    R8_UNORM: 61,
+    BC1_UNORM: 71,
+    BC1_UNORM_SRGB: 72,
+    BC2_UNORM: 74,
+    BC2_UNORM_SRGB: 75,
+    BC3_UNORM: 77,
+    BC3_UNORM_SRGB: 78,
+    BC4_UNORM: 80,
+    BC4_SNORM: 81,
+    BC5_UNORM: 83,
+    BC5_SNORM: 84,
+    B8G8R8A8_UNORM: 87,
+    B8G8R8X8_UNORM: 88,
+    B8G8R8A8_UNORM_SRGB: 91,
+    B8G8R8X8_UNORM_SRGB: 93,
+    BC6H_UF16: 95,
+    BC6H_SF16: 96,
+    BC7_UNORM: 98,
+    BC7_UNORM_SRGB: 99
+});
+
+/**
+ * Normalize a DXGI numeric value.
+ *
+ * @param {number} value Candidate DXGI value.
+ * @returns {number} Integer DXGI value or UNKNOWN.
+ */
+export function normalizeDxgiFormat(value)
+{
+    return Number.isInteger(value) ? value : DxgiFormat.UNKNOWN;
+}

package/src/d3d/index.js

@@ -0,0 +1,2 @@
+export * from "./dxgiFormats.js";
+export * from "./primitiveTopology.js";

package/src/d3d/primitiveTopology.js

@@ -0,0 +1,11 @@
+/**
+ * D3D primitive topology numeric mirror for common geometry payloads.
+ */
+export const D3dPrimitiveTopology = Object.freeze({
+    UNDEFINED: 0,
+    POINTLIST: 1,
+    LINELIST: 2,
+    LINESTRIP: 3,
+    TRIANGLELIST: 4,
+    TRIANGLESTRIP: 5
+});