@carbonenginejs/runtime-utils 0.1.0

package/src/renderContext/formats.js

@@ -0,0 +1,145 @@
+// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
+//   trinityal/Tr2RenderContextEnum.h (PixelFormat, DepthStencilFormat); shadercompiler/EffectData.h (TextureType)
+
+/** Carbon numeric GPU pixel formats (distinct from the abstract graphics/pixelFormats string vocabulary). */
+export const PixelFormat = Object.freeze({
+    PIXEL_FORMAT_UNKNOWN: 0,
+    PIXEL_FORMAT_R32G32B32A32_TYPELESS: 1,
+    PIXEL_FORMAT_R32G32B32A32_FLOAT: 2,
+    PIXEL_FORMAT_R32G32B32A32_UINT: 3,
+    PIXEL_FORMAT_R32G32B32A32_SINT: 4,
+    PIXEL_FORMAT_R32G32B32_TYPELESS: 5,
+    PIXEL_FORMAT_R32G32B32_FLOAT: 6,
+    PIXEL_FORMAT_R32G32B32_UINT: 7,
+    PIXEL_FORMAT_R32G32B32_SINT: 8,
+    PIXEL_FORMAT_R16G16B16A16_TYPELESS: 9,
+    PIXEL_FORMAT_R16G16B16A16_FLOAT: 10,
+    PIXEL_FORMAT_R16G16B16A16_UNORM: 11,
+    PIXEL_FORMAT_R16G16B16A16_UINT: 12,
+    PIXEL_FORMAT_R16G16B16A16_SNORM: 13,
+    PIXEL_FORMAT_R16G16B16A16_SINT: 14,
+    PIXEL_FORMAT_R32G32_TYPELESS: 15,
+    PIXEL_FORMAT_R32G32_FLOAT: 16,
+    PIXEL_FORMAT_R32G32_UINT: 17,
+    PIXEL_FORMAT_R32G32_SINT: 18,
+    PIXEL_FORMAT_R32G8X24_TYPELESS: 19,
+    PIXEL_FORMAT_D32_FLOAT_S8X24_UINT: 20,
+    PIXEL_FORMAT_R32_FLOAT_X8X24_TYPELESS: 21,
+    PIXEL_FORMAT_X32_TYPELESS_G8X24_UINT: 22,
+    PIXEL_FORMAT_R10G10B10A2_TYPELESS: 23,
+    PIXEL_FORMAT_R10G10B10A2_UNORM: 24,
+    PIXEL_FORMAT_R10G10B10A2_UINT: 25,
+    PIXEL_FORMAT_R11G11B10_FLOAT: 26,
+    PIXEL_FORMAT_R8G8B8A8_TYPELESS: 27,
+    PIXEL_FORMAT_R8G8B8A8_UNORM: 28,
+    PIXEL_FORMAT_R8G8B8A8_UNORM_SRGB: 29,
+    PIXEL_FORMAT_R8G8B8A8_UINT: 30,
+    PIXEL_FORMAT_R8G8B8A8_SNORM: 31,
+    PIXEL_FORMAT_R8G8B8A8_SINT: 32,
+    PIXEL_FORMAT_R16G16_TYPELESS: 33,
+    PIXEL_FORMAT_R16G16_FLOAT: 34,
+    PIXEL_FORMAT_R16G16_UNORM: 35,
+    PIXEL_FORMAT_R16G16_UINT: 36,
+    PIXEL_FORMAT_R16G16_SNORM: 37,
+    PIXEL_FORMAT_R16G16_SINT: 38,
+    PIXEL_FORMAT_R32_TYPELESS: 39,
+    PIXEL_FORMAT_D32_FLOAT: 40,
+    PIXEL_FORMAT_R32_FLOAT: 41,
+    PIXEL_FORMAT_R32_UINT: 42,
+    PIXEL_FORMAT_R32_SINT: 43,
+    PIXEL_FORMAT_R24G8_TYPELESS: 44,
+    PIXEL_FORMAT_D24_UNORM_S8_UINT: 45,
+    PIXEL_FORMAT_R24_UNORM_X8_TYPELESS: 46,
+    PIXEL_FORMAT_X24_TYPELESS_G8_UINT: 47,
+    PIXEL_FORMAT_R8G8_TYPELESS: 48,
+    PIXEL_FORMAT_R8G8_UNORM: 49,
+    PIXEL_FORMAT_R8G8_UINT: 50,
+    PIXEL_FORMAT_R8G8_SNORM: 51,
+    PIXEL_FORMAT_R8G8_SINT: 52,
+    PIXEL_FORMAT_R16_TYPELESS: 53,
+    PIXEL_FORMAT_R16_FLOAT: 54,
+    PIXEL_FORMAT_D16_UNORM: 55,
+    PIXEL_FORMAT_R16_UNORM: 56,
+    PIXEL_FORMAT_R16_UINT: 57,
+    PIXEL_FORMAT_R16_SNORM: 58,
+    PIXEL_FORMAT_R16_SINT: 59,
+    PIXEL_FORMAT_R8_TYPELESS: 60,
+    PIXEL_FORMAT_R8_UNORM: 61,
+    PIXEL_FORMAT_R8_UINT: 62,
+    PIXEL_FORMAT_R8_SNORM: 63,
+    PIXEL_FORMAT_R8_SINT: 64,
+    PIXEL_FORMAT_A8_UNORM: 65,
+    PIXEL_FORMAT_R1_UNORM: 66,
+    PIXEL_FORMAT_R9G9B9E5_SHAREDEXP: 67,
+    PIXEL_FORMAT_R8G8_B8G8_UNORM: 68,
+    PIXEL_FORMAT_G8R8_G8B8_UNORM: 69,
+    PIXEL_FORMAT_BC1_TYPELESS: 70,
+    PIXEL_FORMAT_BC1_UNORM: 71,
+    PIXEL_FORMAT_BC1_UNORM_SRGB: 72,
+    PIXEL_FORMAT_BC2_TYPELESS: 73,
+    PIXEL_FORMAT_BC2_UNORM: 74,
+    PIXEL_FORMAT_BC2_UNORM_SRGB: 75,
+    PIXEL_FORMAT_BC3_TYPELESS: 76,
+    PIXEL_FORMAT_BC3_UNORM: 77,
+    PIXEL_FORMAT_BC3_UNORM_SRGB: 78,
+    PIXEL_FORMAT_BC4_TYPELESS: 79,
+    PIXEL_FORMAT_BC4_UNORM: 80,
+    PIXEL_FORMAT_BC4_SNORM: 81,
+    PIXEL_FORMAT_BC5_TYPELESS: 82,
+    PIXEL_FORMAT_BC5_UNORM: 83,
+    PIXEL_FORMAT_BC5_SNORM: 84,
+    PIXEL_FORMAT_B5G6R5_UNORM: 85,
+    PIXEL_FORMAT_B5G5R5A1_UNORM: 86,
+    PIXEL_FORMAT_B8G8R8A8_UNORM: 87,
+    PIXEL_FORMAT_B8G8R8X8_UNORM: 88,
+    PIXEL_FORMAT_R10G10B10_XR_BIAS_A2_UNORM: 89,
+    PIXEL_FORMAT_B8G8R8A8_TYPELESS: 90,
+    PIXEL_FORMAT_B8G8R8A8_UNORM_SRGB: 91,
+    PIXEL_FORMAT_B8G8R8X8_TYPELESS: 92,
+    PIXEL_FORMAT_B8G8R8X8_UNORM_SRGB: 93,
+    PIXEL_FORMAT_BC6H_TYPELESS: 94,
+    PIXEL_FORMAT_BC6H_UF16: 95,
+    PIXEL_FORMAT_BC6H_SF16: 96,
+    PIXEL_FORMAT_BC7_TYPELESS: 97,
+    PIXEL_FORMAT_BC7_UNORM: 98,
+    PIXEL_FORMAT_BC7_UNORM_SRGB: 99,
+    PIXEL_FORMAT_SENTINEL: 100,
+    PIXEL_FORMAT_FORCE_UINT: 4294967295
+});
+
+export const DepthStencilFormat = Object.freeze({
+    DSFMT_UNKNOWN: 0,
+    DSFMT_D24S8: 1,
+    DSFMT_D24X8: 2,
+    DSFMT_D24FS8: 3,
+    DSFMT_D32F: 4,
+    DSFMT_D32: 5,
+    DSFMT_READABLE: 6,
+    DSFMT_AUTO: 7,
+    DSFMT_D16_LOCKABLE: 8,
+    DSFMT_D15S1: 9,
+    DSFMT_D24X4S4: 10,
+    DSFMT_D16: 11,
+    DSFMT_D32F_LOCKABLE: 12
+});
+
+/** Carbon texture/buffer view type (Tr2RenderContextEnum::TextureType). */
+export const TextureType = Object.freeze({
+    TEX_TYPE_1D: 1,
+    TEX_TYPE_2D: 2,
+    TEX_TYPE_3D: 3,
+    TEX_TYPE_CUBE: 4,
+    TEX_TYPE_TYPELESS: 5,
+    TEX_TYPE_BUFFER: 6,
+    TEX_TYPE_STRUCTURED_BUFFER: 7,
+    TEX_TYPE_TBUFFER: 8,
+    TEX_TYPE_BYTEADDRESS_BUFFER: 9,
+    TEX_TYPE_UAV_RWTYPED: 10,
+    TEX_TYPE_UAV_RWSTRUCTURED: 11,
+    TEX_TYPE_UAV_RWBYTEADDRESS: 12,
+    TEX_TYPE_UAV_APPEND_STRUCTURED: 13,
+    TEX_TYPE_UAV_CONSUME_STRUCTURED: 14,
+    TEX_TYPE_UAV_RWSTRUCTURED_WITH_COUNTER: 15,
+    TEX_TYPE_RAYTRACING_ACCELERATION_STRUCTURE: 16,
+    TEX_TYPE_INVALID: 17
+});

