@carbonenginejs/runtime 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/trinity/core/context/Tr2RenderContext.js

@@ -1,5 +1,5 @@
 import { identity as _identity, applyDecs2311 as _applyDecs2311 } from '../../../_virtual/_rollupPluginBabelHelpers.js';
-import { impl, type } from '#schema';
+import { impl, carbon, type } from '#schema';
 import { CjsModel } from '#model';
 import { mat4 } from '#math/mat4';
 import { vec3 } from '#math/vec3';
@@ -11,6 +11,7 @@ import { TriPoolAllocator } from '../rawData/TriPoolAllocator.js';
 import { Tr2PerObjectData } from '../rawData/perObjectData/Tr2PerObjectData.js';
 import { CjsDirectTrinityStepExecutor } from './CjsDirectTrinityStepExecutor.js';
 import { CjsTrinityStepExecutor } from './CjsTrinityStepExecutor.js';
+import '../device/TriDevice.js';
 import { Tr2RenderBatch } from '../batch/TriRenderBatch/Tr2RenderBatch.js';
 import '../batch/TriRenderBatch/DefaultKeyGenerator.js';
 import '../batch/TriRenderBatch/EffectKeyGenerator.js';
@@ -21,7 +22,7 @@ import { Tr2RenderContextALStub } from '../../../trinityal/stub/Tr2RenderContext
 import { Tr2Blitter } from '../Tr2Blitter.js';
 import { RealizeBatchGeometry } from '../mesh/TriGeometryResAllocations.js';
 
-let _initProto, _initClass;
+let _initProto, _initStatic, _initClass;
 const DIRECT_STEP_EXECUTOR = Object.freeze(new CjsDirectTrinityStepExecutor());
 
 /** Carbon DEFAULT_TECHNIQUE (Tr2RenderContext.h:37). */
@@ -33,12 +34,13 @@ new class extends _identity {
   static [class Tr2RenderContext extends CjsModel {
     static {
       ({
-        e: [_initProto],
+        e: [_initProto, _initStatic],
         c: [_Tr2RenderContext, _initClass]
       } = _applyDecs2311(this, [type.define({
         className: "Tr2RenderContext",
         family: "trinityCore"
-      })], [[[impl, impl.custom, void 0, impl.reason("Forwards JS platform selection and its internal allocation mode to the installed abstraction-layer context.")], 18, "CreateResourceSet"]], 0, void 0, CjsModel));
+      })], [[[impl, impl.custom, void 0, impl.reason("Forwards JS platform selection and its internal allocation mode to the installed abstraction-layer context.")], 18, "CreateResourceSet"], [[carbon, carbon.method, impl, impl.implemented], 26, "DestroyMainThreadRenderContext"]], 0, void 0, CjsModel));
+      _initStatic(this);
     }
     #diagnostics = (_initProto(this), []);
     #stepExecutor = DIRECT_STEP_EXECUTOR;
