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
/**
* @file spriteFilter.ts
* @brief Per-sprite filter effects using custom materials
*/
import { Material, type MaterialHandle, type ShaderHandle } from './material';
// =============================================================================
// Outline/Glow Shader (single-pass, samples 8 neighbors)
// =============================================================================
// Authored as fragment-only .esshader (the canonical 2D vertex stage is injected,
// so attribute locations, u_projection, and the batch samplers all follow the
// engine conventions) with #pragma param reflection — the same modern seam as the
// builtin templates. The old raw GLSL ES 1.00 pair had no u_projection source and
// no attribute bindings, and its loose uniforms bypassed the material system.
const OUTLINE_ESSHADER = `#pragma shader "SpriteOutlineFilter"
#pragma version 300 es
#pragma domain Unlit
#pragma param u_outlineColor color default(1,1,1,1)
#pragma param u_outlineWidth float default(1) range(0,8)
#pragma param u_texelSize vec2 default(0.001953125,0.001953125)
#pragma fragment
precision mediump float;
in vec4 v_color;
in vec2 v_texCoord;
uniform sampler2D u_textures[8];
out vec4 fragColor;
void main() {
vec4 texColor = texture(u_textures[0], v_texCoord) * v_color;
float maxAlpha = 0.0;
for (float x = -1.0; x <= 1.0; x += 1.0) {
for (float y = -1.0; y <= 1.0; y += 1.0) {
if (x == 0.0 && y == 0.0) continue;
vec2 offset = vec2(x, y) * u_texelSize * u_outlineWidth;
maxAlpha = max(maxAlpha, texture(u_textures[0], v_texCoord + offset).a);
}
}
vec4 outline = u_outlineColor * maxAlpha * (1.0 - texColor.a);
fragColor = texColor + outline;
}
#pragma end
#pragma fragment wgsl
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
let texColor = textureSampleLevel(t0, s0, v.v_texCoord, 0.0) * v.v_color;
var maxAlpha = 0.0;
for (var x = -1.0; x <= 1.0; x += 1.0) {
for (var y = -1.0; y <= 1.0; y += 1.0) {
if (x == 0.0 && y == 0.0) { continue; }
let offset = vec2f(x, y) * mc.u_texelSize * mc.u_outlineWidth;
maxAlpha = max(maxAlpha, textureSampleLevel(t0, s0, v.v_texCoord + offset, 0.0).a);
}
}
let outline = mc.u_outlineColor * maxAlpha * (1.0 - texColor.a);
return texColor + outline;
}
#pragma end
`;
// =============================================================================
// Drop Shadow Shader (single-pass offset + blur)
// =============================================================================
const SHADOW_ESSHADER = `#pragma shader "SpriteShadowFilter"
#pragma version 300 es
#pragma domain Unlit
#pragma param u_shadowColor color default(0,0,0,0.6)
#pragma param u_shadowOffset vec2 default(3,3)
#pragma param u_shadowBlur float default(2)
#pragma param u_texelSize vec2 default(0.001953125,0.001953125)
#pragma fragment
precision mediump float;
in vec4 v_color;
in vec2 v_texCoord;
uniform sampler2D u_textures[8];
out vec4 fragColor;
void main() {
vec2 shadowUV = v_texCoord - u_shadowOffset * u_texelSize;
float shadowAlpha = 0.0;
float total = 0.0;
float radius = max(1.0, u_shadowBlur);
for (float x = -2.0; x <= 2.0; x += 1.0) {
for (float y = -2.0; y <= 2.0; y += 1.0) {
vec2 offset = vec2(x, y) * u_texelSize * radius;
shadowAlpha += texture(u_textures[0], shadowUV + offset).a;
total += 1.0;
}
}
shadowAlpha /= total;
vec4 shadow = u_shadowColor * shadowAlpha;
vec4 texColor = texture(u_textures[0], v_texCoord) * v_color;
fragColor = texColor + shadow * (1.0 - texColor.a);
}
#pragma end
#pragma fragment wgsl
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
let shadowUV = v.v_texCoord - mc.u_shadowOffset * mc.u_texelSize;
var shadowAlpha = 0.0;
var total = 0.0;
let radius = max(1.0, mc.u_shadowBlur);
for (var x = -2.0; x <= 2.0; x += 1.0) {
for (var y = -2.0; y <= 2.0; y += 1.0) {
let offset = vec2f(x, y) * mc.u_texelSize * radius;
shadowAlpha += textureSampleLevel(t0, s0, shadowUV + offset, 0.0).a;
total += 1.0;
}
}
shadowAlpha /= total;
let shadow = mc.u_shadowColor * shadowAlpha;
let texColor = textureSampleLevel(t0, s0, v.v_texCoord, 0.0) * v.v_color;
return texColor + shadow * (1.0 - texColor.a);
}
#pragma end
`;
// =============================================================================
// Shader Cache
// =============================================================================
let outlineShader_: ShaderHandle = 0;
let shadowShader_: ShaderHandle = 0;
function getOutlineShader(): ShaderHandle {
if (outlineShader_ === 0) {
outlineShader_ = Material.compileShader(OUTLINE_ESSHADER);
}
return outlineShader_;
}
function getShadowShader(): ShaderHandle {
if (shadowShader_ === 0) {
shadowShader_ = Material.compileShader(SHADOW_ESSHADER);
}
return shadowShader_;
}
// =============================================================================
// Filter API
// =============================================================================
export interface OutlineFilterOptions {
color?: { r: number; g: number; b: number; a: number };
width?: number;
texelSize?: { x: number; y: number };
}
export interface DropShadowFilterOptions {
color?: { r: number; g: number; b: number; a: number };
offsetX?: number;
offsetY?: number;
blur?: number;
texelSize?: { x: number; y: number };
}
const DEFAULT_TEXEL_SIZE = { x: 1 / 512, y: 1 / 512 };
export const SpriteFilter = {
createOutline(options?: OutlineFilterOptions): MaterialHandle {
const shader = getOutlineShader();
const color = options?.color ?? { r: 1, g: 1, b: 1, a: 1 };
const width = options?.width ?? 1.0;
const texel = options?.texelSize ?? DEFAULT_TEXEL_SIZE;
const mat = Material.create({ shader });
Material.setUniform(mat, 'u_outlineColor', [color.r, color.g, color.b, color.a]);
Material.setUniform(mat, 'u_outlineWidth', width);
Material.setUniform(mat, 'u_texelSize', [texel.x, texel.y]);
return mat;
},
createGlow(options?: OutlineFilterOptions): MaterialHandle {
return SpriteFilter.createOutline({
color: options?.color ?? { r: 1, g: 0.8, b: 0.2, a: 0.8 },
width: options?.width ?? 2.0,
texelSize: options?.texelSize,
});
},
createDropShadow(options?: DropShadowFilterOptions): MaterialHandle {
const shader = getShadowShader();
const color = options?.color ?? { r: 0, g: 0, b: 0, a: 0.6 };
const ox = options?.offsetX ?? 3;
const oy = options?.offsetY ?? 3;
const blur = options?.blur ?? 2;
const texel = options?.texelSize ?? DEFAULT_TEXEL_SIZE;
const mat = Material.create({ shader });
Material.setUniform(mat, 'u_shadowColor', [color.r, color.g, color.b, color.a]);
Material.setUniform(mat, 'u_shadowOffset', [ox, oy]);
Material.setUniform(mat, 'u_shadowBlur', blur);
Material.setUniform(mat, 'u_texelSize', [texel.x, texel.y]);
return mat;
},
setOutlineColor(material: MaterialHandle, color: { r: number; g: number; b: number; a: number }): void {
Material.setUniform(material, 'u_outlineColor', [color.r, color.g, color.b, color.a]);
},
setOutlineWidth(material: MaterialHandle, width: number): void {
Material.setUniform(material, 'u_outlineWidth', width);
},
setShadowOffset(material: MaterialHandle, x: number, y: number): void {
Material.setUniform(material, 'u_shadowOffset', [x, y]);
},
setShadowBlur(material: MaterialHandle, blur: number): void {
Material.setUniform(material, 'u_shadowBlur', blur);
},
};