@carbonenginejs/runtime-utils 0.1.0

package/src/geometry/sphere.js

@@ -0,0 +1,123 @@
+import { vec3 } from "../vec3.js";
+import { toJSON } from "./json.js";
+
+/**
+ * Creates a sphere
+ * @author Three.js converted
+ *
+ *
+ **/
+export function createSphere(options = {})
+{
+
+    let {
+        radius = 1,
+        widthSegments = 32,
+        heightSegments = 16,
+        phiStart = 0,
+        phiLength = Math.PI * 2,
+        thetaStart = 0,
+        thetaLength = Math.PI
+    } = options;
+
+    if (![ radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength ].every(Number.isFinite) ||
+        radius <= 0 ||
+        phiLength <= 0 ||
+        thetaLength <= 0)
+    {
+        throw new Error("Invalid sphere dimensions");
+    }
+
+    widthSegments = Math.max(3, Math.floor(widthSegments));
+    heightSegments = Math.max(2, Math.floor(heightSegments));
+
+    const
+        thetaEnd = Math.min(thetaStart + thetaLength, Math.PI),
+        grid = [],
+        vertex = vec3.alloc(),
+        normal = vec3.alloc();
+
+    let index = 0;
+
+    // buffers
+    const
+        indices = [],
+        vertices = [],
+        normals = [],
+        uvs = [];
+
+    // generate vertices, normals and uvs
+    for (let iy = 0; iy <= heightSegments; iy++)
+    {
+        const
+            verticesRow = [],
+            v = iy / heightSegments;
+
+        // special case for the poles
+        let uOffset = 0;
+        if (iy === 0 && thetaStart === 0)
+        {
+            uOffset = 0.5 / widthSegments;
+        }
+        else if (iy === heightSegments && thetaEnd === Math.PI)
+        {
+            uOffset = -0.5 / widthSegments;
+        }
+
+        for (let ix = 0; ix <= widthSegments; ix++)
+        {
+            const u = ix / widthSegments;
+
+            // vertex
+            vertex[0] = -radius * Math.cos(phiStart + u * phiLength) * Math.sin(thetaStart + v * thetaLength);
+            vertex[1] = radius * Math.cos(thetaStart + v * thetaLength);
+            vertex[2] = radius * Math.sin(phiStart + u * phiLength) * Math.sin(thetaStart + v * thetaLength);
+            vertices.push(vertex[0], vertex[1], vertex[2]);
+
+            // normal
+            vec3.copy(normal, vertex);
+            vec3.normalize(normal, normal);
+            normals.push(normal[0], normal[1], normal[2]);
+
+            // uv
+            uvs.push(u + uOffset, 1 - v);
+            verticesRow.push(index++);
+        }
+
+        grid.push(verticesRow);
+    }
+
+    // indices
+    for (let iy = 0; iy < heightSegments; iy++)
+    {
+        for (let ix = 0; ix < widthSegments; ix++)
+        {
+            const
+                a = grid[iy][ix + 1],
+                b = grid[iy][ix],
+                c = grid[iy + 1][ix],
+                d = grid[iy + 1][ix + 1];
+
+            if (iy !== 0 || thetaStart > 0) indices.push(a, b, d);
+            if (iy !== heightSegments - 1 || thetaEnd < Math.PI) indices.push(b, c, d);
+        }
+    }
+
+    vec3.unalloc(vertex);
+    vec3.unalloc(normal);
+
+    const result = toJSON(indices, vertices, uvs, normals);
+    result.factory = createSphere;
+    result.options = {
+        radius,
+        widthSegments,
+        heightSegments,
+        phiStart,
+        phiLength,
+        thetaStart,
+        thetaLength
+    };
+    result.shape = { factory: result.factory, options: result.options };
+
+    return result;
+}

package/src/geometry/torus.js

