@carbonenginejs/runtime-utils 0.1.0

package/src/vec4.js

@@ -0,0 +1,347 @@
+import * as glVec4 from "gl-matrix/esm/vec4.js";
+import { num } from "./num.js";
+import { pool } from "./pool.js";
+
+const vec4 = { ...glVec4 };
+
+/**
+ * Vector 4
+ * @typedef {Float32Array} vec4
+ */
+
+
+/**
+ * Allocates a pooled vec4
+ * @returns {Float32Array|vec4}
+ */
+vec4.alloc = function()
+{
+    return pool.allocF32(4);
+};
+
+/**
+ * Unallocates a pooled vec4
+ * @param {vec4|Float32Array} a
+ */
+vec4.unalloc = function(a)
+{
+    pool.freeType(a);
+};
+
+vec4.ZERO = vec4.fromValues(0, 0, 0, 0);
+
+/**
+ * Creates a linear color vec4 with opaque alpha
+ * @returns {vec4}
+ */
+vec4.createLinear = function()
+{
+    const out = vec4.create();
+    out[3] = 1;
+    return out;
+};
+
+/**
+ * Adds a scalar to a vec4
+ *
+ * @param {vec4} out
+ * @param {vec4} a
+ * @param {Number} s
+ * @returns {vec4} out
+ */
+vec4.addScalar = function(out, a, s)
+{
+    out[0] = a[0] + s;
+    out[1] = a[1] + s;
+    out[2] = a[2] + s;
+    out[3] = a[3] + s;
+    return out;
+};
+
+/**
+ * Checks if all elements are 0
+ * @param {vec4} a
+ * @returns {boolean}
+ */
+vec4.isEmpty = function(a)
+{
+    return a[0] === 0 && a[1] === 0 && a[2] === 0 && a[3] === 0;
+};
+
+/**
+ * Divides a vec4 by a scalar
+ *
+ * @param {vec4} out
+ * @param {vec4} a
+ * @param {Number} s
+ * @returns {vec4} out
+ */
+vec4.divideScalar = function(out, a, s)
+{
+    return vec4.multiplyScalar(out, a, 1 / s);
+};
+
+
+/**
+ * Multiplies a vec4 by a scalar
+ *
+ * @param {vec4} out
+ * @param {vec4} a
+ * @param {Number} s
+ * @returns {vec4} out
+ */
+vec4.multiplyScalar = function(out, a, s)
+{
+    out[0] = a[0] * s;
+    out[1] = a[1] * s;
+    out[2] = a[2] * s;
+    out[3] = a[3] * s;
+    return out;
+};
+
+/**
+ * Sets a vec4 from a scalar
+ *
+ * @param {vec4} out
+ * @param {Number} s
+ * @returns {vec4} out
+ */
+vec4.setScalar = function(out, s)
+{
+    out[0] = s;
+    out[1] = s;
+    out[2] = s;
+    out[3] = s;
+    return out;
+};
+
+/**
+ * Subtracts a scalar from a vec4
+ *
+ * @param {vec4} out
+ * @param {vec4} a
+ * @param {Number} s
+ * @returns {vec4} out
+ */
+vec4.subtractScalar = function(out, a, s)
+{
+    out[0] = a[0] - s;
+    out[1] = a[1] - s;
+    out[2] = a[2] - s;
+    out[3] = a[3] - s;
+    return out;
+};
+
+/**
+ * Converts from linear color to rgba
+ * @param {vec4} out
+ * @param {vec4} linear
+ * @param {boolean} [denormalizeAlpha]
+ * @returns {vec4}
+ */
+vec4.toRGBA = function(out, linear, denormalizeAlpha)
+{
+    out[0] = num.colorFromLinear(linear[0]);
+    out[1] = num.colorFromLinear(linear[1]);
+    out[2] = num.colorFromLinear(linear[2]);
+    out[3] = denormalizeAlpha ? num.colorFromLinear(linear[3]) : linear[3];
+    return out;
+};
+
+/**
+ * Converts to linear color from rgba
+ * @param {vec4} out
+ * @param {vec4} rgba
+ * @param {boolean} [denormalizedAlpha]
+ * @returns {vec4} out
+ */
+vec4.fromRGBA = function(out, rgba, denormalizedAlpha)
+{
+    out[0] = num.linearFromColor(rgba[0]);
+    out[1] = num.linearFromColor(rgba[1]);
+    out[2] = num.linearFromColor(rgba[2]);
+    out[3] = denormalizedAlpha ? num.linearFromColor(rgba[3]) : rgba[3];
+    return out;
+};
+
+/**
+ * Converts to linear color from rgb
+ * @param {vec4} out
+ * @param {vec3} rgb
+ * @param {Number} [linearAlpha=1]
+ * @returns {vec4} out
+ */
+vec4.fromRGB = function(out, rgb, linearAlpha = 1)
+{
+    out[0] = num.linearFromColor(rgb[0]);
+    out[1] = num.linearFromColor(rgb[1]);
+    out[2] = num.linearFromColor(rgb[2]);
+    out[3] = linearAlpha;
+    return out;
+};
+
+/**
+ * Gets hex value with alpha from linear color
+ * @param {vec4} linear
+ * @returns {string} hex value
+ */
+vec4.toHexA = function(linear)
+{
+    return "#" +
+        num.hexFromLinear(linear[0]) +
+        num.hexFromLinear(linear[1]) +
+        num.hexFromLinear(linear[2]) +
+        num.hexFromLinear(linear[3]);
+};
+
+/**
+ * Gets hex value from linear color
+ * @param {vec4} linear
+ * @returns {string} hex value
+ */
+vec4.toHex = function(linear)
+{
+    return "#" +
+        num.hexFromLinear(linear[0]) +
+        num.hexFromLinear(linear[1]) +
+        num.hexFromLinear(linear[2]);
+};
+
+/**
+ * Gets linear color from hex or hex with alpha
+ * @param {vec4} out
+ * @param {String} hex
+ * @param {Number} [defaultAlpha=1]
+ * @return {vec4}
+ */
+vec4.fromHex = function(out, hex, defaultAlpha = 1)
+{
+    // Set empty color in case of error
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = defaultAlpha;
+
+    if (typeof hex !== "string" || !/^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.test(hex))
+    {
+        throw new TypeError("Invalid hex");
+    }
+
+    // RGB hex
+    if (hex.length === 4 || hex.length === 5)
+    {
+        out[0] = ("0x" + hex[1] + hex[1]) / 255;
+        out[1] = ("0x" + hex[2] + hex[2]) / 255;
+        out[2] = ("0x" + hex[3] + hex[3]) / 255;
+        if (hex.length === 5) out[3] = ("0x" + hex[4] + hex[4]) / 255;
+    }
+    // RGB hex
+    else if (hex.length === 7 || hex.length === 9)
+    {
+        out[0] = ("0x" + hex[1] + hex[2]) / 255;
+        out[1] = ("0x" + hex[3] + hex[4]) / 255;
+        out[2] = ("0x" + hex[5] + hex[6]) / 255;
+        if (hex.length === 9) out[3] = ("0x" + hex[7] + hex[8]) / 255;
+    }
+    return out;
+};
+
+/**
+ * Sets a vec4 from an array with an optional offset
+ * @param {vec3} out
+ * @param {TypedArray|Array} array
+ * @param {Number} [offset=0]
+ * @returns {vec3} out
+ */
+vec4.fromArray = function(out, array, offset=0)
+{
+    out[0] = array[offset];
+    out[1] = array[offset + 1];
+    out[2] = array[offset + 2];
+    out[3] = array[offset + 3];
+    return out;
+};
+
+vec4.setArray = vec4.fromArray;
+
+/**
+ * Writes a vec4 to an array at an optional offset.
+ * @param {vec4} a
+ * @param {TypedArray|Array} array
+ * @param {Number} [offset=0]
+ * @returns {vec4} a
+ */
+vec4.toArray = function(a, array, offset=0)
+{
+    array[offset] = a[0];
+    array[offset + 1] = a[1];
+    array[offset + 2] = a[2];
+    array[offset + 3] = a[3];
+    return a;
+};
+
+
+export { vec4 };
+
+export const {
+    add,
+    ceil,
+    clone,
+    copy,
+    create,
+    cross,
+    dist,
+    distance,
+    div,
+    divide,
+    dot,
+    equals,
+    exactEquals,
+    floor,
+    forEach,
+    fromValues,
+    inverse,
+    len,
+    length,
+    lerp,
+    max,
+    min,
+    mul,
+    multiply,
+    negate,
+    normalize,
+    random,
+    round,
+    scale,
+    scaleAndAdd,
+    set,
+    sqrDist,
+    sqrLen,
+    squaredDistance,
+    squaredLength,
+    str,
+    sub,
+    subtract,
+    transformMat4,
+    transformQuat,
+    zero,
+    createLinear,
+    alloc,
+    unalloc,
+    ZERO,
+    addScalar,
+    isEmpty,
+    divideScalar,
+    multiplyScalar,
+    setScalar,
+    subtractScalar,
+    toRGBA,
+    fromRGBA,
+    fromRGB,
+    toHexA,
+    toHex,
+    fromHex,
+    fromArray,
+    setArray,
+    toArray
+} = vec4;

