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.

15.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include "SpritePlugin.hpp"
#include "../store/MaterialStore.hpp"
#include "../frame/RenderContext.hpp"
#include "../frame/RenderFrame.hpp"
#include "../rhi/Texture.hpp"
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/Hierarchy.hpp"
#include "../../ecs/FlatGeometry.hpp"
#include "../../ecs/components/Sprite.hpp"
#include "../../ecs/components/SpriteMask.hpp"
#include "../../ecs/components/UINode.hpp"
#include "../../ecs/GroupOpacityLookup.hpp"
#include "../draw/SpriteDrawResolve.hpp"
#include "../store/LightConstants.hpp"

#include "../store/LightStore.hpp"

#include <algorithm>
#include <bit>
#include <cmath>

namespace esengine {

void SpritePlugin::collect(RenderCollectContext& collect_ctx) {
    auto& registry = collect_ctx.registry;
    auto& clips = collect_ctx.clip_state;
    auto& buffers = collect_ctx.buffer_pool;
    auto& draw_list = collect_ctx.draw_list;
    auto& ctx = collect_ctx.frame_context;
    auto spriteView = registry.activeView<ecs::Transform, ecs::Sprite>();

    u32 litProgram = 0;
    const ecs::GroupOpacityLookup groupOpacity(registry);

    for (auto entity : spriteView) {
        if (!collect_ctx.accepts(entity)) continue;
        const auto& sprite = spriteView.get<ecs::Sprite>(entity);
        if (!sprite.enabled) continue;
        if (registry.has<ecs::UINode>(entity)) continue;  // UI sprites are drawn by UIElementPlugin

        auto& transform = spriteView.get<ecs::Transform>(entity);
        glm::vec3 position = parallaxedWorldPosition(transform, sprite.parallax, collect_ctx.camera);
        const auto& rotation = transform.worldRotation;
        const auto& scale = transform.worldScale;

        const bool parented = registry.has<ecs::Parent>(entity);
        if (scale.x == 0 || scale.y == 0 || !ecs::hasFlatGeometryArea(registry, entity, transform)
            || sprite.size.x == 0.0f || sprite.size.y == 0.0f) continue;

        glm::vec2 finalSize = sprite.size * glm::vec2(scale);
        // The quad turns about `position`, so its pivot offset turns with it and its
        // extents grow. Bounding the unturned box instead loses a turned sprite while
        // part of it is still on screen — at 45 degrees the box is 41% short.
        const glm::vec2 turn = flatTurnZ(rotation);
        const glm::vec3 axisX = parented ? glm::vec3(transform.cachedMatrix_[0])
            : glm::vec3(turn.x, turn.y, 0.0f) * scale.x;
        const glm::vec3 axisY = parented ? glm::vec3(transform.cachedMatrix_[1])
            : glm::vec3(-turn.y, turn.x, 0.0f) * scale.y;
        const glm::vec2 pivotOffset = (glm::vec2(.5f) - sprite.pivot) * sprite.size;
        const glm::vec3 aabbCenter = position + axisX * pivotOffset.x + axisY * pivotOffset.y;
        const glm::vec3 halfExtents = glm::abs(axisX) * std::abs(sprite.size.x) * .5f
                                   + glm::abs(axisY) * std::abs(sprite.size.y) * .5f;
        // Never depth-tested unless a material says so, and that is resolved
        // below — so a sprite is judged by the view alone, and an occluder in
        // front of it does not get to speak.
        if (!collect_ctx.visible(aabbCenter, halfExtents, false)) {
            ++collect_ctx.culled;
            continue;
        }

        f32 angle = 2.0f * std::atan2(rotation.z, rotation.w);

        u32 textureId = ctx.white_texture_id;
        glm::vec2 texSize{0.0f};
        bool useNineSlice = false;
        resource::SliceBorder sliceBorder{};

        if (sprite.texture.isValid()) {
            Texture* tex = ctx.resources.getTexture(sprite.texture);
            if (tex) {
                textureId = tex->getId();
                texSize = glm::vec2(
                    static_cast<f32>(tex->getWidth()),
                    static_cast<f32>(tex->getHeight())
                );
                const auto* metadata = ctx.resources.getTextureMetadata(sprite.texture);
                if (metadata && metadata->sliceBorder.hasSlicing()) {
                    useNineSlice = true;
                    sliceBorder = metadata->sliceBorder;
                }
            }
        }

        glm::vec2 uvOff = sprite.uvOffset;
        glm::vec2 uvSc = sprite.uvScale;
        if (sprite.flipX) {
            uvOff.x += uvSc.x;
            uvSc.x = -uvSc.x;
        }
        if (sprite.flipY) {
            uvOff.y += uvSc.y;
            uvSc.y = -uvSc.y;
        }

        const SpriteDrawChoice draw = resolveSpriteDraw(
            sprite.drawMode,
            sprite.tileSize.x > 0.0f && sprite.tileSize.y > 0.0f,
            useNineSlice);
        const bool hasTiling = draw.tiled;
        useNineSlice = draw.nineSlice;

        // Emit into the existing batch stream, then map just this sprite's new
        // vertices through its full basis. Parent matrices may contain shear;
        // tiled grids also need positive steps before applying signed axes.
        const bool mapBasis = parented || hasTiling;
        if (mapBasis) angle = 0.0f;
        const u32 vertexStart = buffers.vertexBytesUsed(LayoutId::Batch);

        BatchDrawKey key{
            .stage = ctx.current_stage,
            .layer = collect_ctx.treeLayer(entity, sprite.layer),
            .order = sprite.order,
            .shaderId = batch_shader_id_,
            .blend = BlendMode::Normal,
            .textureId = textureId,
            .depth = collect_ctx.sortDepth(position),
            .y = position.y,
            .entity = entity,
            .type = RenderType::Sprite,
        };

        // Resolve the material handle to its engine-side render state. An unregistered
        // handle falls back to the default batch shader (treated as no material), so a
        // dangling reference renders plainly instead of binding a bogus program.
        if (sprite.material != 0) {
            if (const MaterialRecord* m = ctx.materials ? ctx.materials->find(sprite.material) : nullptr) {
                key.shaderId = (m->shader != 0) ? m->shader : batch_shader_id_;
                key.blend = m->blend;
                key.materialId = sprite.material;
                key.depthTest = m->depthTest;
                key.depthWrite = m->depthWrite;
                key.cull = static_cast<u8>(m->cull);
                key.depthBias = m->depthBias;
            }
        } else if (sprite.lit && ctx.frame) {
            // A material owns shading fully, so it takes precedence over the toggle.
            if (litProgram == 0) litProgram = ctx.frame->batchProgram({"LIT"});
            if (litProgram != 0) key.shaderId = litProgram;
        }

        // A mask with a cutoff cuts to the SHAPE it draws, not its box: this same draw runs
        // with colour writes off to fill the stencil, so it needs the variant that discards
        // transparent fragments or a round mask cuts a rectangle. Same resolution as UIMask.
        if (ctx.frame) {
            if (const auto* mask = registry.tryGet<ecs::SpriteMask>(entity);
                mask && mask->enabled && mask->alphaCutoff > 0.0f) {
                key.shaderId = ctx.frame->batchProgram({"ALPHA_CLIP"});
            }
        }

        glm::vec4 color = sprite.color;
        color.a *= groupOpacity.of(entity);
        if (color.a <= 0.0f) continue;

        if (hasTiling) {
            emitTiledQuads(buffers, draw_list, clips,
                position, finalSize, sprite.pivot,
                angle, color, uvOff, uvSc,
                sprite.tileSize * glm::abs(glm::vec2(scale)),
                sprite.tileSpacing * glm::abs(glm::vec2(scale)),
                key);
        } else if (useNineSlice) {
            emitNineSlice(buffers, draw_list, clips,
                position, finalSize, sprite.pivot,
                angle, texSize,
                glm::vec4(sliceBorder.left, sliceBorder.right, sliceBorder.top, sliceBorder.bottom),
                uvOff, uvSc, color, key);
        } else {
            emitQuad(buffers, draw_list, clips,
                position, finalSize, sprite.pivot,
                angle, uvOff, uvSc, color, key);
        }
        if (mapBasis) {
            const glm::vec2 divisor = hasTiling ? glm::abs(finalSize) / sprite.size
                                               : glm::vec2(scale);
            const glm::vec3 basisX = axisX / divisor.x;
            const glm::vec3 basisY = axisY / divisor.y;
            const u32 vertexEnd = buffers.vertexBytesUsed(LayoutId::Batch);
            // appendQuad can grow the pool, so retrieve its pointer after emission.
            auto* vertices = reinterpret_cast<BatchVertex*>(buffers.vertexData(LayoutId::Batch));
            for (u32 i = vertexStart / sizeof(BatchVertex); i < vertexEnd / sizeof(BatchVertex); ++i) {
                const glm::vec3 delta = vertices[i].position - position;
                vertices[i].position = position + basisX * delta.x + basisY * delta.y;
            }
        }
        // A lit sprite hands its layer to the fragment stage in the batch layout's last lane (text spends it on an outline, and a sprite
        // is never SDF text), where a light's range of layers is tested against it. See SPRITE_LAYER_BIAS in LightConstants.hpp.
        if (sprite.lit || sprite.material != 0) {
            const u32 vertexEnd = buffers.vertexBytesUsed(LayoutId::Batch);
            auto* vertices = reinterpret_cast<BatchVertex*>(buffers.vertexData(LayoutId::Batch));
            // ...and with it, which of the frame's lights can reach each quad, so a pixel works out the lamps near it and not every
            // lamp in the level (packSpriteLightLane). Quad by quad: a tiled floor is one sprite and hundreds of quads, and it is
            // the floor that is lit. The lights were collected before any plugin ran, so the slots are the ones the loop reads.
            const LightStore& lights = ctx.render_context.lights();
            const GpuLight* slots = lights.data().lights;
            const u32 lightCount = lights.count();
            const u32 first = vertexStart / sizeof(BatchVertex);
            const u32 end = vertexEnd / sizeof(BatchVertex);
            const u32 step = (end - first) % 4 == 0 ? 4 : std::max(end - first, 1u);
            for (u32 q = first; q < end; q += step) {
                glm::vec2 lo{vertices[q].position};
                glm::vec2 hi = lo;
                for (u32 i = q + 1; i < q + step; ++i) {
                    lo = glm::min(lo, glm::vec2{vertices[i].position});
                    hi = glm::max(hi, glm::vec2{vertices[i].position});
                }
                const u32 reach = lightReachMask2D(slots, lightCount, lo, hi);
                collect_ctx.lightsSpared += std::min(lightCount, SPRITE_LIGHT_REACH_BITS)
                                          - static_cast<u32>(std::popcount(reach));
                const f32 lane = packSpriteLightLane(sprite.layer, reach);
                for (u32 i = q; i < q + step; ++i) vertices[i].sdfBias = lane;
            }
        }
    }
}

void SpritePlugin::emitTiledQuads(
    TransientBufferPool& buffers, DrawList& draw_list, const ClipState& clips,
    const glm::vec3& position, const glm::vec2& size, const glm::vec2& pivot,
    f32 angle, const glm::vec4& color,
    const glm::vec2& uvOffset, const glm::vec2& uvScale,
    const glm::vec2& tileSize, const glm::vec2& tileSpacing,
    const BatchDrawKey& key
) {
    glm::vec2 step = tileSize + tileSpacing;
    if (step.x <= 0.0f || step.y <= 0.0f
        || !std::isfinite(step.x) || !std::isfinite(step.y)
        || !std::isfinite(tileSize.x) || !std::isfinite(tileSize.y)) return;

    glm::vec2 absSize = glm::vec2(std::abs(size.x), std::abs(size.y));
    if (!std::isfinite(absSize.x) || !std::isfinite(absSize.y)) return;

    f32 baseX = position.x - absSize.x * pivot.x;
    f32 baseY = position.y - absSize.y * pivot.y;

    bool hasRotation = std::abs(angle) > 0.001f;
    f32 cosA = 1.0f, sinA = 0.0f;
    if (hasRotation) {
        cosA = std::cos(angle);
        sinA = std::sin(angle);
    }

    u32 pc = packColor(color);

    const f64 countY = std::ceil(static_cast<f64>(absSize.y) / step.y);
    const f64 countX = std::ceil(static_cast<f64>(absSize.x) / step.x);

    // Bound counts before integer conversion, which can turn overflowing native
    // counts negative. Grids above the cap use one stretched quad.
    constexpr f64 kMaxTiledQuads = 16384;
    if (countX > kMaxTiledQuads || countY > kMaxTiledQuads
        || countX * countY > kMaxTiledQuads) {
        BatchVertex verts[4];
        if (hasRotation) {
            verts[0] = { rotatePoint(position, baseX, baseY, cosA, sinA), pc, { uvOffset.x, uvOffset.y } };
            verts[1] = { rotatePoint(position, baseX + absSize.x, baseY, cosA, sinA), pc, { uvOffset.x + uvScale.x, uvOffset.y } };
            verts[2] = { rotatePoint(position, baseX + absSize.x, baseY + absSize.y, cosA, sinA), pc, { uvOffset.x + uvScale.x, uvOffset.y + uvScale.y } };
            verts[3] = { rotatePoint(position, baseX, baseY + absSize.y, cosA, sinA), pc, { uvOffset.x, uvOffset.y + uvScale.y } };
        } else {
            verts[0] = { { baseX, baseY, position.z }, pc, { uvOffset.x, uvOffset.y } };
            verts[1] = { { baseX + absSize.x, baseY, position.z }, pc, { uvOffset.x + uvScale.x, uvOffset.y } };
            verts[2] = { { baseX + absSize.x, baseY + absSize.y, position.z }, pc, { uvOffset.x + uvScale.x, uvOffset.y + uvScale.y } };
            verts[3] = { { baseX, baseY + absSize.y, position.z }, pc, { uvOffset.x, uvOffset.y + uvScale.y } };
        }
        appendQuad(buffers, draw_list, clips, verts, key);
        return;
    }

    const i32 tilesX = static_cast<i32>(countX);
    const i32 tilesY = static_cast<i32>(countY);

    for (i32 iy = 0; iy < tilesY; ++iy) {
        f32 ty = static_cast<f32>(iy) * step.y;
        f32 th = glm::min(tileSize.y, absSize.y - ty);
        if (th <= 0.0f) break;
        f32 vFrac = th / tileSize.y;

        for (i32 ix = 0; ix < tilesX; ++ix) {
            f32 tx = static_cast<f32>(ix) * step.x;
            f32 tw = glm::min(tileSize.x, absSize.x - tx);
            if (tw <= 0.0f) break;
            f32 uFrac = tw / tileSize.x;

            f32 x0 = baseX + tx;
            f32 y0 = baseY + ty;
            f32 x1 = x0 + tw;
            f32 y1 = y0 + th;

            glm::vec2 tileUvScale = { uvScale.x * uFrac, uvScale.y * vFrac };

            BatchVertex verts[4];
            if (hasRotation) {
                verts[0] = { rotatePoint(position, x0, y0, cosA, sinA), pc, { uvOffset.x,                 uvOffset.y } };
                verts[1] = { rotatePoint(position, x1, y0, cosA, sinA), pc, { uvOffset.x + tileUvScale.x, uvOffset.y } };
                verts[2] = { rotatePoint(position, x1, y1, cosA, sinA), pc, { uvOffset.x + tileUvScale.x, uvOffset.y + tileUvScale.y } };
                verts[3] = { rotatePoint(position, x0, y1, cosA, sinA), pc, { uvOffset.x,                 uvOffset.y + tileUvScale.y } };
            } else {
                verts[0] = { { x0, y0, position.z }, pc, { uvOffset.x,                 uvOffset.y } };
                verts[1] = { { x1, y0, position.z }, pc, { uvOffset.x + tileUvScale.x, uvOffset.y } };
                verts[2] = { { x1, y1, position.z }, pc, { uvOffset.x + tileUvScale.x, uvOffset.y + tileUvScale.y } };
                verts[3] = { { x0, y1, position.z }, pc, { uvOffset.x,                 uvOffset.y + tileUvScale.y } };
            }

            appendQuad(buffers, draw_list, clips, verts, key);
        }
    }
}

}  // namespace esengine