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.

8.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    shaderReflect.ts
 * @brief   What a `.esshader`'s `#pragma param` lines declare, read from the source.
 * @details Parses the same param grammar the engine's C++ ShaderParser does, but only the
 *          declaration metadata (name / type / default / range / ui hint / display name).
 *          The engine remains the single source of the std140 layout + GLSL codegen; this is
 *          the static view of the declarations, for everything that needs to know a shader's
 *          parameter vocabulary without compiling one.
 *
 *          Three things read it, which is why it lives here rather than in the editor where
 *          it started: the Material inspector builds its parameter panel from it, the built-in
 *          templates derive their material defaults from it (so the defaults cannot drift from
 *          the shader that consumes them), and `Material.setUniform` uses it to tell a caller
 *          that the name it just wrote is not one this shader has — a value the engine would
 *          otherwise drop without a word.
 *
 *          Grammar (matches ShaderParser):
 *            #pragma param <name> <type> [default(csv)] [range(min,max)] [ui(hint)] [texel(data)] [unit(length|perLength)]
 *            (<type> `textureArray` reads as a `texture` param with `layered` set)
 *            #pragma domain <Unlit|Lit|PostProcess|UI>
 */

import { worldUnitScale } from '../ecs/worldUnits';

export type ShaderParamType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int' | 'texture';

export interface ShaderParam {
    name: string;
    type: ShaderParamType;
    /** Human label for the inspector row (leading `u_` stripped, capitalized). */
    displayName: string;
    /** Default components for a scalar/vector param (length 1–4); empty for a texture. */
    default: number[];
    /** Default texture hint for a texture param (e.g. "white"); undefined otherwise. */
    defaultTexture?: string;
    /** Optional slider bounds from `range(min,max)`. */
    range?: { min: number; max: number };
    /** Optional UI hint from `ui(...)`, e.g. "slider". */
    ui?: string;
    /**
     * `texel(data)`: a texture whose texels this shader reads as numbers (a normal,
     * packed roughness), which sRGB decode would bend. Absent means colour.
     */
    texel?: 'data';
    /**
     * `unit(length)` (1) or `unit(perLength)` (-1): the default and range are written at 100 world units a metre, the
     * engine's reference, and follow the project's units per metre where a material leaves the param unset
     * (ecs/worldUnits.ts; {@link shaderParamInUnits} is what an inspector shows). Absent is a plain number.
     */
    worldUnits?: 1 | -1;
    /**
     * Declared `textureArray`: a 2D texture array, sampled with a layer index
     * (`texture(u_x, vec3(uv, layer))`). Set it with `Material.tex` on a handle from
     * `createTextureArrayFromPixels`. Absent means a plain 2D texture.
     */
    layered?: true;
}

/**
 * A param as it reads in this project: a world-unit one's default and range scaled to the project's units per metre (a length
 * by the scale, a rate per length by its inverse), as the engine fills it; any other as declared.
 */
export function shaderParamInUnits(p: ShaderParam): ShaderParam {
    const s = worldUnitScale();
    if (!p.worldUnits || s === 1) return p;
    const k = p.worldUnits === 1 ? s : 1 / s;
    const range = p.range ? { min: p.range.min * k, max: p.range.max * k } : undefined;
    return { ...p, default: p.default.map((v) => v * k), ...(range ? { range } : {}) };
}

export interface ShaderReflection {
    domain: string;
    params: ShaderParam[];
}

const TYPES = new Set<ShaderParamType>(['float', 'vec2', 'vec3', 'vec4', 'color', 'int', 'texture']);
const ARITY: Record<string, number> = { float: 1, int: 1, vec2: 2, vec3: 3, vec4: 4, color: 4 };
const VEC_KEYS = ['x', 'y', 'z', 'w'] as const;

// Extract the contents of a `key(...)` clause from a directive argument.
function clause(arg: string, key: string): string | undefined {
    const token = `${key}(`;
    const open = arg.indexOf(token);
    if (open < 0) return undefined;
    const start = open + token.length;
    const close = arg.indexOf(')', start);
    if (close < 0) return undefined;
    return arg.slice(start, close).trim();
}