package/src/renderContext/index.js

@@ -0,0 +1,5 @@
+export * from "./formats.js";
+export * from "./resources.js";
+export * from "./presentation.js";
+export * from "./upscaling.js";
+export * from "./window.js";

package/src/renderContext/presentation.js

@@ -0,0 +1,125 @@
+// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
+//   trinityal/Tr2RenderContextEnum.h (SwapEffect, PresentInterval, RenderState)
+
+export const SwapEffect = Object.freeze({
+    SWAP_EFFECT_DISCARD: 0,
+    SWAP_EFFECT_SEQUENTIAL: 1
+});
+
+export const PresentInterval = Object.freeze({
+    PRESENT_INTERVAL_IMMEDIATE: 0,
+    PRESENT_INTERVAL_ONE: 1
+});
+
+/** Sparse D3D-derived render state ids. */
+export const RenderState = Object.freeze({
+    RS_ZENABLE: 7,
+    RS_FILLMODE: 8,
+    RS_SHADEMODE: 9,
+    RS_ZWRITEENABLE: 14,
+    RS_ALPHATESTENABLE: 15,
+    RS_LASTPIXEL: 16,
+    RS_SRCBLEND: 19,
+    RS_DESTBLEND: 20,
+    RS_CULLMODE: 22,
+    RS_ZFUNC: 23,
+    RS_ALPHAREF: 24,
+    RS_ALPHAFUNC: 25,
+    RS_DITHERENABLE: 26,
+    RS_ALPHABLENDENABLE: 27,
+    RS_FOGENABLE: 28,
+    RS_SPECULARENABLE: 29,
+    RS_FOGCOLOR: 34,
+    RS_FOGTABLEMODE: 35,
+    RS_FOGSTART: 36,
+    RS_FOGEND: 37,
+    RS_FOGDENSITY: 38,
+    RS_RANGEFOGENABLE: 48,
+    RS_STENCILENABLE: 52,
+    RS_STENCILFAIL: 53,
+    RS_STENCILZFAIL: 54,
+    RS_STENCILPASS: 55,
+    RS_STENCILFUNC: 56,
+    RS_STENCILREF: 57,
+    RS_STENCILMASK: 58,
+    RS_STENCILWRITEMASK: 59,
+    RS_TEXTUREFACTOR: 60,
+    RS_DEPTH_CLIP_ENABLE: 61,
+    RS_WRAP0: 128,
+    RS_WRAP1: 129,
+    RS_WRAP2: 130,
+    RS_WRAP3: 131,
+    RS_WRAP4: 132,
+    RS_WRAP5: 133,
+    RS_WRAP6: 134,
+    RS_WRAP7: 135,
+    RS_CLIPPING: 136,
+    RS_LIGHTING: 137,
+    RS_AMBIENT: 139,
+    RS_FOGVERTEXMODE: 140,
+    RS_COLORVERTEX: 141,
+    RS_LOCALVIEWER: 142,
+    RS_NORMALIZENORMALS: 143,
+    RS_DIFFUSEMATERIALSOURCE: 145,
+    RS_SPECULARMATERIALSOURCE: 146,
+    RS_AMBIENTMATERIALSOURCE: 147,
+    RS_EMISSIVEMATERIALSOURCE: 148,
+    RS_VERTEXBLEND: 151,
+    RS_CLIPPLANEENABLE: 152,
+    RS_POINTSIZE: 154,
+    RS_POINTSIZE_MIN: 155,
+    RS_POINTSPRITEENABLE: 156,
+    RS_POINTSCALEENABLE: 157,
+    RS_POINTSCALE_A: 158,
+    RS_POINTSCALE_B: 159,
+    RS_POINTSCALE_C: 160,
+    RS_MULTISAMPLEANTIALIAS: 161,
+    RS_MULTISAMPLEMASK: 162,
+    RS_PATCHEDGESTYLE: 163,
+    RS_DEBUGMONITORTOKEN: 165,
+    RS_POINTSIZE_MAX: 166,
+    RS_INDEXEDVERTEXBLENDENABLE: 167,
+    RS_COLORWRITEENABLE: 168,
+    RS_TWEENFACTOR: 170,
+    RS_BLENDOP: 171,
+    RS_POSITIONDEGREE: 172,
+    RS_NORMALDEGREE: 173,
+    RS_SLOPESCALEDEPTHBIAS: 175,
+    RS_ANTIALIASEDLINEENABLE: 176,
+    RS_MINTESSELLATIONLEVEL: 178,
+    RS_MAXTESSELLATIONLEVEL: 179,
+    RS_ADAPTIVETESS_X: 180,
+    RS_ADAPTIVETESS_Y: 181,
+    RS_ADAPTIVETESS_Z: 182,
+    RS_ADAPTIVETESS_W: 183,
+    RS_ENABLEADAPTIVETESSELLATION: 184,
+    RS_TWOSIDEDSTENCILMODE: 185,
+    RS_CCW_STENCILFAIL: 186,
+    RS_CCW_STENCILZFAIL: 187,
+    RS_CCW_STENCILPASS: 188,
+    RS_CCW_STENCILFUNC: 189,
+    RS_COLORWRITEENABLE1: 190,
+    RS_COLORWRITEENABLE2: 191,
+    RS_COLORWRITEENABLE3: 192,
+    RS_BLENDFACTOR: 193,
+    RS_SRGBWRITEENABLE: 194,
+    RS_DEPTHBIAS: 195,
+    RS_WRAP8: 198,
+    RS_WRAP9: 199,
+    RS_WRAP10: 200,
+    RS_WRAP11: 201,
+    RS_WRAP12: 202,
+    RS_WRAP13: 203,
+    RS_WRAP14: 204,
+    RS_WRAP15: 205,
+    RS_SEPARATEALPHABLENDENABLE: 206,
+    RS_SRCBLENDALPHA: 207,
+    RS_DESTBLENDALPHA: 208,
+    RS_BLENDOPALPHA: 209,
+    RS_ZBIAS: 47,
+    // RS_SCISSORTESTENABLE: 174 — present in ccpwgl (src/global/constant/d3d.js)
+    // but not in Carbon's Tr2RenderContextEnum::RenderState. Kept commented in
+    // case a consumer needs the D3D9 scissor-test state later.
+    RS_MAX_STATE: 210,
+    RS_FORCE_DWORD: 0
+});

