FabricatePassChainBuilder.kt

fun StandardRenderer.Bundle.addPassChain(
    passes: List<FabricatePassSpec>,
    renderer: Renderer = fromContext(),
    printReport: Boolean = false
): FabricateBuiltChain {
    val chainInput = inputBeforeReplacement(
        entries = postStack.effects().map { it.name to it.target },
        replacing = passes.map { it.name }.toSet(),
        initialInput = postStack.input
    )
    val plan = FabricatePassChain.plan(
        passes = passes,
        inputWidth = chainInput.width,
        inputHeight = chainInput.height,
        inputFormat = chainInput.colorFormats.firstOrNull() ?: chainInput.parameters.format
    )
    if (printReport) println(plan.report())

    val effects = arrayOfNulls<FabricatePostEffect>(plan.passes.size)

    // A persistent pass's previous frame may be read by a pass that runs *before* it, so its target
    // has to exist before the walk reaches it. Allocating every ping-pong target up front is what
    // makes that reference resolvable at all; the planner already guaranteed the shapes do not
    // depend on anything the walk computes.
    val persistentTargets = plan.persistentPasses.associate { pass ->
        // Reuse the ping-pong pair a previous run of this same declaration left behind, when the
        // shape still matches. For a persistent pass the target *is* the state, so this is the
        // difference between re-running the box and keeping your fluid, and re-running it and
        // silently starting from an empty one while leaking the old pair.
        val carried = (postStack[pass.name]?.target as? PingPongRenderToTexture)?.takeIf { old ->
            old.width == pass.shape.width &&
                    old.height == pass.shape.height &&
                    (old.colorFormats.firstOrNull() ?: old.parameters.format) == pass.shape.format
        }
        pass.index to (carried ?: PingPongRenderToTexture(
            renderer,
            FabricatePassChain.PERSISTENT_IMAGE_COUNT,
            postEffectTargetParameters(pass.name, pass.shape) {
                // A simulation field is not an image that gets redrawn from scratch; clearing it
                // every frame would be clearing the state. Every pass writing one is fullscreen, so
                // there is nothing a per-frame clear would cover that the pass does not.
                clearFirst = false
                // It does have to be cleared *once*, though, and this is what buys that:
                // PingPongRenderToTexture.initializePingImagesNow clears every image in the ring at
                // construction only if the image carries TRANSFER_DST usage, and otherwise just
                // transitions the layout and leaves the contents undefined. Frame zero of a
                // simulation then advects whatever was in that memory — which on a warm GPU is
                // often plausible-looking noise rather than an obvious failure, and which does not
                // reproduce.
                colorTransferDst = true
            }
        ))
    }

    fun textureFor(ref: FabricatePassRef): RenderToTexture = when (ref) {
        FabricatePassRef.ChainInput -> chainInput
        is FabricatePassRef.Pass -> requireNotNull(effects[ref.index]) {
            "pass '${ref.name}' has not been built yet"
        }.target
        is FabricatePassRef.PreviousFrame -> persistentTargets.getValue(ref.index)
        // The planner refuses an external reference as a pass's source, so this is unreachable
        // rather than merely unused: an external texture binds a view, never a target.
        is FabricatePassRef.External -> throw IllegalStateException(
            "'${ref.reference}' binds as a view, not as a target — the planner should have refused it " +
                    "as a source before the build got here"
        )
    }

    /**
     * Refs that bind a *view* rather than a target: a previous-frame ref binds the half of the
     * ping-pong pair that is not being written, and an external ref binds a texture the renderer
     * owns outright.
     *
     * The g-buffer's motion vectors are colour attachment **3**, and its depth prefers the sampled
     * view, which is what the shadow-map and depth-blit paths in `standardRenderer` already do.
     */
    fun viewFor(ref: FabricatePassRef): HasImageView? = when (ref) {
        is FabricatePassRef.PreviousFrame -> persistentTargets.getValue(ref.index).otherImageView
        is FabricatePassRef.External -> when (ref.reference) {
            FabricatePassChain.GBUFFER_MOTION -> {
                require(gBuffer.width == chainInput.width && gBuffer.height == chainInput.height) {
                    "a pass asked for '${FabricatePassChain.GBUFFER_MOTION}', whose vectors are in the " +
                            "g-buffer's UV space at ${gBuffer.width}x${gBuffer.height}, but this chain's " +
                            "input is ${chainInput.width}x${chainInput.height} — sampling one by the " +
                            "other's coordinates reprojects to the right fraction of the wrong picture, " +
                            "which renders and merely looks soft"
                }
                requireNotNull(gBuffer.imageViewArray.getOrNull(GBUFFER_MOTION_ATTACHMENT)) {
                    "the g-buffer has ${gBuffer.imageViewArray.size} colour attachments, and the motion " +
                            "vectors are attachment $GBUFFER_MOTION_ATTACHMENT"
                }
            }
            FabricatePassChain.GBUFFER_DEPTH -> requireNotNull(
                gBuffer.depthSampledImageView ?: gBuffer.depthImageView
            ) {
                "the g-buffer exposes no sampleable depth view, so '${FabricatePassChain.GBUFFER_DEPTH}' " +
                        "cannot be bound"
            }
            else -> throw IllegalArgumentException("unknown external reference '${ref.reference}'")
        }
        else -> null
    }

    // One FrameHistory per chain, not per pass. Every pass that declares `frameHistory` binds
    // against this same object, and `FrameHistory.capture` is idempotent for a frame id it already
    // stands at — so whichever pass's push constant is written first advances the history and the
    // rest see the same answer. Per-pass histories would make each pass reproject against the
    // *previous pass* instead of the previous frame, and the ghost that produces looks like a
    // slightly soft image rather than like a bug.
    //
    // Fresh per build, deliberately. A rebuild carries the persistent *target* (see above) but not
    // the history, so the frame after a rebuild reports unavailable and the accumulation restarts
    // once. That is the right answer rather than a limitation: the thing that was rebuilt may be the
    // shader, the resolution or the camera wiring, and none of those leave last frame comparable.
    val history = FrameHistory()

    // Scratch, reused every frame. The binding below runs inside the render loop, where allocating a
    // matrix per pass per frame is a real cost and an avoidable one.
    val viewProjection = Matrix4f()

    plan.passes.forEach { pass ->
        val primary = pass.inputs.first()
        val extras = pass.inputs.drop(1)
        val effect = addShaderEffect(
            name = pass.name,
            fragment = pass.spec.fragment,
            renderer = renderer,
            // Already resolved by the planner. Handing Absolute back deliberately: the builder must
            // not get a second chance to compute a size.
            size = FabricatePassSize.Absolute(pass.shape.width, pass.shape.height),
            format = pass.shape.format,
            source = textureFor(primary.from),
            extraInputs = extras.filter { viewFor(it.from) == null }
                .associate { it.samplerName to textureFor(it.from) },
            mipLevels = pass.shape.mipLevels,
            pingPong = pass.persistent,
            sourceView = viewFor(primary.from),
            extraViews = extras.mapNotNull { input -> viewFor(input.from)?.let { input.samplerName to it } }.toMap(),
            existingTarget = persistentTargets[pass.index]
        )
        effects[pass.index] = effect
        pass.spec.push.forEach { (name, value) -> effect.setPush(name, value) }

        if (pass.frameHistory) {
            // Bound, not set: `Structure.bind` keeps the supplier and re-invokes it every time the
            // push-constant buffer is written, which is once per pass per frame. A value written
            // here at build time would be last frame's camera forever.
            //
            // `capture` is called from inside the binding rather than from a frame callback on
            // purpose. There is no "start of frame" hook that is guaranteed to run before the first
            // pass writes its constants, and a capture that lands *after* a pass has already read
            // the history is a one-frame-stale reprojection that looks like a slightly wrong motion
            // vector. Calling it from the binding makes the first reader the one that advances it,
            // and idempotence makes every later reader agree.
            effect.setPushBinding("reprojection") {
                history.capture(
                    frameId = renderer.frameCounter,
                    viewProjection = currentViewProjection(viewProjection),
                    width = chainInput.width,
                    height = chainInput.height,
                    epoch = frameHistoryEpoch
                )
                history.reprojection
            }
            effect.setPushBinding("historyParams") {
                history.capture(
                    frameId = renderer.frameCounter,
                    viewProjection = currentViewProjection(viewProjection),
                    width = chainInput.width,
                    height = chainInput.height,
                    epoch = frameHistoryEpoch
                )
                history.params()
            }
        }
    }

    return FabricateBuiltChain(plan, effects.map { requireNotNull(it) }, chainInput, history)
}