@@ -0,0 +1,96 @@
+import { toJSON } from "./json.js";
+import { vec3 } from "../vec3.js";
+
+
+export function createTorus(options = {})
+{
+    let {
+        radius = 1,
+        tube = 0.4,
+        radialSegments = 12,
+        tubularSegments = 49,
+        arc = Math.PI * 2
+    } = options;
+
+    if (![ radius, tube, radialSegments, tubularSegments, arc ].every(Number.isFinite) ||
+        radius <= 0 ||
+        tube <= 0 ||
+        arc === 0)
+    {
+        throw new Error("Invalid torus dimensions");
+    }
+
+    radialSegments = Math.max(3, Math.floor(Number.isFinite(radialSegments) ? radialSegments : 12));
+    tubularSegments = Math.max(3, Math.floor(Number.isFinite(tubularSegments) ? tubularSegments : 49));
+
+    const
+        indices = [],
+        positions = [],
+        uvs = [],
+        normals = [];
+
+    const
+        center = vec3.alloc(),
+        vertex = vec3.alloc(),
+        normal = vec3.alloc();
+
+    // generate vertices, normals and uvs
+    for (let j = 0; j <= radialSegments; j++)
+    {
+        for (let i = 0; i <= tubularSegments; i++)
+        {
+            const
+                u = i / tubularSegments * arc,
+                v = j / radialSegments * Math.PI * 2;
+
+            // vertex
+            vertex[0] = (radius + tube * Math.cos(v)) * Math.cos(u);
+            vertex[1] = (radius + tube * Math.cos(v)) * Math.sin(u);
+            vertex[2] = tube * Math.sin(v);
+            positions.push(vertex[0], vertex[1], vertex[2]);
+
+            // normal
+            center[0] = radius * Math.cos(u);
+            center[1] = radius * Math.sin(u);
+            vec3.subtract(normal, vertex, center);
+            vec3.normalize(normal, normal);
+            normals.push(normal[0], normal[1], normal[2]);
+
+            // uv
+            uvs.push(i / tubularSegments);
+            uvs.push(j / radialSegments);
+        }
+    }
+
+    vec3.unalloc(center);
+    vec3.unalloc(vertex);
+    vec3.unalloc(normal);
+
+    // generate indices
+    for (let j = 1; j <= radialSegments; j++)
+    {
+        for (let i = 1; i <= tubularSegments; i++)
+        {
+            // indices
+            const
+                a = (tubularSegments + 1) * j + i - 1,
+                b = (tubularSegments + 1) * (j - 1) + i - 1,
+                c = (tubularSegments + 1) * (j - 1) + i,
+                d = (tubularSegments + 1) * j + i;
+            // faces
+            indices.push(a, b, d);
+            indices.push(b, c, d);
+        }
+    }
+
+    const result = toJSON(indices, positions, uvs, normals);
+    result.factory = createTorus;
+    result.options = {
+        radius,
+        tube,
+        radialSegments,
+        tubularSegments,
+        arc
+    };
+    return result;
+}

package/src/graphics/colorSpaces.js

@@ -0,0 +1,22 @@
+/**
+ * Canonical color space tokens for decoded image/texture payloads.
+ */
+export const ColorSpace = Object.freeze({
+    UNKNOWN: "unknown",
+    LINEAR: "linear",
+    SRGB: "srgb",
+    DISPLAY_P3: "display-p3",
+    REC709: "rec709",
+    REC2020: "rec2020"
+});
+
+/**
+ * Normalize a color space token.
+ *
+ * @param {string} colorSpace Color space token.
+ * @returns {string} Canonical lowercase token or unknown.
+ */
+export function normalizeColorSpace(colorSpace)
+{
+    return colorSpace ? String(colorSpace).trim().toLowerCase() : ColorSpace.UNKNOWN;
+}

package/src/graphics/index.js

@@ -0,0 +1,4 @@
+export * from "./pixelFormats.js";
+export * from "./colorSpaces.js";
+export * from "./textureDimensions.js";
+export * from "./trinityEnums.js";

package/src/graphics/pixelFormats.js

