@JvmStatic
    fun main(args: Array<String>) {
        Options.enableVR = false
        val out = File(EVIDENCE_DIR)
        out.mkdirs()

        val window = Window("GPU Skinning Evidence")
        val renderer = Renderer(window)
        try {
            val rt = RenderTarget(renderer)
            renderer.renderList = rt

            val path = RiggedFixture.locate()
            val model = GltfSupport.loadGltfBasic(path, GltfSupport.GltfLoadConfig(loadTextures = false))
            val instance = model.meshes.first { it.skin != null }

            val module = Module(
                Parameters(
                    renderer = renderer,
                    vertex = GpuSkinning.skinnedVertexShader,
                    fragment = GpuSkinning.skinnedFragmentShader,
                    name = "gpu-skinning-evidence",
                )
            )
            rt += "skinned" to module
            val pointer = module.pointer()
            val mesh = Mesh(renderer, pointer)
            module += "character" to mesh

            val camera = Camera(renderer)
            val skinner = GpuSkinner(instance, instances = CROWD, renderer = renderer, name = "evidence")
            val cpu = CpuSkinner(instance)

            println("fixture   : $path")
            println("mesh      : ${instance.name}, ${skinner.vertexCount} vertices, ${skinner.boneCount} bones")
            println("clips     : ${skinner.clips}")
            println("output    : ${out.absolutePath}")
            println()

            if ("--twist-only" in args) {
                // Only the dual-quaternion section, so re-deriving it does not rewrite the
                // linear-blend evidence that was committed from an earlier run.
                twist(renderer, window, mesh, camera, skinner, cpu, instance, out)
                println()
                println("gpu skinning evidence written (twist section only)")
                renderer.cleanup()
                window.cleanup()
                exitProcess(0)
            }

            // ---------------------------------------------------------------- one character
            frameSingle(camera)
            skinner.bindTo(mesh, camera, instanceCount = 1, tint = false)

            var worstDiff = 0.0
            for (t in listOf(0f, 0.5f, 1f)) {
                val label = "bend_t%03d".format((t * 100).toInt())
                worstDiff = maxOf(
                    worstDiff,
                    pair(renderer, window, mesh, camera, skinner, cpu, instance, out, label) {
                        skinner.uploadPalette(skinner.placedPalette(Matrix4f(), "bend", t))
                        cpu.pose("bend", t)
                    }
                )
            }

            // A blend of two clips, which the CPU path can also do, so it can be differenced too.
            worstDiff = maxOf(
                worstDiff,
                pair(renderer, window, mesh, camera, skinner, cpu, instance, out, "blend_bend_curl") {
                    val sk = skinner.skin.skeleton
                    skinner.uploadPalette(
                        skinner.blendedPalette(Matrix4f(), "bend", 1f, "curl", 1f, mix = 0.5f)
                    )
                    cpu.pose(sk.blendedPalette(sk.clip("bend"), 1f, sk.clip("curl"), 1f, 0.5f))
                }
            )

            println()
            println("worst mean pixel difference over all GPU/CPU pairs: %.4f / 255".format(worstDiff))
            if (worstDiff > PIXEL_TOL) {
                println(
                    "FAIL: the GPU frame and the CPU frame are not the same picture " +
                        "($worstDiff > $PIXEL_TOL mean levels)"
                )
                exitProcess(1)
            }
            println("the GPU-skinned frame and the CPU-skinned frame are the same picture.")

            // ---------------------------------------------------------------- the control
            //
            // The pairs above came back *bit-identical*, and that is exactly the result a
            // completely dead comparison would give. If `skinEnabled` were being ignored, or if
            // the second capture were returning a stale frame, both PNGs would be the GPU frame
            // and the difference would be zero for the wrong reason.
            //
            // So: render the same camera with skinning off and the *bind pose* in the buffer.
            // That must be a visibly different picture. If it is not, nothing above means
            // anything, and this fails loudly rather than letting a zero speak for itself.
            println()
            control(renderer, window, mesh, skinner, out)

            // ---------------------------------------------------------------- the crowd
            println()
            crowd(renderer, window, mesh, camera, skinner, out)

            // ---------------------------------------------------------------- the candy wrapper
            println()
            twist(renderer, window, mesh, camera, skinner, cpu, instance, out)

            println()
            println("gpu skinning evidence written")
        } finally {
            renderer.cleanup()
            window.cleanup()
        }
        exitProcess(0)
    }

    private fun control(
        renderer: Renderer,
        window: Window,
        mesh: Mesh,
        skinner: GpuSkinner,
        out: File,
    ) {
        skinner.restoreBindPose(mesh)          // bind pose back into the GPU buffer
        mesh.push["skinEnabled"] = 0           // ... and do not skin it
        val bind = capture(renderer, window, File(out, "control_unskinned.png"))
        val d = difference(bind, File(out, "gpu_bend_t100.png"), File(out, "diff_control.png"))
        println(
            "  %-18s mean |unskinned - gpu bend| %.4f levels   max %d".format(
                "control_unskinned", d.mean, d.max
            )
        )
        if (d.mean < CONTROL_MIN) {
            println(
                "  FAIL: turning skinning off changed the picture by only ${d.mean} levels. " +
                    "Either skinEnabled is being ignored or the capture is returning a stale " +
                    "frame -- so the zero difference between the GPU and CPU frames above is " +
                    "not evidence of anything."
            )
            exitProcess(1)
        }
        println("  control passed: the pipeline does produce a different picture when asked to.")
        skinner.restoreBindPose(mesh)
    }

    private fun crowd(
        renderer: Renderer,
        window: Window,
        mesh: Mesh,
        camera: Camera,
        skinner: GpuSkinner,
        out: File,
    ) {
        camera.p.orthoness = 0.25
        camera.p.matchDepth = 2.0
        camera.target = Vector3f(0f, 2f, 0f)
        camera.at = Vector3f(6.5f, 8.5f, -17f)
        camera.p()

        skinner.restoreBindPose(mesh)
        skinner.bindTo(mesh, camera, instanceCount = CROWD, tint = true)
        val clips = skinner.clips
        skinner.uploadPalettes((0 until CROWD).map { i ->
            skinner.blendedPalette(
                grid(i),
                clips[0], (i * 0.031f) % 1f,
                clips[1], (i * 0.047f) % 1f,
                mix = i / (CROWD - 1).toFloat(),
            )
        })
        val file = capture(renderer, window, File(out, "crowd_64.png"))
        val ink = inkOf(file)
        println("  %-18s %,8d B   %,d non-background pixels   $CROWD instances, one draw call".format(
            "crowd_64", file.length(), ink
        ))
        if (ink < MIN_INK) {
            println("  FAIL: the crowd frame is blank")
            exitProcess(1)
        }
    }

    private fun twist(
        renderer: Renderer,
        window: Window,
        mesh: Mesh,
        camera: Camera,
        skinner: GpuSkinner,
        cpu: CpuSkinner,
        instance: GltfSupport.MeshInstance,
        out: File,
    ) {
        // The linear CpuSkinner left its last pose in instance.buffers, and a CpuSkinner snapshots
        // its bind pose from those buffers at construction -- so without this reset the DQ skinner
        // below would take the bend/curl blend for the bind pose and skin it again. It did, the
        // first time: 5.67 mean levels against a GPU frame that was right. The trap GpuSkinner's
        // KDoc warns about, met from the CPU side.
        cpu.reset()
        val twist =skinner.skin.skeleton.clip("twist") ?: error("the bending cylinder has no 'twist' clip")
        val half = twist.durationSeconds * 0.5f
        frameSingle(camera)
        // bindTo first: it creates the push-constant block restoreBindPose writes into.
        skinner.bindTo(mesh, camera, instanceCount = 1, tint = false)
        skinner.restoreBindPose(mesh)

        val cpuDq = CpuSkinner(
            instance, GltfSkinning.SkinningOptions(method = GltfSkinning.SkinningMethod.DUAL_QUATERNION)
        )
        skinner.method = GltfSkinning.SkinningMethod.DUAL_QUATERNION
        val d = pair(renderer, window, mesh, camera, skinner, cpuDq, instance, out, "dq_twist_t100") {
            skinner.uploadPalette(skinner.placedPalette(Matrix4f(), "twist", half))
            cpuDq.pose("twist", half)
        }
        cpuDq.reset()
        if (d > PIXEL_TOL) {
            println("  FAIL: GPU and CPU dual-quaternion twist frames differ by $d > $PIXEL_TOL mean levels")
            exitProcess(1)
        }

        // The control: same pose, GPU, linear blend.
        skinner.restoreBindPose(mesh)
        skinner.method = GltfSkinning.SkinningMethod.LINEAR_BLEND
        skinner.uploadPalette(skinner.placedPalette(Matrix4f(), "twist", half))
        val lbs = capture(renderer, window, File(out, "gpu_lbs_twist_t100.png"))
        val c = difference(lbs, File(out, "gpu_dq_twist_t100.png"), File(out, "diff_lbs_vs_dq_twist.png"))
        println("  %-18s mean |gpu lbs - gpu dq| %.4f levels   max %d".format("control_twist", c.mean, c.max))
        if (c.mean < CONTROL_MIN) {
            println("  FAIL: linear and dual-quaternion twist frames are the same picture (${c.mean}) -- the method word is not reaching the shader")
            exitProcess(1)
        }

        // Side by side, one draw call: instance 0 linear on the left, instance 1 DQ on the right.
        camera.p.orthoness = 0.3
        camera.p.matchDepth = 2.0
        camera.target = Vector3f(0f, 2f, 0f)
        camera.at = Vector3f(0f, 2.4f, -5.2f)
        camera.p()
        skinner.bindTo(mesh, camera, instanceCount = 2, tint = true)
        fun at(x: Float) = Matrix4f().translate(Vector3f(x, 0f, 0f))
        for ((label, seconds) in listOf("t067" to twist.durationSeconds / 3f, "t100" to half)) {
            skinner.uploadPalettes(
                listOf(skinner.placedPalette(at(1.3f), "twist", seconds), skinner.placedPalette(at(-1.3f), "twist", seconds)),
                listOf(GltfSkinning.SkinningMethod.LINEAR_BLEND, GltfSkinning.SkinningMethod.DUAL_QUATERNION),
            )
            val file = capture(renderer, window, File(out, "twist_lbs_vs_dqs_$label.png"))
            val ink = inkOf(file)
            println("  %-18s %,8d B   %,d non-background pixels   2 instances, one draw call, words %s".format(
                "twist_lbs_vs_dqs_$label", file.length(), ink, skinner.methodWords(2).toList()
            ))
            if (ink < MIN_INK) {
                println("  FAIL: the side-by-side twist frame is blank")
                exitProcess(1)
            }
        }
        skinner.method = GltfSkinning.SkinningMethod.LINEAR_BLEND
    }

    private fun difference(a: File, b: File, into: File): Diff {
        val ia = ImageIO.read(a) ?: error("could not read ${a.name}")
        val ib = ImageIO.read(b) ?: error("could not read ${b.name}")
        require(ia.width == ib.width && ia.height == ib.height) {
            "${a.name} is ${ia.width}x${ia.height} but ${b.name} is ${ib.width}x${ib.height}"
        }
        val diff = java.awt.image.BufferedImage(ia.width, ia.height, java.awt.image.BufferedImage.TYPE_INT_RGB)
        var total = 0L
        var max = 0
        var ink = 0
        // The clear colour, sampled from a corner: what counts as "background" is the renderer's
        // business, not a constant this file should guess at.
        val background = ia.getRGB(1, 1)
        for (y in 0 until ia.height) for (x in 0 until ia.width) {
            val pa = ia.getRGB(x, y)
            val pb = ib.getRGB(x, y)
            if (pa != background) ink++
            var worst = 0
            var amplified = 0
            for (shift in listOf(16, 8, 0)) {
                val d = abs(((pa shr shift) and 0xff) - ((pb shr shift) and 0xff))
                total += d
                if (d > worst) worst = d
                // x16, so a difference of 1 level is visible rather than indistinguishable
                // from black. Saturating, so a large difference does not wrap around to dark.
                amplified = amplified or ((d * 16).coerceAtMost(255) shl shift)
            }
            if (worst > max) max = worst
            diff.setRGB(x, y, amplified)
        }
        ImageIO.write(diff, "png", into)
        return Diff(total.toDouble() / (ia.width * ia.height * 3), max, ink)
    }

    private fun inkOf(file: File): Int {
        val img = ImageIO.read(file) ?: error("could not read ${file.name}")
        val background = img.getRGB(1, 1)
        var ink = 0
        for (y in 0 until img.height) for (x in 0 until img.width) {
            if (img.getRGB(x, y) != background) ink++
        }
        return ink
    }
}