package/src/vertex.js

@@ -0,0 +1,108 @@
+/**
+ * Legacy vertex helper container backed by the shared mesh/tangent math.
+ *
+ * The previous ccpwgl implementation is intentionally not preserved here:
+ * normal/tangent generation now delegates to the same helpers used by the GR2,
+ * OBJ, glTF, and STL format packages.
+ */
+
+import {
+    generateBiNormals,
+    generateNormals,
+    generateTangentFrames,
+    generateTangents
+} from "./mesh.js";
+import { packTangentFrames } from "./tangent.js";
+
+function facesForAreas(indices, areas)
+{
+    if (!areas || areas.length === 0) return Array.from(indices);
+
+    const faces = [];
+    for (const area of areas)
+    {
+        const
+            start = area.start || 0,
+            count = area.count === undefined ? indices.length - start : area.count;
+
+        for (let i = start; i < start + count; i++)
+        {
+            faces.push(indices[i]);
+        }
+    }
+    return faces;
+}
+
+/**
+ * Calculate area-weighted vertex normals.
+ *
+ * @param {ArrayLike<number>} indices Flat triangle indices.
+ * @param {ArrayLike<number>} positions Flat xyz positions.
+ * @returns {number[]} Flat xyz normals.
+ */
+export function calculateNormals(indices, positions)
+{
+    return generateNormals(positions, indices);
+}
+
+/**
+ * Calculate xyz tangents from positions, normals, UVs, and triangle indices.
+ *
+ * @param {ArrayLike<number>} indices Flat triangle indices.
+ * @param {ArrayLike<number>} positions Flat xyz positions.
+ * @param {ArrayLike<number>} uvs Flat uv coordinates.
+ * @param {Array<object>} [areas] Optional index ranges to use.
+ * @param {ArrayLike<number>} [normals] Flat xyz normals; generated when absent.
+ * @returns {number[]} Flat xyz tangents.
+ */
+export function calculateTangents(indices, positions, uvs, areas, normals)
+{
+    const faces = facesForAreas(indices, areas);
+    return generateTangents(
+        positions,
+        normals && normals.length ? normals : generateNormals(positions, faces),
+        uvs,
+        faces
+    );
+}
+
+/**
+ * Calculate xyz binormals from normals and tangents.
+ *
+ * @param {ArrayLike<number>} normals Flat xyz normals.
+ * @param {ArrayLike<number>} tangents Flat xyz tangents.
+ * @param {object} [options] Generation options.
+ * @returns {number[]} Flat xyz binormals.
+ */
+export function calculateBiNormals(normals, tangents, options)
+{
+    return generateBiNormals(normals, tangents, options);
+}
+
+/**
+ * Calculate GR2-style packed tangent frames.
+ *
+ * @param {ArrayLike<number>} indices Flat triangle indices.
+ * @param {ArrayLike<number>} positions Flat xyz positions.
+ * @param {ArrayLike<number>} uvs Flat uv coordinates.
+ * @param {Array<object>} [areas] Optional index ranges to use.
+ * @param {ArrayLike<number>} [normals] Flat xyz normals; generated when absent.
+ * @param {object} [options] Generation options.
+ * @returns {number[]} Flat xyzw packed tangent-frame values.
+ */
+export function calculatePackedTangents(indices, positions, uvs, areas, normals, options)
+{
+    const
+        faces = facesForAreas(indices, areas),
+        normalValues = normals && normals.length ? normals : generateNormals(positions, faces),
+        frame = generateTangentFrames(positions, normalValues, uvs, faces, options);
+
+    return packTangentFrames(normalValues, frame.tangents, frame.binormals);
+}
+
+export const vertex = Object.freeze({
+    calculateNormals,
+    calculateTangents,
+    calculateBiNormals,
+    calculatePackedTangents
+});

