Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

7.7 KB
Raw Blame
// The sort key's field layout, asserted on the bits rather than through a frame: two
// draws in the right order prove nothing about WHICH field decided it, and that is what
// the next change has to keep. Header-only, so no engine link.

#include "esengine/renderer/draw/DrawCommand.hpp"

#include <algorithm>
#include <cstdio>

using namespace esengine;

static int g_failures = 0;
#define CHECK(cond, msg)                                                        \
    do {                                                                        \
        if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; }          \
        else { std::printf("ok:   %s\n", msg); }                                \
    } while (0)

/// The key a plain blended sprite gets, with every field the caller can vary.
static u64 blended(i32 layer, i32 order, f32 depth, u32 shader = 0, u32 material = 0) {
    return DrawCommand::buildSortKey(RenderStage::Transparent, layer, shader,
                                     BlendMode::Normal, 0, depth, material, order);
}

static u64 opaque(i32 layer, i32 order, f32 depth, u32 shader = 0, u32 material = 0) {
    return DrawCommand::buildSortKey(RenderStage::Opaque, layer, shader,
                                     BlendMode::None, 0, depth, material, order);
}

static u64 ysorted(i32 layer, i32 order, f32 worldY, u32 shader = 0) {
    return DrawCommand::buildSortKeyYSorted(RenderStage::Transparent, layer, worldY,
                                            shader, BlendMode::Normal, 0, order);
}

/// The 8 bits a group spends on its members, read back out of a finished key.
static u64 memberField(u64 key) { return (key >> 30) & 0xFF; }