function defaultForType(type: ShaderParamType): number[] {
    if (type === 'texture') return [];
    if (type === 'color') return [0, 0, 0, 1];
    return new Array(ARITY[type] ?? 1).fill(0);
}

function displayNameFor(name: string): string {
    let s = name.startsWith('u_') ? name.slice(2) : name;
    if (s.length > 0) s = s[0].toUpperCase() + s.slice(1);
    return s;
}

function parseParam(arg: string): ShaderParam | null {
    const tokens = arg.trim().split(/\s+/);
    const name = tokens[0];
    const typeStr = tokens[1];
    const layered = typeStr === 'textureArray';
    if (!name || !typeStr || (!layered && !TYPES.has(typeStr as ShaderParamType))) return null;
    const type: ShaderParamType = layered ? 'texture' : (typeStr as ShaderParamType);

    const param: ShaderParam = { name, type, displayName: displayNameFor(name), default: defaultForType(type) };
    if (layered) param.layered = true;

    const def = clause(arg, 'default');
    if (def !== undefined) {
        if (type === 'texture') {
            param.defaultTexture = def;
        } else {
            const nums = def.split(',').map((s) => parseFloat(s.trim())).filter((n) => !Number.isNaN(n));
            if (nums.length > 0) param.default = nums;
        }
    }

    const range = clause(arg, 'range');
    if (range !== undefined) {
        const [min, max] = range.split(',').map((s) => parseFloat(s.trim()));
        if (!Number.isNaN(min) && !Number.isNaN(max)) param.range = { min, max };
    }

    const ui = clause(arg, 'ui');
    if (ui !== undefined) param.ui = ui;

    if (type === 'texture' && clause(arg, 'texel') === 'data') param.texel = 'data';
    const unit = clause(arg, 'unit');
    if (type !== 'texture' && (unit === 'length' || unit === 'perLength')) param.worldUnits = unit === 'length' ? 1 : -1;

    return param;
}

/**
 * A param's declared default in the shape a `.esmaterial`'s `properties` stores it: a number
 * for float/int, `{r,g,b,a}` for a color, `{x,y,…}` for a vector, and for a texture the
 * default's NAME (`"white"`, `"flatnormal"` — an engine-resolved stand-in, not an asset ref).
 */
export function paramDefaultValue(param: ShaderParam): unknown {
    if (param.type === 'texture') return param.defaultTexture ?? 0;
    if (param.type === 'color') {
        const d = param.default;
        return { r: d[0] ?? 0, g: d[1] ?? 0, b: d[2] ?? 0, a: d[3] ?? 1 };
    }
    if (param.type === 'float' || param.type === 'int') return param.default[0] ?? 0;
    const vec: Record<string, number> = {};
    const arity = ARITY[param.type] ?? 1;
    for (let i = 0; i < arity; i++) vec[VEC_KEYS[i]] = param.default[i] ?? 0;
    return vec;
}

/**
 * A domain a shader was authored against, under the name the engine uses now.
 * The twin of the engine parser's own table: the two lit domains were named for
 * a plane before either was the only one there is, and a `.esshader` carries no
 * format version to migrate by, so the old spelling is answered on the way in.
 */
export const RENAMED_DOMAINS: Readonly<Record<string, string>> = { Lit2D: 'Lit', Unlit2D: 'Unlit' };

/** Parse a `.esshader` source into its declared parameters (world-unit ones in the project's units) and domain. */
export function reflectEsshader(source: string): ShaderReflection {
    const params: ShaderParam[] = [];
    let domain = 'Unlit';

    for (const raw of source.split('\n')) {
        const line = raw.trim();
        if (!line.startsWith('#pragma')) continue;
        const rest = line.slice('#pragma'.length).trim();
        const sp = rest.search(/\s/);
        const directive = sp < 0 ? rest : rest.slice(0, sp);
        const arg = sp < 0 ? '' : rest.slice(sp + 1).trim();

        if (directive === 'param') {
            const p = parseParam(arg);
            // In the project's units, as the engine fills an unset param: an inspector, a template and a tool all read the same number.
            if (p) params.push(shaderParamInUnits(p));
        } else if (directive === 'domain' && arg) {
            domain = RENAMED_DOMAINS[arg] ?? arg;
        }
    }

    return { domain, params };
}