@carbonenginejs/runtime-trinity 0.6.0 → 0.8.0

package/dist/trinityCore/Tr2RenderContext.js

@@ -41,28 +41,53 @@ new class extends _identity {
     #projectionStack = [];
     #viewTransformStack = [];
     #intentCursor = 0;
+    /**
+     * Installs the optional executor that Begin/Execute/EndStep delegate to;
+     * passing null restores direct dispatch to the step itself.
+     */
     SetStepExecutor(executor) {
       this.#stepExecutor = executor ?? null;
       return this;
     }
+
+    /**
+     * Delegates to the installed step executor when it implements BeginStep,
+     * otherwise calls the step's own BeginExecute.
+     */
     BeginStep(step, realTime, simTime, job) {
       if (this.#stepExecutor?.BeginStep) {
         return this.#stepExecutor.BeginStep(step, realTime, simTime, job, this);
       }
       return step?.BeginExecute?.(this);
     }
+
+    /**
+     * Delegates to the installed step executor when it implements ExecuteStep,
+     * otherwise calls the step's own Execute with the frame times.
+     */
     ExecuteStep(step, realTime, simTime, job) {
       if (this.#stepExecutor?.ExecuteStep) {
         return this.#stepExecutor.ExecuteStep(step, realTime, simTime, job, this);
       }
       return step?.Execute?.(realTime, simTime, this);
     }
+
+    /**
+     * Delegates to the installed step executor when it implements EndStep,
+     * otherwise calls the step's own EndExecute.
+     */
     EndStep(step, realTime, simTime, job) {
       if (this.#stepExecutor?.EndStep) {
         return this.#stepExecutor.EndStep(step, realTime, simTime, job, this);
       }
       return step?.EndExecute?.(this);
     }
+
+    /**
+     * Pushes a render target onto the balance-guard stack for one slot, creating
+     * that slot's stack on first use; it records no intent, only SetRenderTarget
+     * does.
+     */
     PushRenderTarget(renderTarget = null, slot = 0) {
       const index = Number(slot) >>> 0;
       let stack = this.#renderTargetStacks.get(index);
@@ -73,23 +98,44 @@ new class extends _identity {
       stack.push(renderTarget);
       return true;
     }
+
+    /**
+     * Pops the top render target off one slot's stack, or null when that stack is
+     * empty.
+     */
     PopRenderTarget(slot = 0) {
       const stack = this.#renderTargetStacks.get(Number(slot) >>> 0);
       return stack?.length ? stack.pop() : null;
     }
+
+    /** Depth of one slot's render-target stack; zero for a slot never pushed to. */
     GetStackSizeRT(slot = 0) {
       return this.#renderTargetStacks.get(Number(slot) >>> 0)?.length ?? 0;
     }
+
+    /**
+     * Pushes a depth-stencil onto the balance-guard stack; it records no intent,
+     * only SetDepthStencil does.
+     */
     PushDepthStencil(depthStencil = null) {
       this.#depthStencilStack.push(depthStencil);
       return true;
     }
+
+    /** Pops the top depth-stencil, or null when the stack is empty. */
     PopDepthStencil() {
       return this.#depthStencilStack.length ? this.#depthStencilStack.pop() : null;
     }
+
+    /** Depth of the depth-stencil stack. */
     GetStackSizeDS() {
       return this.#depthStencilStack.length;
     }
+
+    /**
+     * Binds a render target to a slot and records a set-render-target intent for
+     * the engine to realize.
+     */
     SetRenderTarget(slot, renderTarget) {
       const index = Number(slot) >>> 0;
       this.#renderTargets.set(index, renderTarget ?? null);
@@ -100,9 +146,16 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * The render target currently bound to a slot, or null when that slot was
+     * never set.
+     */
     GetRenderTarget(slot = 0) {
       return this.#renderTargets.get(Number(slot) >>> 0) ?? null;
     }
+
+    /** Binds the depth-stencil surface and records a set-depth-stencil intent. */
     SetDepthStencil(depthStencil) {
       this.#depthStencil = depthStencil ?? null;
       this.#intents.push({
@@ -111,9 +164,17 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** The currently bound depth-stencil surface, or null. */
     GetDepthStencil() {
       return this.#depthStencil;
     }
+
+    /**
+     * Records a clear intent with separate colour, depth and stencil enables; the
+     * colour is snapshotted by value so a caller's reusable buffer cannot mutate
+     * the queued intent.
+     */
     Clear(options) {
       const intent = {
         type: "clear",
@@ -127,9 +188,16 @@ new class extends _identity {
       this.#intents.push(intent);
       return true;
     }
+
+    /** GPU-free validity check: any non-null render target counts as valid. */
     IsRenderTargetValid(renderTarget) {
       return renderTarget != null;
     }
+
+    /**
+     * Records a resolve intent moving a multisampled source into a resolved
+     * destination.
+     */
     ResolveRenderTarget(source, destination) {
       this.#intents.push({
         type: "resolve-render-target",
@@ -138,6 +206,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a copy-render-target intent, spreading the caller's descriptor
+     * fields into it.
+     */
     CopyRenderTarget(intent) {
       this.#intents.push({
         type: "copy-render-target",
@@ -145,6 +218,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records a generate-mipmaps intent for a render target. */
     GenerateMipMaps(renderTarget) {
       this.#intents.push({
         type: "generate-mipmaps",
@@ -152,6 +227,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a render-object intent naming a renderable, with any extra options
+     * merged into the intent.
+     */
     RenderObject(renderable, options = {}) {
       this.#intents.push({
         type: "render-object",
@@ -160,6 +240,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a full-screen draw-effect intent; the two texture-coordinate corners
+     * are copied by value so caller buffers can be reused.
+     */
     DrawEffect(effect, shaderBuffer = null, tlTexCoord = null, brTexCoord = null) {
       this.#intents.push({
         type: "draw-effect",
@@ -170,6 +255,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records a draw-line-set intent referencing the line set. */
     DrawLineSet(lineSet) {
       this.#intents.push({
         type: "draw-line-set",
@@ -177,6 +264,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a clear-unordered-access-view intent; the clear value is copied by
+     * value and clearWithFloat selects float rather than integer clearing.
+     */
     ClearUav(buffer, value, clearWithFloat = false) {
       this.#intents.push({
         type: "clear-uav",
@@ -186,6 +278,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records a render-atlas intent for an atlas step. */
     RenderAtlas(step) {
       this.#intents.push({
         type: "render-atlas",
@@ -193,6 +287,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records a render-line-graphs intent for a line-graph step. */
     RenderLineGraphs(step) {
       this.#intents.push({
         type: "render-line-graphs",
@@ -200,6 +296,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a render-texture intent for a source texture, with any extra options
+     * merged into the intent.
+     */
     RenderTexture(source, options = {}) {
       this.#intents.push({
         type: "render-texture",
@@ -208,6 +309,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a render-debug intent, deep-copying the step's line vertices and its
+     * 2D and 3D text entries so the debug step can be refilled immediately.
+     */
     RenderDebug(debugStep) {
       this.#intents.push({
         type: "render-debug",
@@ -225,6 +331,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a compute-dispatch intent with an explicit thread-group count per
+     * axis.
+     */
     RunComputeShader(effect, groupDimX = 1, groupDimY = 1, groupDimZ = 1) {
       this.#intents.push({
         type: "run-compute-shader",
@@ -235,6 +346,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records an indirect compute-dispatch intent reading its group counts from a
+     * buffer at the given byte offset.
+     */
     RunComputeShaderIndirect(effect, indirectionBuffer, offsetForArgs = 0) {
       this.#intents.push({
         type: "run-compute-shader-indirect",
@@ -244,6 +360,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records the upscaler context the following work belongs to. */
     SetUpscalingContextID(upscalingContextID) {
       this.#intents.push({
         type: "set-upscaling-context-id",
@@ -251,6 +369,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records the debug renderer to route subsequent debug drawing through; null
+     * detaches it.
+     */
     SetDebugRenderer(renderer) {
       this.#intents.push({
         type: "set-debug-renderer",
@@ -258,6 +381,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records the end-of-frame present intent for a swap chain. */
     PresentSwapChain(swapChain) {
       this.#intents.push({
         type: "present-swap-chain",
@@ -265,6 +390,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Caches the viewport and records a set-viewport intent; the viewport object
+     * is held by reference, not copied.
+     */
     SetViewport(viewport) {
       this.#viewport = viewport ?? null;
       this.#intents.push({
@@ -273,6 +403,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Clears the cached viewport and records a fullscreen-viewport intent, leaving
+     * the engine to resolve the actual target extent.
+     */
     SetFullScreenViewport() {
       this.#viewport = null;
       this.#intents.push({
@@ -280,6 +415,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * The viewport last set, or null while the context is in fullscreen-viewport
+     * mode.
+     */
     GetViewport() {
       return this.#viewport;
     }
@@ -288,10 +428,20 @@ new class extends _identity {
     // step calls these with no argument: push saves the current viewport, pop
     // restores it and re-records the set-viewport intent so realization sees the
     // restored value. Independent of the RT/DS balance-guard stacks.
+
+    /**
+     * Saves the current viewport on its own save/restore stack, independent of the
+     * render-target and depth-stencil balance guards.
+     */
     PushViewport() {
       this.#viewportStack.push(this.#viewport);
       return true;
     }
+
+    /**
+     * Restores the last pushed viewport and re-records a set-viewport intent so
+     * realization sees the restored value; returns false when the stack is empty.
+     */
     PopViewport() {
       if (!this.#viewportStack.length) return false;
       this.#viewport = this.#viewportStack.pop();
@@ -301,9 +451,16 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Depth of the viewport save/restore stack. */
     GetStackSizeViewport() {
       return this.#viewportStack.length;
     }
+
+    /**
+     * Caches the view/camera/simTime record, refreshes the cached view matrix and
+     * its inverse from the view matrix, and records a set-view intent.
+     */
     SetView(view, camera = null, simTime = 0) {
       this.#view = {
         view: view ?? null,
@@ -317,6 +474,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Caches a raw view matrix (Tr2Renderer::SetViewTransform), refreshes the
+     * inverse and eye position, and records a set-view-transform intent.
+     */
     SetViewTransform(transform, source = null) {
       this.#view = {
         transform: transform ?? null,
@@ -333,6 +495,13 @@ new class extends _identity {
     // Mirrors Tr2Renderer::SetViewTransform: cache the view matrix, compute its
     // inverse once, and derive the view position from the inverse-view
     // translation row (Carbon reads _41.._43 -> column-major indices [12,13,14]).
+
+    /**
+     * Mirrors Tr2Renderer::SetViewTransform - copies the view matrix into the
+     * cached buffer, inverts it once (falling back to identity when singular) and
+     * derives the eye position from the inverse-view translation; anything that is
+     * not a 16-element matrix is ignored and leaves the cache untouched.
+     */
     #ApplyViewMatrix(matrix) {
       if (!matrix || matrix.length !== 16) {
         return;
@@ -344,6 +513,11 @@ new class extends _identity {
       vec3.set(this.#viewPosition, this.#inverseViewTransform[12], this.#inverseViewTransform[13], this.#inverseViewTransform[14]);
       this.#hasViewMatrix = true;
     }
+
+    /**
+     * A shallow copy of the last view or view-transform record, or null when none
+     * has been set.
+     */
     GetView() {
       return this.#view ? {
         ...this.#view
@@ -352,24 +526,44 @@ new class extends _identity {
 
     // Raw column-major view matrix (Tr2Renderer::GetViewTransform). Live buffer -
     // callers read, never mutate.
+
+    /**
+     * The raw column-major view matrix (Tr2Renderer::GetViewTransform); a live
+     * buffer owned by the context that callers read and never mutate.
+     */
     GetViewTransform() {
       return this.#viewTransform;
     }
 
     // Inverse of the view matrix (Tr2Renderer::GetInverseViewTransform), cached on
     // the last view change. Live buffer - callers read, never mutate.
+
+    /**
+     * The inverse view matrix (Tr2Renderer::GetInverseViewTransform), recomputed
+     * on each view change; a live buffer callers read and never mutate.
+     */
     GetInverseViewTransform() {
       return this.#inverseViewTransform;
     }
 
     // World-space view/eye position (Tr2Renderer::GetViewPosition): the
     // inverse-view translation. Live buffer - callers read, never mutate.
+
+    /**
+     * The world-space eye position taken from the inverse-view translation; a live
+     * buffer callers read and never mutate.
+     */
     GetViewPosition() {
       return this.#viewPosition;
     }
 
     // Whether a view matrix has been set (camera-dependent modifiers fall back to
     // an unchanged transform when it has not).
+
+    /**
+     * Whether a view matrix has been set; camera-dependent modifiers fall back to
+     * an unchanged transform when it has not.
+     */
     HasViewMatrix() {
       return this.#hasViewMatrix;
     }
@@ -377,6 +571,12 @@ new class extends _identity {
     // Save/restore stack for the cached view transform (Carbon Push/PopViewTransform).
     // Push snapshots the current view object, its matrix, and the has-matrix flag;
     // pop restores them and re-derives the inverse/eye-position via ApplyViewMatrix.
+
+    /**
+     * Snapshots the current view record, its matrix and the has-matrix flag onto
+     * the view-transform stack, copying the matrix rather than aliasing the live
+     * buffer.
+     */
     PushViewTransform() {
       this.#viewTransformStack.push({
         view: this.#view,
@@ -385,6 +585,13 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Restores the last pushed view transform, re-deriving the inverse and eye
+     * position (or resetting them to identity when nothing was cached), and
+     * re-records a set-view-transform intent; returns false when the stack is
+     * empty.
+     */
     PopViewTransform() {
       if (!this.#viewTransformStack.length) return false;
       const saved = this.#viewTransformStack.pop();
@@ -403,9 +610,16 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Depth of the view-transform save/restore stack. */
     GetStackSizeViewTransform() {
       return this.#viewTransformStack.length;
     }
+
+    /**
+     * Caches the projection and records a set-projection intent; the projection
+     * object is held by reference.
+     */
     SetProjection(projection) {
       this.#projection = projection ?? null;
       this.#intents.push({
@@ -414,6 +628,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records a single render-state assignment; both state and value are coerced
+     * to unsigned integers.
+     */
     SetRenderState(state, value) {
       this.#intents.push({
         type: "set-render-state",
@@ -422,6 +641,8 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Records the intent to apply the standard state block for a rendering mode. */
     ApplyStandardStates(renderingMode) {
       this.#intents.push({
         type: "apply-standard-states",
@@ -429,6 +650,11 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * Records the wireframe toggle for the engine to read at realization; the
+     * context itself draws nothing.
+     */
     SetWireframeRendering(enabled) {
       this.#intents.push({
         type: "set-wireframe-rendering",
@@ -436,15 +662,27 @@ new class extends _identity {
       });
       return true;
     }
+
+    /**
+     * The projection matrix last recorded on the context, or null before a pass
+     * sets one.
+     */
     GetProjection() {
       return this.#projection;
     }
 
     // Save/restore stack for the current projection (Carbon Push/PopProjection).
+
+    /** Saves the current projection on its own save/restore stack. */
     PushProjection() {
       this.#projectionStack.push(this.#projection);
       return true;
     }
+
+    /**
+     * Restores the last pushed projection and re-records a set-projection intent;
+     * returns false when the stack is empty.
+     */
     PopProjection() {
       if (!this.#projectionStack.length) return false;
       this.#projection = this.#projectionStack.pop();
@@ -454,9 +692,16 @@ new class extends _identity {
       });
       return true;
     }
+
+    /** Depth of the projection save/restore stack. */
     GetStackSizeProjection() {
       return this.#projectionStack.length;
     }
+
+    /**
+     * A full copy of every intent recorded since the last ClearIntents; it does
+     * not move the take-cursor, so intents can be returned again.
+     */
     GetIntents() {
       return this.#intents.slice();
     }
@@ -465,6 +710,12 @@ new class extends _identity {
     // returns the intents recorded since the previous TakeIntents/ClearIntents and
     // advances the cursor. Unlike GetIntents (a full copy), the same intent is
     // never returned twice, so nested jobs cannot realize an intent more than once.
+
+    /**
+     * Exactly-once consumption for a per-step executor: returns the intents
+     * recorded since the previous take and advances the cursor, so no intent can
+     * be realized twice.
+     */
     TakeIntents() {
       const taken = this.#intents.slice(this.#intentCursor);
       this.#intentCursor = this.#intents.length;
@@ -472,25 +723,45 @@ new class extends _identity {
     }
 
     // Peek at the intents since the cursor without advancing it.
+
+    /** The intents recorded since the cursor, without advancing it. */
     PeekIntents() {
       return this.#intents.slice(this.#intentCursor);
     }
+
+    /** Index of the first intent not yet consumed by TakeIntents. */
     GetIntentCursor() {
       return this.#intentCursor;
     }
+
+    /** Drops all recorded intents and rewinds the take-cursor to zero. */
     ClearIntents() {
       this.#intents.length = 0;
       this.#intentCursor = 0;
     }
+
+    /**
+     * Appends a diagnostic record for the frame; diagnostics are independent of
+     * the intent stream and cleared separately.
+     */
     AddDiagnostic(diagnostic) {
       this.#diagnostics.push(diagnostic);
     }
+
+    /** A copy of the diagnostics recorded since the last ClearDiagnostics. */
     GetDiagnostics() {
       return this.#diagnostics.slice();
     }
+
+    /** Drops all recorded diagnostics. */
     ClearDiagnostics() {
       this.#diagnostics.length = 0;
     }
+
+    /**
+     * The process-wide fallback context, constructed once when the class is
+     * defined, for callers with no context of their own.
+     */
     static GetDefault() {
       return _Tr2RenderContext.#defaultContext;
     }