int main() {
    // ---- What a group takes over -------------------------------------------------
    // The promise is that nothing outside lands BETWEEN the members — a claim about the
    // key's top fields, so it is checked there.
    {
        const u64 lowMember = DrawCommand::withGroupOrder(blended(5, 2, 0.0f), -100);
        const u64 highMember = DrawCommand::withGroupOrder(blended(5, 2, 0.0f), 100);
        const u64 outsiderAbove = blended(5, 3, 0.0f);
        const u64 outsiderBelow = blended(5, 1, 0.0f);
        CHECK(lowMember < highMember, "a member's own order still separates it inside the group");
        CHECK(outsiderBelow < lowMember && highMember < outsiderAbove,
              "an outsider cannot land between two members of one group");
    }

    // The member field must be the SAME field in every packing, or two members of one
    // group could not be compared at all — the group's own stage is not uniform across
    // its contents (an opaque prop under a blended character).
    {
        const u64 b = DrawCommand::withGroupOrder(blended(5, 0, 1.0f, 0xFF, 0x1F), 7);
        const u64 o = DrawCommand::withGroupOrder(opaque(5, 0, 1.0f, 0xFF, 0x7FF), 7);
        const u64 y = DrawCommand::withGroupOrder(ysorted(5, 0, 42.0f, 0xFF), 7);
        CHECK(memberField(b) == memberField(o) && memberField(o) == memberField(y),
              "the member field is the same 8 bits in all three packings");
        CHECK(memberField(b) == 7u + 128u, "a member order is stored biased, like the group's");
    }

    // Stamping is not appending: it must LAND on those bits whatever they held, or a
    // deep sprite would out-sort a shallow sibling stated to be above it.
    {
        const u64 near = DrawCommand::withGroupOrder(blended(5, 0, 1000.0f), 0);
        const u64 far = DrawCommand::withGroupOrder(blended(5, 0, -1000.0f), 1);
        CHECK(near < far, "a stated member order outranks the depth it overwrote");
    }
    {
        const u64 backY = DrawCommand::withGroupOrder(ysorted(5, 0, 500.0f), 1);
        const u64 frontY = DrawCommand::withGroupOrder(ysorted(5, 0, -500.0f), 0);
        CHECK(frontY < backY, "a stated member order outranks world Y inside a group");
    }

    // Negative and out-of-range members, on the same terms as the group's own order:
    // clamped, never wrapped, because a wrap turns "far on top" into "behind".
    {
        const u64 under = DrawCommand::withGroupOrder(blended(5, 0, 0.0f), -1);
        const u64 unstated = DrawCommand::withGroupOrder(blended(5, 0, 0.0f), 0);
        const u64 over = DrawCommand::withGroupOrder(blended(5, 0, 0.0f), 5000);
        const u64 pinned = DrawCommand::withGroupOrder(blended(5, 0, 0.0f), 127);
        CHECK(under < unstated, "a negative member sinks below an unstated one");
        CHECK(over == pinned, "a member order past the range pins to the end it ran past");
    }

    // A group cannot leak: whatever a member states, it stays inside the group's layer.
    {
        const u64 loudMember = DrawCommand::withGroupOrder(blended(5, 0, 0.0f), 127);
        const u64 quietAbove = blended(6, -128, 0.0f);
        CHECK(loudMember < quietAbove, "the loudest member never escapes its group's layer");
    }

    // ---- What the stamp leaves alone ---------------------------------------------
    // Only [37:30] moves. A group that also disturbed the layer, the order or the stage
    // would reorder the frame in ways nothing here would catch.
    {
        const u64 plain = blended(5, 2, 1.0f, 0xFF, 0x1F);
        const u64 stamped = DrawCommand::withGroupOrder(plain, 3);
        constexpr u64 memberBits = 0xFFull << 30;
        CHECK((plain & ~memberBits) == (stamped & ~memberBits),
              "stamping a member order touches no other field");
    }

    // ---- What the state flags mean ------------------------------------------------
    // The one reading of these bits. A backend doing it in its own words is how a mask
    // ends up working everywhere but one path.
    {
        CHECK(stencilModeOf(0) == GfxStencilMode::Off, "no stencil bits means no stencil");
        CHECK(stencilModeOf(CMD_STATE_STENCIL_WRITE) == GfxStencilMode::Write,
              "the write bit fills the mask");
        CHECK(stencilModeOf(CMD_STATE_STENCIL_TEST) == GfxStencilMode::Test,
              "the test bit alone cuts to the INSIDE");
        CHECK(stencilModeOf(CMD_STATE_STENCIL_TEST | CMD_STATE_STENCIL_OUT)
                  == GfxStencilMode::TestOutside,
              "the outside bit cuts to the hole instead");
        // Write outranks test: a mask filling the stencil cannot also be tested against
        // the value it is in the middle of writing.
        CHECK(stencilModeOf(CMD_STATE_STENCIL_WRITE | CMD_STATE_STENCIL_TEST)
                  == GfxStencilMode::Write,
              "a draw that writes is not also a draw that tests");
        // The outside bit on its own is not a test — it qualifies one.
        CHECK(stencilModeOf(CMD_STATE_STENCIL_OUT) == GfxStencilMode::Off,
              "the outside bit alone turns nothing on");
        CHECK(stencilModeOf(CMD_STATE_SCISSOR) == GfxStencilMode::Off,
              "a scissored draw is not a stencilled one");
    }

    // An instanced mesh draw sorts by its geometry inside a material, so two meshes sharing one do not alternate by depth.
    {
        auto mesh = [](u32 geometry, f32 depth) {
            return DrawCommand::buildSortKey(RenderStage::Opaque, 0, 3, BlendMode::None, 0, depth, 9, 0, geometry);
        };
        const u64 a1 = mesh(5, 1.0f), a2 = mesh(5, 40.0f), b1 = mesh(7, 2.0f), b2 = mesh(7, 30.0f);
        CHECK(std::max(a1, a2) < std::min(b1, b2), "draws of one mesh sit together, whatever their depths");
        CHECK(mesh(5, 1.0f) != mesh(5, 40.0f), "depth still orders within a mesh");
        CHECK((mesh(5, 1.0f) >> 14) == (mesh(7, 1.0f) >> 14), "geometry stays below the material field");
        CHECK(mesh(0, 1.0f) == opaque(0, 0, 1.0f, 3, 9), "no geometry leaves the key as it was");
    }

    std::printf(g_failures ? "\n%d check(s) failed\n" : "\nall checks passed\n", g_failures);
    return g_failures == 0 ? 0 : 1;
}