@@ -0,0 +1,158 @@
+/**
+ * Canonical GPU-free pixel format names used by decoded images and textures.
+ */
+export const PixelFormat = Object.freeze({
+    UNKNOWN: "unknown",
+
+    R8_UNORM: "r8unorm",
+    RG8_UNORM: "rg8unorm",
+    RGB8_UNORM: "rgb8unorm",
+    RGBA8_UNORM: "rgba8unorm",
+    BGRA8_UNORM: "bgra8unorm",
+    BGRX8_UNORM: "bgrx8unorm",
+    RGBA8_UNORM_SRGB: "rgba8unorm-srgb",
+    BGRA8_UNORM_SRGB: "bgra8unorm-srgb",
+    BGRX8_UNORM_SRGB: "bgrx8unorm-srgb",
+
+    R16_UINT: "r16uint",
+    R16_FLOAT: "r16float",
+    RG16_FLOAT: "rg16float",
+    RGBA16_FLOAT: "rgba16float",
+
+    R32_UINT: "r32uint",
+    R32_FLOAT: "r32float",
+    RG32_FLOAT: "rg32float",
+    RGBA32_FLOAT: "rgba32float",
+
+    BC1_RGBA_UNORM: "bc1-rgba-unorm",
+    BC1_RGBA_UNORM_SRGB: "bc1-rgba-unorm-srgb",
+    BC2_RGBA_UNORM: "bc2-rgba-unorm",
+    BC2_RGBA_UNORM_SRGB: "bc2-rgba-unorm-srgb",
+    BC3_RGBA_UNORM: "bc3-rgba-unorm",
+    BC3_RGBA_UNORM_SRGB: "bc3-rgba-unorm-srgb",
+    BC4_R_UNORM: "bc4-r-unorm",
+    BC4_R_SNORM: "bc4-r-snorm",
+    BC5_RG_UNORM: "bc5-rg-unorm",
+    BC5_RG_SNORM: "bc5-rg-snorm",
+    BC6H_RGB_UFLOAT: "bc6h-rgb-ufloat",
+    BC6H_RGB_FLOAT: "bc6h-rgb-float",
+    BC7_RGBA_UNORM: "bc7-rgba-unorm",
+    BC7_RGBA_UNORM_SRGB: "bc7-rgba-unorm-srgb"
+});
+
+const COMPRESSED_FORMATS = new Set([
+    PixelFormat.BC1_RGBA_UNORM,
+    PixelFormat.BC1_RGBA_UNORM_SRGB,
+    PixelFormat.BC2_RGBA_UNORM,
+    PixelFormat.BC2_RGBA_UNORM_SRGB,
+    PixelFormat.BC3_RGBA_UNORM,
+    PixelFormat.BC3_RGBA_UNORM_SRGB,
+    PixelFormat.BC4_R_UNORM,
+    PixelFormat.BC4_R_SNORM,
+    PixelFormat.BC5_RG_UNORM,
+    PixelFormat.BC5_RG_SNORM,
+    PixelFormat.BC6H_RGB_UFLOAT,
+    PixelFormat.BC6H_RGB_FLOAT,
+    PixelFormat.BC7_RGBA_UNORM,
+    PixelFormat.BC7_RGBA_UNORM_SRGB
+]);
+
+const BYTES_PER_BLOCK = Object.freeze({
+    [PixelFormat.R8_UNORM]: 1,
+    [PixelFormat.RG8_UNORM]: 2,
+    [PixelFormat.RGB8_UNORM]: 3,
+    [PixelFormat.RGBA8_UNORM]: 4,
+    [PixelFormat.BGRA8_UNORM]: 4,
+    [PixelFormat.BGRX8_UNORM]: 4,
+    [PixelFormat.RGBA8_UNORM_SRGB]: 4,
+    [PixelFormat.BGRA8_UNORM_SRGB]: 4,
+    [PixelFormat.BGRX8_UNORM_SRGB]: 4,
+    [PixelFormat.R16_UINT]: 2,
+    [PixelFormat.R16_FLOAT]: 2,
+    [PixelFormat.RG16_FLOAT]: 4,
+    [PixelFormat.RGBA16_FLOAT]: 8,
+    [PixelFormat.R32_UINT]: 4,
+    [PixelFormat.R32_FLOAT]: 4,
+    [PixelFormat.RG32_FLOAT]: 8,
+    [PixelFormat.RGBA32_FLOAT]: 16,
+    [PixelFormat.BC1_RGBA_UNORM]: 8,
+    [PixelFormat.BC1_RGBA_UNORM_SRGB]: 8,
+    [PixelFormat.BC2_RGBA_UNORM]: 16,
+    [PixelFormat.BC2_RGBA_UNORM_SRGB]: 16,
+    [PixelFormat.BC3_RGBA_UNORM]: 16,
+    [PixelFormat.BC3_RGBA_UNORM_SRGB]: 16,
+    [PixelFormat.BC4_R_UNORM]: 8,
+    [PixelFormat.BC4_R_SNORM]: 8,
+    [PixelFormat.BC5_RG_UNORM]: 16,
+    [PixelFormat.BC5_RG_SNORM]: 16,
+    [PixelFormat.BC6H_RGB_UFLOAT]: 16,
+    [PixelFormat.BC6H_RGB_FLOAT]: 16,
+    [PixelFormat.BC7_RGBA_UNORM]: 16,
+    [PixelFormat.BC7_RGBA_UNORM_SRGB]: 16
+});
+
+/**
+ * Normalize a pixel format token.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {string} Canonical lowercase token or empty string.
+ */
+export function normalizePixelFormat(format)
+{
+    return format ? String(format).trim().toLowerCase() : "";
+}
+
+/**
+ * Test whether a pixel format is block compressed.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {boolean} True when the format is compressed.
+ */
+export function isCompressedPixelFormat(format)
+{
+    return COMPRESSED_FORMATS.has(normalizePixelFormat(format));
+}
+
+/**
+ * Test whether a pixel format is marked as sRGB.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {boolean} True when the token ends with -srgb.
+ */
+export function isSrgbPixelFormat(format)
+{
+    return normalizePixelFormat(format).endsWith("-srgb");
+}
+
+/**
+ * Get bytes per texel or compressed block for a pixel format.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {number} Bytes per texel/block, or 0 when unknown.
+ */
+export function getPixelFormatBytesPerBlock(format)
+{
+    return BYTES_PER_BLOCK[normalizePixelFormat(format)] || 0;
+}
+
+/**
+ * Get the block width for a pixel format.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {number} Block width in texels.
+ */
+export function getPixelFormatBlockWidth(format)
+{
+    return isCompressedPixelFormat(format) ? 4 : 1;
+}
+
+/**
+ * Get the block height for a pixel format.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {number} Block height in texels.
+ */
+export function getPixelFormatBlockHeight(format)
+{
+    return isCompressedPixelFormat(format) ? 4 : 1;
+}