@@ -112,17 +114,11 @@ new class extends _identity {
     // chunks once it exists.
     #poolAllocator = null;
 
-    // The frame clock, relocated here with the other Tr2Renderer statics. Carbon
-    // keeps the counter as a file-scope global in TriDevice.cpp:143 and the
-    // animation time as a TriDevice member; both are ADVANCED by the tick
-    // (TriDevice::Update, cpp:805/:823) and only READ by the render path
-    // (Tr2Renderer::GetCurrentFrameCounter, cpp:1090). Holding them here is what
-    // lets BeginFrame stay zero-argument as Carbon declares it, and matches the
-    // frameIndex an EveSpaceScene driver already documents as coming from
-    // GetCurrentFrameCounter. Trinity does not advance them: a driver does.
-    #frameCounter = 0;
-    #animationTime = 0;
-    #previousAnimationTime = 0;
+    // THE FRAME CLOCK IS NOT HERE. It was, as a stand-in while the tick was
+    // unported; the tick landed on TriDevice (2026-09-18) and the readers moved
+    // to Tr2Renderer's statics with it, which is where Carbon declares them
+    // (Tr2Renderer.h:125-133).
+
     #debugRenderer = null;
     /** Installs a nominal step executor; null restores direct step execution. */
     SetStepExecutor(executor) {
@@ -205,82 +201,30 @@ new class extends _identity {
       return this.#stepExecutor.EndBatch(owner, this);
     }
 
-    // Carbon Tr2Renderer::GetCurrentFrameCounter (Tr2Renderer.cpp:1088-1091).
-
-    /** The frame the render path is currently working on. */
-    GetCurrentFrameCounter() {
-      return this.#frameCounter;
-    }
-
-    /** The animation clock the render path publishes, in seconds. */
-    GetAnimationTime() {
-      return this.#animationTime;
-    }
-
-    // Carbon advances both in TriDevice::Update (cpp:805/:823), which is the
-    // tick, and the tick is engine-owned (see the frame-driver contract in
-    // docs/architecture.md). A driver calls this once per frame BEFORE Render.
-    // Trinity never advances the clock itself: it cannot prove a frame boundary.
+    // Carbon's context INHERITS BeginScene/EndScene from the abstraction layer
+    // (`Tr2RenderContextDx11.h:67-68`, and the same pair on dx12, metal and the
+    // stub), and `Tr2Renderer::BeginRenderContext` is a one-line forward to them
+    // (`Tr2Renderer.cpp:1066-1081`). The frame bracket therefore belongs to the
+    // backend, not to a step executor: the AL stub's own comment already says so,
+    // and the WebGPU backend opens its command encoder in BeginScene and submits
+    // in EndScene.
 
     /**
-     * Advances the frame clock: increments the frame counter and records the new
-     * animation time, keeping the previous one for the render-time vector.
-     * Returns this for chaining.
-     */
-    AdvanceFrame(animationTime = this.#animationTime) {
-      this.#frameCounter++;
-      this.#previousAnimationTime = this.#animationTime;
-      this.#animationTime = Number(animationTime) || 0;
-      return this;
-    }
-
-    // Carbon Tr2Renderer::BeginFrame (Tr2Renderer.cpp:1040-1051): publishes the
-    // "Time" vector every consumer reads - x is the animation time, y its
-    // fractional part (a free 0..1 sawtooth for shaders), z the frame counter,
-    // and w the PREVIOUS frame's animation time, which is what makes a shader
-    // able to compute its own delta. Carbon registers this on the global store
-    // (cpp:329), and Tr2VariableStore.GlobalStore() is the same root here.
-
-    /**
-     * Publishes the per-frame "Time" vector into the global variable store, as
-     * Carbon does at the start of every frame; returns the published vector.
+     * Opens the backend's scene for this frame.
+     *
+     * @returns {*} Whatever the backend returns; the stub returns true.
      */
-    BeginFrame() {
-      const animationTime = this.#animationTime;
-      const time = [animationTime, animationTime - Math.floor(animationTime), this.#frameCounter, this.#previousAnimationTime];
-      _Tr2VariableStore.GlobalStore().RegisterVariable("Time", time);
-      return time;
+    BeginScene() {
+      return this.#requireAL("BeginScene").BeginScene();
     }
 
-    // Carbon Tr2Renderer::EndFrame (Tr2Renderer.cpp:1053-1064) clears the debug
-    // text renderer and the debug line set, both Tr2Renderer statics. Only the
-    // debug renderer has a counterpart here (SetDebugRenderer); Carbon's global
-    // debug line set has no Trinity surface, so nothing stands in for it.
-
     /**
-     * Ends the frame, clearing the installed debug renderer; returns this for
-     * chaining.
-     */
-    EndFrame() {
-      // `SetDebugRenderer` takes whatever a render job hands it, and Carbon's
-      // own type (`Tr2DebugTextRenderer`) is not ported, so this is a foreign
-      // object. Asked explicitly rather than hedged, because the question really
-      // is "does this thing clear" and not "is one of our classes incomplete".
-      if (typeof this.#debugRenderer?.Clear === "function") this.#debugRenderer.Clear();
-      return this;
-    }
-
-    // Carbon Tr2Renderer::BeginRenderContext (Tr2Renderer.cpp:1066-1070) forwards
-    // to the backend context's BeginScene. The GPU-free context records the
-    // intent; an installed executor performs it.
-
-    /**
-     * Opens the scene for this frame, recording the intent and delegating to an
-     * installed executor's BeginScene; returns this for chaining.
+     * Closes the backend's scene, submitting whatever it recorded.
+     *
+     * @returns {*} Whatever the backend returns; WebGPU's returns a promise.
      */
-    BeginRenderContext() {
-      this.#stepExecutor.BeginScene(this);
-      return this;
+    EndScene() {
+      return this.#requireAL("EndScene").EndScene();
     }
 
     // Carbon: Tr2Renderer::GetPoolAllocator (Tr2Renderer.cpp:1083). The store
@@ -310,26 +254,6 @@ new class extends _identity {
       return this;
     }
 
-    // Carbon clears the pool in Tr2Renderer::EndRenderContext (cpp:1072-1081),
-    // BEFORE EndScene, so every transient payload leased during the frame dies at
-    // one point. The frame driver calls this; nothing else may. EndScene is the
-    // required final operation even when resetting the transient pool throws.
-
-    /**
-     * Clears the per-object pool arena at the end of a frame, freeing every
-     * transient payload leased during it (Carbon calls TriPoolAllocator::Clear
-     * here, Tr2Renderer.cpp:1072-1081); a context that never leased one does
-     * nothing.
-     */
-    EndRenderContext() {
-      try {
-        this.#poolAllocator?.Clear();
-      } finally {
-        this.#stepExecutor.EndScene(this);
-      }
-      return this;
-    }
-
     /**
      * Saves the target currently bound to a slot, and binds a new one if given.
      *
@@ -404,10 +328,10 @@ new class extends _identity {
       return this.#requireAL("SetRenderTarget").SetRenderTarget(Number(slot) >>> 0, renderTarget, Number(slice) >>> 0);
     }
 
-    // THE BACKEND'S FRAME CLOCK, WHICH IS NOT THE ONE ABOVE. `AdvanceFrame` and
-    // `GetCurrentFrameCounter` are Trinity's - frames the render path has begun,
-    // driven by the frame driver. These two are the DEVICE's, and the gap between
-    // them is what a ring buffer fences against: rows recorded for a frame cannot
+    // THE BACKEND'S FRAME CLOCK, WHICH IS NOT TRINITY'S.
+    // `Tr2Renderer.GetCurrentFrameCounter` counts frames the render path has
+    // begun. These two count frames the BACKEND has recorded and retired, and the
+    // gap between them is what a ring buffer fences against: rows recorded for a frame cannot
     // be reused until the device reports that frame finished. Carbon keeps them
     // per backend (`Tr2PrimaryRenderContextDx11.h:46-47`), so they are the
     // abstraction layer's to answer and this only forwards.
@@ -728,7 +652,7 @@ new class extends _identity {
      * context; equal descriptions are one state. Created at effect load
      * (`Tr2EffectDescription.cpp:436`) and for sampler overrides
      * (`Tr2Effect.cpp:690`), both through the main-thread context, which is
-     * `GetDefault()` here.
+     * `Tr2RenderContext_GetMainThreadRenderContext()` here.
      *
      * @param {object} description A `Tr2SamplerDescription`.
      * @returns {object|null} A `Tr2SamplerStateAL`, shared, or null.
@@ -1268,6 +1192,19 @@ new class extends _identity {
       return true;
     }
 
+    /**
+     * The debug renderer installed on this context, or null.
+     *
+     * Carbon has no getter because its equivalent is a `Tr2Renderer` static the
+     * clearing code reads directly; ours lives here, so `Tr2Renderer.EndFrame`
+     * needs a way to reach it.
+     *
+     * @returns {object|null} The installed debug renderer.
+     */
+    GetDebugRenderer() {
+      return this.#debugRenderer;
+    }
+
     /**
      * Ends the frame at the device level.
      *
@@ -1613,11 +1550,13 @@ new class extends _identity {
     }
 
     /**
-     * The process-wide fallback context, constructed once when the class is
-     * defined, for callers with no context of their own.
+     * Releases the main-thread render context, as Carbon does
+     * (`Tr2RenderContext.cpp:310-318`). The next reach for it builds a new one.
+     *
+     * @returns {void}
      */
-    static GetDefault() {
-      return _Tr2RenderContext.#defaultContext;
+    static DestroyMainThreadRenderContext() {
+      s_mainThreadRenderContext = null;
     }
 
     /**
@@ -1677,11 +1616,30 @@ new class extends _identity {
     TA_BORDER: 4,
     TA_MIRROR_ONCE: 5
   });
-  #defaultContext = new _Tr2RenderContext();
   constructor() {
     super(_Tr2RenderContext), _initClass();
   }
-}();
+}(); // Source: trinity/trinity/Tr2RenderContext.cpp:300-329
+let s_mainThreadRenderContext = null;
+
+/**
+ * The main-thread render context, created on first reach.
+ *
+ * Carbon guards this with a macro (`USE_MAIN_THREAD_RENDER_CONTEXT`) whose
+ * whole purpose is to make the site visible, and its header says why: if you
+ * are tempted to call this, first make sure no context is available higher up
+ * the callstack, and pass that one down instead. The same applies here. The
+ * legitimate callers are the `Tr2Renderer` frame statics and `TriDevice`,
+ * because Carbon's are the same ones.
+ *
+ * @returns {Tr2RenderContext} The process-wide context, never null.
+ */
+function Tr2RenderContext_GetMainThreadRenderContext() {
+  if (!s_mainThreadRenderContext) {
+    s_mainThreadRenderContext = new _Tr2RenderContext();
+  }
+  return s_mainThreadRenderContext;
+}
 
-export { _Tr2RenderContext as Tr2RenderContext };
+export { _Tr2RenderContext as Tr2RenderContext, Tr2RenderContext_GetMainThreadRenderContext };
 //# sourceMappingURL=Tr2RenderContext.js.map