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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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