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.9 KB
Raw Blame
// 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);
    },
};