package/src/webgpu/index.js

@@ -0,0 +1 @@
+export * from "./textureFormats.js";

package/src/webgpu/textureFormats.js

@@ -0,0 +1,121 @@
+import { PixelFormat } from "../graphics/pixelFormats.js";
+import { DxgiFormat } from "../d3d/dxgiFormats.js";
+
+/**
+ * WebGPU texture format tokens mirrored as stable strings.
+ */
+export const GpuTextureFormat = Object.freeze({
+    R8_UNORM: "r8unorm",
+    RG8_UNORM: "rg8unorm",
+    RGBA8_UNORM: "rgba8unorm",
+    RGBA8_UNORM_SRGB: "rgba8unorm-srgb",
+    BGRA8_UNORM: "bgra8unorm",
+    BGRA8_UNORM_SRGB: "bgra8unorm-srgb",
+    R16_FLOAT: "r16float",
+    RG16_FLOAT: "rg16float",
+    RGBA16_FLOAT: "rgba16float",
+    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"
+});
+
+/**
+ * Map canonical CarbonEngineJS pixel formats to WebGPU texture format strings.
+ */
+export const PixelFormatToWebGpu = Object.freeze({
+    [PixelFormat.R8_UNORM]: GpuTextureFormat.R8_UNORM,
+    [PixelFormat.RG8_UNORM]: GpuTextureFormat.RG8_UNORM,
+    [PixelFormat.RGBA8_UNORM]: GpuTextureFormat.RGBA8_UNORM,
+    [PixelFormat.RGBA8_UNORM_SRGB]: GpuTextureFormat.RGBA8_UNORM_SRGB,
+    [PixelFormat.BGRA8_UNORM]: GpuTextureFormat.BGRA8_UNORM,
+    [PixelFormat.BGRA8_UNORM_SRGB]: GpuTextureFormat.BGRA8_UNORM_SRGB,
+    [PixelFormat.R16_FLOAT]: GpuTextureFormat.R16_FLOAT,
+    [PixelFormat.RG16_FLOAT]: GpuTextureFormat.RG16_FLOAT,
+    [PixelFormat.RGBA16_FLOAT]: GpuTextureFormat.RGBA16_FLOAT,
+    [PixelFormat.R32_FLOAT]: GpuTextureFormat.R32_FLOAT,
+    [PixelFormat.RG32_FLOAT]: GpuTextureFormat.RG32_FLOAT,
+    [PixelFormat.RGBA32_FLOAT]: GpuTextureFormat.RGBA32_FLOAT,
+    [PixelFormat.BC1_RGBA_UNORM]: GpuTextureFormat.BC1_RGBA_UNORM,
+    [PixelFormat.BC1_RGBA_UNORM_SRGB]: GpuTextureFormat.BC1_RGBA_UNORM_SRGB,
+    [PixelFormat.BC2_RGBA_UNORM]: GpuTextureFormat.BC2_RGBA_UNORM,
+    [PixelFormat.BC2_RGBA_UNORM_SRGB]: GpuTextureFormat.BC2_RGBA_UNORM_SRGB,
+    [PixelFormat.BC3_RGBA_UNORM]: GpuTextureFormat.BC3_RGBA_UNORM,
+    [PixelFormat.BC3_RGBA_UNORM_SRGB]: GpuTextureFormat.BC3_RGBA_UNORM_SRGB,
+    [PixelFormat.BC4_R_UNORM]: GpuTextureFormat.BC4_R_UNORM,
+    [PixelFormat.BC4_R_SNORM]: GpuTextureFormat.BC4_R_SNORM,
+    [PixelFormat.BC5_RG_UNORM]: GpuTextureFormat.BC5_RG_UNORM,
+    [PixelFormat.BC5_RG_SNORM]: GpuTextureFormat.BC5_RG_SNORM,
+    [PixelFormat.BC6H_RGB_UFLOAT]: GpuTextureFormat.BC6H_RGB_UFLOAT,
+    [PixelFormat.BC6H_RGB_FLOAT]: GpuTextureFormat.BC6H_RGB_FLOAT,
+    [PixelFormat.BC7_RGBA_UNORM]: GpuTextureFormat.BC7_RGBA_UNORM,
+    [PixelFormat.BC7_RGBA_UNORM_SRGB]: GpuTextureFormat.BC7_RGBA_UNORM_SRGB
+});
+
+/**
+ * Map selected DXGI formats to canonical CarbonEngineJS pixel formats.
+ */
+export const DxgiFormatToPixelFormat = Object.freeze({
+    [DxgiFormat.R32G32B32A32_FLOAT]: PixelFormat.RGBA32_FLOAT,
+    [DxgiFormat.R32G32_FLOAT]: PixelFormat.RG32_FLOAT,
+    [DxgiFormat.R32_FLOAT]: PixelFormat.R32_FLOAT,
+    [DxgiFormat.R16G16B16A16_FLOAT]: PixelFormat.RGBA16_FLOAT,
+    [DxgiFormat.R8G8_UNORM]: PixelFormat.RG8_UNORM,
+    [DxgiFormat.R8G8B8A8_UNORM]: PixelFormat.RGBA8_UNORM,
+    [DxgiFormat.R8G8B8A8_UNORM_SRGB]: PixelFormat.RGBA8_UNORM_SRGB,
+    [DxgiFormat.R16_FLOAT]: PixelFormat.R16_FLOAT,
+    [DxgiFormat.R8_UNORM]: PixelFormat.R8_UNORM,
+    [DxgiFormat.BC1_UNORM]: PixelFormat.BC1_RGBA_UNORM,
+    [DxgiFormat.BC1_UNORM_SRGB]: PixelFormat.BC1_RGBA_UNORM_SRGB,
+    [DxgiFormat.BC2_UNORM]: PixelFormat.BC2_RGBA_UNORM,
+    [DxgiFormat.BC2_UNORM_SRGB]: PixelFormat.BC2_RGBA_UNORM_SRGB,
+    [DxgiFormat.BC3_UNORM]: PixelFormat.BC3_RGBA_UNORM,
+    [DxgiFormat.BC3_UNORM_SRGB]: PixelFormat.BC3_RGBA_UNORM_SRGB,
+    [DxgiFormat.BC4_UNORM]: PixelFormat.BC4_R_UNORM,
+    [DxgiFormat.BC4_SNORM]: PixelFormat.BC4_R_SNORM,
+    [DxgiFormat.BC5_UNORM]: PixelFormat.BC5_RG_UNORM,
+    [DxgiFormat.BC5_SNORM]: PixelFormat.BC5_RG_SNORM,
+    [DxgiFormat.B8G8R8A8_UNORM]: PixelFormat.BGRA8_UNORM,
+    [DxgiFormat.B8G8R8X8_UNORM]: PixelFormat.BGRX8_UNORM,
+    [DxgiFormat.B8G8R8A8_UNORM_SRGB]: PixelFormat.BGRA8_UNORM_SRGB,
+    [DxgiFormat.B8G8R8X8_UNORM_SRGB]: PixelFormat.BGRX8_UNORM_SRGB,
+    [DxgiFormat.BC6H_UF16]: PixelFormat.BC6H_RGB_UFLOAT,
+    [DxgiFormat.BC6H_SF16]: PixelFormat.BC6H_RGB_FLOAT,
+    [DxgiFormat.BC7_UNORM]: PixelFormat.BC7_RGBA_UNORM,
+    [DxgiFormat.BC7_UNORM_SRGB]: PixelFormat.BC7_RGBA_UNORM_SRGB
+});
+
+/**
+ * Convert a pixel format token to a WebGPU texture format token.
+ *
+ * @param {string} format Pixel format token.
+ * @returns {string} WebGPU texture format token or empty string.
+ */
+export function toWebGpuTextureFormat(format)
+{
+    return PixelFormatToWebGpu[format] || "";
+}
+
+/**
+ * Convert a DXGI numeric format to a pixel format token.
+ *
+ * @param {number} format DXGI_FORMAT numeric value.
+ * @returns {string} Pixel format token or unknown.
+ */
+export function dxgiToPixelFormat(format)
+{
+    return DxgiFormatToPixelFormat[format] || PixelFormat.UNKNOWN;
+}