package/src/renderContext/resources.js

@@ -0,0 +1,27 @@
+// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
+//   trinityal/Tr2RenderContextEnum.h (Tr2CpuUsage, Tr2GpuUsage namespaces)
+
+/** CPU access usage flags. */
+export const Tr2CpuUsage = Object.freeze({
+    NONE: 0,
+    READ: 1,
+    WRITE: 2,
+    READ_OFTEN: 5,
+    WRITE_OFTEN: 10,
+    NON_SYNCRONIZED_WRITE: 16
+});
+
+/** GPU resource usage flags. */
+export const Tr2GpuUsage = Object.freeze({
+    NONE: 0,
+    VERTEX_BUFFER: 1,
+    INDEX_BUFFER: 2,
+    RENDER_TARGET: 4,
+    DEPTH_STENCIL: 8,
+    SHADER_RESOURCE: 16,
+    UNORDERED_ACCESS: 32,
+    COPY_DESTINATION: 64,
+    DRAW_INDIRECT_ARGS: 128,
+    ACCELERATION_STRUCTURE: 256,
+    SHARED: 512
+});

package/src/renderContext/upscaling.js

@@ -0,0 +1,22 @@
+// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
+//   trinityal/include/upscaling/Tr2UpscalingAL.h (Technique, Setting)
+
+export const UpscalingTechnique = Object.freeze({
+    NONE: 0,
+    FSR1: 1,
+    FSR2: 2,
+    FSR3: 3,
+    DLSS: 4,
+    XESS: 5,
+    METALFX: 6
+});
+
+/** Upscaling quality setting flags. */
+export const UpscalingSetting = Object.freeze({
+    NATIVE: 1,
+    ULTRA_QUALITY: 2,
+    QUALITY: 4,
+    BALANCED: 8,
+    PERFORMANCE: 16,
+    ULTRA_PERFORMANCE: 32
+});