package/src/graphics/textureDimensions.js

@@ -0,0 +1,22 @@
+/**
+ * Canonical texture dimension tokens.
+ */
+export const TextureDimension = Object.freeze({
+    D1: "1d",
+    D2: "2d",
+    D3: "3d",
+    CUBE: "cube",
+    D2_ARRAY: "2d-array",
+    CUBE_ARRAY: "cube-array"
+});
+
+/**
+ * Normalize a texture dimension token.
+ *
+ * @param {string} dimension Texture dimension token.
+ * @returns {string} Canonical lowercase token.
+ */
+export function normalizeTextureDimension(dimension)
+{
+    return dimension ? String(dimension).trim().toLowerCase() : "";
+}

package/src/graphics/trinityEnums.js

@@ -0,0 +1,87 @@
+/** Global Trinity render-batch vocabulary from ITr2Renderable.h. */
+export const TriBatchType = Object.freeze({
+    TRIBATCHTYPE_OPAQUE: 0,
+    TRIBATCHTYPE_DECAL: 1,
+    TRIBATCHTYPE_TRANSPARENT: 2,
+    TRIBATCHTYPE_DEPTH: 3,
+    TRIBATCHTYPE_ADDITIVE: 4,
+    TRIBATCHTYPE_PICKING: 5,
+    TRIBATCHTYPE_MIRROR: 6,
+    TRIBATCHTYPE_DECALNORMAL: 7,
+    TRIBATCHTYPE_DEPTHNORMAL: 8,
+    TRIBATCHTYPE_OPAQUE_PREPASS: 9,
+    TRIBATCHTYPE_DECAL_PREPASS: 10,
+    TRIBATCHTYPE_GEOMETRY_ERASER: 11,
+    TRIBATCHTYPE_FLARE: 12,
+    TRIBATCHTYPE_DISTORTION: 13,
+    TRIBATCHTYPE_COUNT_OF_BATCH_TYPES: 14
+});
+
+/** Trinity standard render-state selector from Shader/Tr2EffectStateManager.h.
+ * Cross-package: runtime-trinity batches/accumulators and engine dispatch both
+ * key on it. Distinct from TriBatchType (batch bucket) — a render-state mode.
+ * Unscoped Carbon enum: values are sequential from RM_ANY = 0. */
+export const RenderingMode = Object.freeze({
+    RM_ANY: 0,
+    RM_OPAQUE: 1,
+    RM_DECAL: 2,
+    RM_DECAL_NO_DEPTH: 3,
+    RM_ALPHA: 4,
+    RM_ALPHA_ADDITIVE: 5,
+    RM_DEPTH_ONLY: 6,
+    RM_PICKING: 7,
+    RM_FULLSCREEN: 8,
+    RM_SPRITE2D: 9,
+    RM_CULL: 10,
+    RM_LIGHT: 11,
+    RM_ERASE: 12,
+    RM_PREPASS_COLOR: 13,
+    RM_COUNT: 14
+});
+
+/** Shared EVE entity reflection vocabulary from EntityComponents. */
+export const ReflectionMode = Object.freeze({
+    REFLECT_HIGH: 0,
+    REFLECT_MEDIUM_AND_HIGH: 1,
+    REFLECT_LOW_MEDIUM_HIGH: 2,
+    REFLECT_NEVER: 3
+});
+
+/** Trinity graph value-combination operator from blue/include/ITriConstants.h. */
+export const TriOperator = Object.freeze({
+    TRIOP_MULTIPLY: 0,
+    TRIOP_ADD: 1,
+    TRIOP_AVERAGE: 2
+});
+
+/** Trinity transform-parameter base frame from blue/include/ITriConstants.h. */
+export const TriTransformBase = Object.freeze({
+    TRITB_OBJECT: 0,
+    TRITB_CAMERA_ROTATION: 1,
+    TRITB_CAMERA_TRANSLATION: 2,
+    TRITB_CAMERA: 3,
+    TRITB_CAMERA_ROTATION_ALIGNED: 4,
+    TRITB_FIXED: 5,
+    TRITB_CAMERA_ROTATION_FALLOFF: 6,
+    TRITB_CAMERA_ROTATION_ALIGNED_SYMMETRY: 7,
+    TRITB_CAMERA_ROTATION_FALLOFF_SYMMETRY: 8,
+    TRITB_BOOSTER: 9,
+    TRITB_SIMPLE_HALO: 10,
+    TRITB_SIMPLE_HALO_SYMMETRY: 11,
+    TRITB_BOOSTER_FALLOFF: 12,
+    TRITB_WORLD: 13,
+    TRITB_SIMPLE_HALO_FALLOFF: 14,
+    TRITB_SIMPLE_SPRITE: 15,
+    TRITB_SIMPLE_SPRITE_FALLOFF: 16,
+    TRITB_SIMPLE_SPRITE_CONSTANT: 17
+});
+
+// Carbon TRIEXTRAPOLATION (blue/include/ITriConstants.h:33) - curve
+// extrapolation modes, shared by trinity curves (TriEventCurve) and audio
+// (AudEventCurve). Class statics alias this export (TriOperator pattern).
+export const TriExtrapolation = Object.freeze({
+    TRIEXT_NONE: 0,
+    TRIEXT_CONSTANT: 1,
+    TRIEXT_GRADIENT: 2,
+    TRIEXT_CYCLE: 3
+});

