@carbonenginejs/runtime-utils 0.1.1 → 0.1.3

package/src/tangent.js

@@ -1,288 +1,288 @@
-/**
- * Packed tangent-frame helpers for CarbonEngineJS/GR2-style mesh data.
- *
- * The packed-frame constants and decode/encode behavior are based on observed
- * Fenris Creations (CCP Games) shader behavior for EVE/Carbon packed tangent
- * frames. No shader source is included here.
- */
-
-import {
-    generateBiNormals,
-    generateNormals,
-    generateTangentFrames,
-    generateTangents
-} from "./mesh.js";
-import {
-    EPSILON,
-    clamp
-} from "./num.js";
-import {
-    cross,
-    dot,
-    length as vec3Length,
-    normalize
-} from "gl-matrix/esm/vec3.js";
-
-/** Full-turn float32 constant used by the CCP tangent-frame shader. */
-export const TANGENT_TAU = 6.28318548;
-
-/** Half-turn float32 constant used by the CCP tangent-frame shader. */
-export const TANGENT_PI = 3.14159274;
-
-const
-    TAU = TANGENT_TAU,
-    PI = TANGENT_PI,
-    POLAR_EPSILON = 1e-6;
-
-/**
- * Packed UNorm sentinel used for vertices with no authored tangent frame.
- *
- * @type {number[]}
- */
-export const NULL_TANGENT_UNORM = Object.freeze([ 0, 1, 0, 1 ]);
-
-/**
- * Test whether a packed tangent payload is the null-frame sentinel.
- *
- * @param {ArrayLike<number>} u Four UNorm values.
- * @returns {boolean} Whether the payload marks a missing authored frame.
- */
-export function isNullTangent(u)
-{
-    const
-        e1 = u[1],
-        e3 = u[3];
-
-    return (e1 <= 1e-3 || e1 >= 1 - 1e-3) && (e3 <= 1e-3 || e3 >= 1 - 1e-3);
-}
-
-const
-    scratchT = new Float64Array(3),
-    scratchB = new Float64Array(3),
-    scratchN = new Float64Array(3);
-
-function decodeTangentFrameInto(u0, u1, u2, u3, outT, outB, outN)
-{
-    const
-        a0 = u0 * TAU - PI,
-        a1 = u1 * TAU - PI,
-        a2 = u2 * TAU - PI,
-        a3 = u3 * TAU - PI,
-        s1 = Math.abs(Math.sin(a1)),
-        s3 = Math.abs(Math.sin(a3));
-
-    outT[0] = s1 * Math.cos(a0);
-    outT[1] = s1 * Math.sin(a0);
-    outT[2] = Math.cos(a1);
-
-    outB[0] = s3 * Math.cos(a2);
-    outB[1] = s3 * Math.sin(a2);
-    outB[2] = Math.cos(a3);
-
-    const sign = (a1 > 0 && a3 > 0) ? 1 : -1;
-    outN[0] = (outT[1] * outB[2] - outT[2] * outB[1]) * sign;
-    outN[1] = (outT[2] * outB[0] - outT[0] * outB[2]) * sign;
-    outN[2] = (outT[0] * outB[1] - outT[1] * outB[0]) * sign;
-
-    return s1 < 1e-6 && s3 < 1e-6;
-}
-
-/**
- * Decode a packed tangent frame.
- *
- * @param {ArrayLike<number>} u Four UNorm values in `[0, 1]`.
- * @returns {{T: number[], B: number[], N: number[], null: boolean}} Decoded basis.
- */
-export function decodeTangentFrame(u)
-{
-    const isNull = decodeTangentFrameInto(u[0], u[1], u[2], u[3], scratchT, scratchB, scratchN);
-    return { T: Array.from(scratchT), B: Array.from(scratchB), N: Array.from(scratchN), null: isNull };
-}
-
-/**
- * Encode a tangent frame back to four UNorm angles.
- *
- * @param {ArrayLike<number>} T Unit tangent.
- * @param {ArrayLike<number>} B Unit binormal.
- * @param {ArrayLike<number>} [N] Unit normal; only handedness is used.
- * @returns {number[]} Four UNorm values in `[0, 1]`.
- */
-export function encodeTangentFrame(T, B, N)
-{
-    let a0 = Math.atan2(T[1], T[0]),
-        a1 = Math.acos(clamp(T[2], -1, 1));
-
-    const a2 = Math.atan2(B[1], B[0]);
-    let a3 = Math.acos(clamp(B[2], -1, 1));
-
-    const negativeHandedness = N && dot(N, cross([ 0, 0, 0 ], T, B)) < 0;
-    if (negativeHandedness)
-    {
-        a1 = a1 === 0 ? -POLAR_EPSILON : -a1;
-    }
-    else
-    {
-        if (a1 === 0) a1 = POLAR_EPSILON;
-        if (a3 === 0) a3 = POLAR_EPSILON;
-    }
-
-    const enc = angle => clamp((angle + PI) / TAU, 0, 1);
-    return [ enc(a0), enc(a1), enc(a2), enc(a3) ];
-}
-
-function vertexCount(mesh)
-{
-    const p = mesh.vertex && mesh.vertex.position;
-    return p ? (p.length / 3) | 0 : 0;
-}
-
-/**
- * Is this shared JSON mesh's tangent frame packed?
- *
- * @param {object} mesh Shared JSON mesh.
- * @returns {boolean} Whether the mesh has packed tangent frames.
- */
-export function isPacked(mesh)
-{
-    const v = mesh.vertex;
-    if (!v || !v.tangent || !v.tangent.length) return false;
-
-    const n = vertexCount(mesh);
-    if (!n) return false;
-
-    const
-        comps = v.tangent.length / n,
-        empty = value => !value || value.length === 0;
-
-    return comps === 4 && empty(v.normal) && empty(v.binormal);
-}
-
-/**
- * Unpack a packed shared JSON mesh in place.
- *
- * @param {object} mesh Shared JSON mesh to mutate.
- * @returns {boolean} Whether unpacking happened.
- */
-export function unpackMeshTangents(mesh)
-{
-    if (!isPacked(mesh)) return false;
-
-    const
-        v = mesh.vertex,
-        n = vertexCount(mesh),
-        src = v.tangent,
-        normal = new Array(n * 3),
-        tangent = new Array(n * 3),
-        binormal = new Array(n * 3);
-
-    for (let i = 0; i < n; i++)
-    {
-        const
-            s = i * 4,
-            o = i * 3,
-            isNull = decodeTangentFrameInto(src[s], src[s + 1], src[s + 2], src[s + 3], scratchT, scratchB, scratchN);
-
-        if (isNull)
-        {
-            normal[o] = normal[o + 1] = normal[o + 2] = 0;
-            tangent[o] = tangent[o + 1] = tangent[o + 2] = 0;
-            binormal[o] = binormal[o + 1] = binormal[o + 2] = 0;
-        }
-        else
-        {
-            normal[o] = scratchN[0];
-            normal[o + 1] = scratchN[1];
-            normal[o + 2] = scratchN[2];
-            tangent[o] = scratchT[0];
-            tangent[o + 1] = scratchT[1];
-            tangent[o + 2] = scratchT[2];
-            binormal[o] = scratchB[0];
-            binormal[o + 1] = scratchB[1];
-            binormal[o + 2] = scratchB[2];
-        }
-    }
-
-    v.normal = normal;
-    v.tangent = tangent;
-    v.binormal = binormal;
-    return true;
-}
-
-/**
- * Pack explicit tangent frames into GR2-style four-component tangent data.
- *
- * @param {ArrayLike<number>} normals Flat xyz normals.
- * @param {ArrayLike<number>} tangents Flat xyz tangents.
- * @param {ArrayLike<number>} binormals Flat xyz binormals.
- * @returns {number[]} Flat xyzw packed tangent-frame values.
- */
-export function packTangentFrames(normals, tangents, binormals)
-{
-    if (normals.length !== tangents.length ||
-        normals.length !== binormals.length ||
-        normals.length % 3 !== 0)
-    {
-        throw new Error("packTangentFrames requires matching complete xyz channels");
-    }
-
-    const packed = new Array((normals.length / 3) * 4);
-    for (let i = 0, o = 0; i < normals.length; i += 3, o += 4)
-    {
-        const components = [
-            normals[i], normals[i + 1], normals[i + 2],
-            tangents[i], tangents[i + 1], tangents[i + 2],
-            binormals[i], binormals[i + 1], binormals[i + 2]
-        ];
-        if (!components.every(Number.isFinite))
-        {
-            throw new Error(`packTangentFrames received non-finite data at vertex ${i / 3}`);
-        }
-
-        const
-            normal = normalize([ 0, 0, 0 ], components.slice(0, 3)),
-            tangent = normalize([ 0, 0, 0 ], components.slice(3, 6)),
-            binormal = normalize([ 0, 0, 0 ], components.slice(6, 9)),
-            frameNormalLength = vec3Length(cross([ 0, 0, 0 ], tangent, binormal));
-
-        if (vec3Length(normal) <= EPSILON ||
-            vec3Length(tangent) <= EPSILON ||
-            vec3Length(binormal) <= EPSILON ||
-            frameNormalLength <= EPSILON)
-        {
-            packed[o] = NULL_TANGENT_UNORM[0];
-            packed[o + 1] = NULL_TANGENT_UNORM[1];
-            packed[o + 2] = NULL_TANGENT_UNORM[2];
-            packed[o + 3] = NULL_TANGENT_UNORM[3];
-            continue;
-        }
-
-        const encoded = encodeTangentFrame(tangent, binormal, normal);
-        packed[o] = encoded[0];
-        packed[o + 1] = encoded[1];
-        packed[o + 2] = encoded[2];
-        packed[o + 3] = encoded[3];
-    }
-
-    return packed;
-}
-
-export const tangent = Object.freeze({
-    TAU: TANGENT_TAU,
-    PI: TANGENT_PI,
-    NULL_TANGENT_UNORM,
-    isNull: isNullTangent,
-    isNullTangent,
-    decode: decodeTangentFrame,
-    decodeTangentFrame,
-    pack: encodeTangentFrame,
-    encode: encodeTangentFrame,
-    encodeTangentFrame,
-    packTangentFrames,
-    unpack: unpackMeshTangents,
-    unpackMeshTangents,
-    isPacked,
-    generateNormals,
-    generateTangents,
-    generateTangentFrames,
-    generateBiNormals
-});
+/**
+ * Packed tangent-frame helpers for CarbonEngineJS/GR2-style mesh data.
+ *
+ * The packed-frame constants and decode/encode behavior are based on observed
+ * Fenris Creations (CCP Games) shader behavior for EVE/Carbon packed tangent
+ * frames. No shader source is included here.
+ */
+
+import {
+    generateBiNormals,
+    generateNormals,
+    generateTangentFrames,
+    generateTangents
+} from "./mesh.js";
+import {
+    EPSILON,
+    clamp
+} from "./num.js";
+import {
+    cross,
+    dot,
+    length as vec3Length,
+    normalize
+} from "gl-matrix/esm/vec3.js";
+
+/** Full-turn float32 constant used by the CCP tangent-frame shader. */
+export const TANGENT_TAU = 6.28318548;
+
+/** Half-turn float32 constant used by the CCP tangent-frame shader. */
+export const TANGENT_PI = 3.14159274;
+
+const
+    TAU = TANGENT_TAU,
+    PI = TANGENT_PI,
+    POLAR_EPSILON = 1e-6;
+
+/**
+ * Packed UNorm sentinel used for vertices with no authored tangent frame.
+ *
+ * @type {number[]}
+ */
+export const NULL_TANGENT_UNORM = Object.freeze([ 0, 1, 0, 1 ]);
+
+/**
+ * Test whether a packed tangent payload is the null-frame sentinel.
+ *
+ * @param {ArrayLike<number>} u Four UNorm values.
+ * @returns {boolean} Whether the payload marks a missing authored frame.
+ */
+export function isNullTangent(u)
+{
+    const
+        e1 = u[1],
+        e3 = u[3];
+
+    return (e1 <= 1e-3 || e1 >= 1 - 1e-3) && (e3 <= 1e-3 || e3 >= 1 - 1e-3);
+}
+
+const
+    scratchT = new Float64Array(3),
+    scratchB = new Float64Array(3),
+    scratchN = new Float64Array(3);
+
+function decodeTangentFrameInto(u0, u1, u2, u3, outT, outB, outN)
+{
+    const
+        a0 = u0 * TAU - PI,
+        a1 = u1 * TAU - PI,
+        a2 = u2 * TAU - PI,
+        a3 = u3 * TAU - PI,
+        s1 = Math.abs(Math.sin(a1)),
+        s3 = Math.abs(Math.sin(a3));
+
+    outT[0] = s1 * Math.cos(a0);
+    outT[1] = s1 * Math.sin(a0);
+    outT[2] = Math.cos(a1);
+
+    outB[0] = s3 * Math.cos(a2);
+    outB[1] = s3 * Math.sin(a2);
+    outB[2] = Math.cos(a3);
+
+    const sign = (a1 > 0 && a3 > 0) ? 1 : -1;
+    outN[0] = (outT[1] * outB[2] - outT[2] * outB[1]) * sign;
+    outN[1] = (outT[2] * outB[0] - outT[0] * outB[2]) * sign;
+    outN[2] = (outT[0] * outB[1] - outT[1] * outB[0]) * sign;
+
+    return s1 < 1e-6 && s3 < 1e-6;
+}
+
+/**
+ * Decode a packed tangent frame.
+ *
+ * @param {ArrayLike<number>} u Four UNorm values in `[0, 1]`.
+ * @returns {{T: number[], B: number[], N: number[], null: boolean}} Decoded basis.
+ */
+export function decodeTangentFrame(u)
+{
+    const isNull = decodeTangentFrameInto(u[0], u[1], u[2], u[3], scratchT, scratchB, scratchN);
+    return { T: Array.from(scratchT), B: Array.from(scratchB), N: Array.from(scratchN), null: isNull };
+}
+
+/**
+ * Encode a tangent frame back to four UNorm angles.
+ *
+ * @param {ArrayLike<number>} T Unit tangent.
+ * @param {ArrayLike<number>} B Unit binormal.
+ * @param {ArrayLike<number>} [N] Unit normal; only handedness is used.
+ * @returns {number[]} Four UNorm values in `[0, 1]`.
+ */
+export function encodeTangentFrame(T, B, N)
+{
+    let a0 = Math.atan2(T[1], T[0]),
+        a1 = Math.acos(clamp(T[2], -1, 1));
+
+    const a2 = Math.atan2(B[1], B[0]);
+    let a3 = Math.acos(clamp(B[2], -1, 1));
+
+    const negativeHandedness = N && dot(N, cross([ 0, 0, 0 ], T, B)) < 0;
+    if (negativeHandedness)
+    {
+        a1 = a1 === 0 ? -POLAR_EPSILON : -a1;
+    }
+    else
+    {
+        if (a1 === 0) a1 = POLAR_EPSILON;
+        if (a3 === 0) a3 = POLAR_EPSILON;
+    }
+
+    const enc = angle => clamp((angle + PI) / TAU, 0, 1);
+    return [ enc(a0), enc(a1), enc(a2), enc(a3) ];
+}
+
+function vertexCount(mesh)
+{
+    const p = mesh.vertex && mesh.vertex.position;
+    return p ? (p.length / 3) | 0 : 0;
+}
+
+/**
+ * Is this shared JSON mesh's tangent frame packed?
+ *
+ * @param {object} mesh Shared JSON mesh.
+ * @returns {boolean} Whether the mesh has packed tangent frames.
+ */
+export function isPacked(mesh)
+{
+    const v = mesh.vertex;
+    if (!v || !v.tangent || !v.tangent.length) return false;
+
+    const n = vertexCount(mesh);
+    if (!n) return false;
+
+    const
+        comps = v.tangent.length / n,
+        empty = value => !value || value.length === 0;
+
+    return comps === 4 && empty(v.normal) && empty(v.binormal);
+}
+
+/**
+ * Unpack a packed shared JSON mesh in place.
+ *
+ * @param {object} mesh Shared JSON mesh to mutate.
+ * @returns {boolean} Whether unpacking happened.
+ */
+export function unpackMeshTangents(mesh)
+{
+    if (!isPacked(mesh)) return false;
+
+    const
+        v = mesh.vertex,
+        n = vertexCount(mesh),
+        src = v.tangent,
+        normal = new Array(n * 3),
+        tangent = new Array(n * 3),
+        binormal = new Array(n * 3);
+
+    for (let i = 0; i < n; i++)
+    {
+        const
+            s = i * 4,
+            o = i * 3,
+            isNull = decodeTangentFrameInto(src[s], src[s + 1], src[s + 2], src[s + 3], scratchT, scratchB, scratchN);
+
+        if (isNull)
+        {
+            normal[o] = normal[o + 1] = normal[o + 2] = 0;
+            tangent[o] = tangent[o + 1] = tangent[o + 2] = 0;
+            binormal[o] = binormal[o + 1] = binormal[o + 2] = 0;
+        }
+        else
+        {
+            normal[o] = scratchN[0];
+            normal[o + 1] = scratchN[1];
+            normal[o + 2] = scratchN[2];
+            tangent[o] = scratchT[0];
+            tangent[o + 1] = scratchT[1];
+            tangent[o + 2] = scratchT[2];
+            binormal[o] = scratchB[0];
+            binormal[o + 1] = scratchB[1];
+            binormal[o + 2] = scratchB[2];
+        }
+    }
+
+    v.normal = normal;
+    v.tangent = tangent;
+    v.binormal = binormal;
+    return true;
+}
+
+/**
+ * Pack explicit tangent frames into GR2-style four-component tangent data.
+ *
+ * @param {ArrayLike<number>} normals Flat xyz normals.
+ * @param {ArrayLike<number>} tangents Flat xyz tangents.
+ * @param {ArrayLike<number>} binormals Flat xyz binormals.
+ * @returns {number[]} Flat xyzw packed tangent-frame values.
+ */
+export function packTangentFrames(normals, tangents, binormals)
+{
+    if (normals.length !== tangents.length ||
+        normals.length !== binormals.length ||
+        normals.length % 3 !== 0)
+    {
+        throw new Error("packTangentFrames requires matching complete xyz channels");
+    }
+
+    const packed = new Array((normals.length / 3) * 4);
+    for (let i = 0, o = 0; i < normals.length; i += 3, o += 4)
+    {
+        const components = [
+            normals[i], normals[i + 1], normals[i + 2],
+            tangents[i], tangents[i + 1], tangents[i + 2],
+            binormals[i], binormals[i + 1], binormals[i + 2]
+        ];
+        if (!components.every(Number.isFinite))
+        {
+            throw new Error(`packTangentFrames received non-finite data at vertex ${i / 3}`);
+        }
+
+        const
+            normal = normalize([ 0, 0, 0 ], components.slice(0, 3)),
+            tangent = normalize([ 0, 0, 0 ], components.slice(3, 6)),
+            binormal = normalize([ 0, 0, 0 ], components.slice(6, 9)),
+            frameNormalLength = vec3Length(cross([ 0, 0, 0 ], tangent, binormal));
+
+        if (vec3Length(normal) <= EPSILON ||
+            vec3Length(tangent) <= EPSILON ||
+            vec3Length(binormal) <= EPSILON ||
+            frameNormalLength <= EPSILON)
+        {
+            packed[o] = NULL_TANGENT_UNORM[0];
+            packed[o + 1] = NULL_TANGENT_UNORM[1];
+            packed[o + 2] = NULL_TANGENT_UNORM[2];
+            packed[o + 3] = NULL_TANGENT_UNORM[3];
+            continue;
+        }
+
+        const encoded = encodeTangentFrame(tangent, binormal, normal);
+        packed[o] = encoded[0];
+        packed[o + 1] = encoded[1];
+        packed[o + 2] = encoded[2];
+        packed[o + 3] = encoded[3];
+    }
+
+    return packed;
+}
+
+export const tangent = Object.freeze({
+    TAU: TANGENT_TAU,
+    PI: TANGENT_PI,
+    NULL_TANGENT_UNORM,
+    isNull: isNullTangent,
+    isNullTangent,
+    decode: decodeTangentFrame,
+    decodeTangentFrame,
+    pack: encodeTangentFrame,
+    encode: encodeTangentFrame,
+    encodeTangentFrame,
+    packTangentFrames,
+    unpack: unpackMeshTangents,
+    unpackMeshTangents,
+    isPacked,
+    generateNormals,
+    generateTangents,
+    generateTangentFrames,
+    generateBiNormals
+});