package/src/renderContext/window.js

@@ -0,0 +1,20 @@
+// Ported from CarbonEngine (MIT, (c) 2026 CCP Games) - https://github.com/carbonengine/trinity
+//   trinity/UI/Tr2MainWindow.h (Tr2WindowMode, Tr2WindowShowState, Tr2ImeState_MacOS namespaces)
+
+export const Tr2WindowMode = Object.freeze({
+    FULL_SCREEN: 0,
+    WINDOWED: 1,
+    FIXED_WINDOW: 2
+});
+
+export const Tr2WindowShowState = Object.freeze({
+    NORMAL: 0,
+    MAXIMIZED: 1,
+    MINIMIZED: 2
+});
+
+export const Tr2ImeState_MacOS = Object.freeze({
+    DISABLED: 0,
+    READY: 1,
+    BLOCKING: 2
+});

package/src/runtime/CjsRuntimeState.js

@@ -0,0 +1,50 @@
+/**
+ * Gets an object's own CarbonEngineJS runtime state without creating it.
+ *
+ * Runtime state is intentionally stored on the object for inspection while
+ * remaining outside enumeration and serialization.
+ *
+ * @param {object|Function} target
+ * @returns {object|null}
+ */
+export function getRuntimeState(target)
+{
+    assertRuntimeStateTarget(target);
+    if (!Object.prototype.hasOwnProperty.call(target, "__state")) return null;
+
+    const state = target.__state;
+    if (!state || typeof state !== "object" || Array.isArray(state))
+    {
+        throw new TypeError("Existing __state must be an object.");
+    }
+    return state;
+}
+
+/**
+ * Gets or creates an object's own non-enumerable runtime state.
+ *
+ * @param {object|Function} target
+ * @returns {object}
+ */
+export function ensureRuntimeState(target)
+{
+    const existing = getRuntimeState(target);
+    if (existing) return existing;
+
+    const state = {};
+    Object.defineProperty(target, "__state", {
+        value: state,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    return state;
+}
+
+function assertRuntimeStateTarget(target)
+{
+    if ((typeof target !== "object" || target === null) && typeof target !== "function")
+    {
+        throw new TypeError("Runtime state requires an object or function.");
+    }
+}