package/src/index.js

@@ -0,0 +1,58 @@
+export * as is from "./is.js";
+export * from "./is.js";
+
+export * as arrays from "./arrays.js";
+export * from "./arrays.js";
+export * as bytes from "./bytes.js";
+export * from "./bytes.js";
+export * as compression from "./compression.js";
+export * from "./compression.js";
+export * as json from "./json.js";
+export * from "./json.js";
+export * as lookup from "./lookup.js";
+export * from "./lookup.js";
+export * as path from "./path.js";
+export * from "./path.js";
+export * as text from "./text.js";
+export * from "./text.js";
+export * as validation from "./validation.js";
+export {
+    assertPlainObject,
+    assertNonEmptyString,
+    assertSupportedVersion
+} from "./validation.js";
+
+export * as constants from "./constants/index.js";
+export * from "./constants/index.js";
+
+export * as num from "./num.js";
+export * as math from "./math/index.js";
+export * from "./math/scalar.js";
+export * as vec2 from "./vec2.js";
+export * as vec3 from "./vec3.js";
+export * as vec4 from "./vec4.js";
+export * as quat from "./quat.js";
+export * as mat3 from "./mat3.js";
+export * as mat4 from "./mat4.js";
+
+export * as box3 from "./box3.js";
+export * as tri3 from "./tri3.js";
+export * as lne3 from "./lne3.js";
+export * as pln from "./pln.js";
+export * as ray3 from "./ray3.js";
+export * as sph3 from "./sph3.js";
+
+export * as pool from "./pool.js";
+export * as noise from "./noise.js";
+export * as curve from "./curve.js";
+
+export * as geometry from "./geometry/index.js";
+export * as vertex from "./vertex.js";
+export * as mesh from "./mesh.js";
+export * as tangent from "./tangent.js";
+
+
+/**
+ * TypedArray
+ * @typedef {Float64Array|Float32Array|Uint32Array|Uint16Array|Uint8Array|Uint8ClampedArray|Int32Array|Int16Array|Int8Array} TypedArray
+ */