Files
gods-eye-view/src/render/contract/effects.d.ts
T
Sameh Khamis bbda6dd0a1 Run styles, bloom and sharpen through a Cesium effects port
The effects port puts each style the app defines on its own post-process
stage, takes the scene's bloom stage and adds a sharpen stage, with the
mappings the application uses today. An animated style holds frames and
advances its time uniform while it draws. A replaced style keeps drawing
until its intensity is 0, so the app can crossfade; the contract, the stub
and a new conformance check say so. The conformance renderer has the
port; the application renderer does not yet.
2026-11-06 16:32:39 -08:00

90 lines
3.6 KiB
TypeScript

/**
* Full-screen effects: visual styles, bloom, sharpen and screen modulation.
* Each style is a plain full-screen pass over the frame's colour. The
* application owns the styles and defines them on the renderer
* renderer runs the same set; a renderer's own styles are extra ones.
*/
import type { Off } from './common';
export interface StyleDescriptor {
id: string;
/** Parameters and their ranges. */
params: Array<{ key: string; min: number; max: number; default: number }>;
/** Animates, so it needs frames while on. */
animated: boolean;
}
/**
* A style's shader. `glsl` is a GLSL ES 3.00 fragment shader with its
* `main()`, as GEV's styles are written, without `#version`, `precision`
* or an `out` declaration: the renderer declares `out_FragColor`, which it
* writes. It declares what it reads of `uniform sampler2D colorTexture`,
* `uniform vec2 colorTextureDimensions` (pixels),
* `in vec2 v_textureCoordinates`, `uniform float intensity` (0..1),
* `uniform float time` (seconds, for an animated style) and one
* `uniform float` per parameter under its key. Parameter keys are GLSL
* identifiers and never one of those names.
* `wgsl` is the same pass in WGSL: a fragment entry
* `fs_main` taking `@location(0) uv: vec2f` and returning the colour at
* `@location(0)`. Group 0 binds `colorTexture` (`texture_2d<f32>`) at 0,
* `colorSampler` at 1 and, at 2, a uniform struct the shader declares as
* `params`: `intensity: f32`, `time: f32`, `dimensions: vec2f`, then one
* `f32` per parameter in the order `params` lists them.
*/
export interface StyleShader {
glsl: string;
wgsl?: string;
}
export interface StyleDefinition extends StyleDescriptor {
shader: StyleShader;
}
/** A sweeping sector drawn over the frame (a sonar band), or null. */
export interface ModulationSector {
/** Centre of the sweep, CSS pixels. */
center: { x: number; y: number };
/** Current angle, radians clockwise from up. */
angle: number;
/** Width of the band, radians. */
width: number;
/** 0..1. */
strength: number;
color: string;
}
export interface EffectsDiagnostics {
style: string | null;
/** The passes that draw: `style:<id>` for each style, `bloom`, ... */
passes: string[];
}
export interface EffectsPort {
/** `styles`: every style, defined by the application or the renderer's own. */
styles(): StyleDescriptor[];
/**
* `styles`: add a style, replacing one with the same id. Null without
* the capability, or when the renderer runs none of the shader's
* languages; the Off removes it (turning it off when it is the style).
*/
defineStyle(definition: StyleDefinition): Off | null;
/**
* Make `id` the style, or none. The style it replaces, if its intensity
* is above 0, keeps drawing with the new one until its intensity is set
* to 0, so the application crossfades by fading one out as it fades the other in.
* Styles draw in the order they were defined.
*/
setStyle(id: string | null, params?: Record<string, number>): void;
/** A style's intensity, 0..1; kept while it is not the style. 1 at first. */
setStyleIntensity(id: string, intensity: number): void;
setStyleParams(id: string, params: Record<string, number>): void;
/** `bloom`. `strength`, 0..1, is kept while bloom is off. */
bloom(settings: { enabled: boolean; strength?: number }): void;
/** `sharpen`. `amount`, 0..1, is kept while sharpen is off. */
sharpen(settings: { enabled: boolean; amount?: number }): void;
/** `screenModulation`. */
screenModulation?(sector: ModulationSector | null): void;
diagnostics(): EffectsDiagnostics;
on(event: 'change', cb: (diagnostics: EffectsDiagnostics) => void): Off;
}