package/src/text.js

@@ -1,40 +1,40 @@
-import { asUint8Array } from "./bytes.js";
-
-/** Encodes a value as UTF-8 without importing a platform-specific module. */
-export function encodeUtf8(value)
-{
-    const TextEncoderClass = globalThis.TextEncoder;
-
-    if (typeof TextEncoderClass !== "function")
-    {
-        throw unsupportedTextCodec("TextEncoder");
-    }
-
-    return new TextEncoderClass().encode(String(value));
-}
-
-/** Decodes supported byte input as UTF-8. */
-export function decodeUtf8(value, options = {})
-{
-    const TextDecoderClass = globalThis.TextDecoder;
-
-    if (typeof TextDecoderClass !== "function")
-    {
-        throw unsupportedTextCodec("TextDecoder");
-    }
-
-    const decoder = new TextDecoderClass("utf-8", {
-        fatal: Boolean(options.fatal),
-        ignoreBOM: Boolean(options.ignoreBOM)
-    });
-
-    return decoder.decode(asUint8Array(value, "UTF-8 input"));
-}
-
-function unsupportedTextCodec(name)
-{
-    const error = new Error(`${name} is unavailable in this environment.`);
-
-    error.code = "CJS_TEXT_CODEC_UNSUPPORTED";
-    return error;
-}
+import { asUint8Array } from "./bytes.js";
+
+/** Encodes a value as UTF-8 without importing a platform-specific module. */
+export function encodeUtf8(value)
+{
+    const TextEncoderClass = globalThis.TextEncoder;
+
+    if (typeof TextEncoderClass !== "function")
+    {
+        throw unsupportedTextCodec("TextEncoder");
+    }
+
+    return new TextEncoderClass().encode(String(value));
+}
+
+/** Decodes supported byte input as UTF-8. */
+export function decodeUtf8(value, options = {})
+{
+    const TextDecoderClass = globalThis.TextDecoder;
+
+    if (typeof TextDecoderClass !== "function")
+    {
+        throw unsupportedTextCodec("TextDecoder");
+    }
+
+    const decoder = new TextDecoderClass("utf-8", {
+        fatal: Boolean(options.fatal),
+        ignoreBOM: Boolean(options.ignoreBOM)
+    });
+
+    return decoder.decode(asUint8Array(value, "UTF-8 input"));
+}
+
+function unsupportedTextCodec(name)
+{
+    const error = new Error(`${name} is unavailable in this environment.`);
+
+    error.code = "CJS_TEXT_CODEC_UNSUPPORTED";
+    return error;
+}