excalibur 0.33.0-alpha.99 → 1.1.0-alpha.310

package/build/esm/src/engine/graphics/context/material.d.ts

@@ -0,0 +1,208 @@
+import { Color } from '../../color';
+import type { ExcaliburGraphicsContext } from './excalibur-graphics-context';
+import type { Shader, UniformDictionary } from './shader';
+import type { ImageSource } from '../image-source';
+import { ImageFiltering } from '../filtering';
+import { Framebuffer } from './framebuffer';
+import type { ShaderPassLike, ShaderPipelineLike } from './shader-pipeline/shader-pipeline';
+type MaterialSharedOptions = {
+    /**
+     * Name the material for debugging
+     */
+    name?: string;
+    /**
+     * Excalibur graphics context to create the material (only WebGL is supported at the moment)
+     */
+    graphicsContext?: ExcaliburGraphicsContext;
+    /**
+     * Optionally specify a vertex shader
+     *
+     * If none supplied the default will be used
+     *
+     * ```
+     *  #version 300 es
+     *  // vertex position in local space
+     *  in vec2 a_position;
+     *  in vec2 a_uv;
+     *  out vec2 v_uv;
+     *  // orthographic projection matrix
+     *  uniform mat4 u_matrix;
+     *  // world space transform matrix
+     *  uniform mat4 u_transform;
+     *  void main() {
+     *    // Set the vertex position using the ortho & transform matrix
+     *    gl_Position = u_matrix * u_transform * vec4(a_position, 0.0, 1.0);
+     *    // Pass through the UV coord to the fragment shader
+     *    v_uv = a_uv;
+     *  }
+     * ```
+     */
+    vertexSource?: string;
+    /**
+     * Add custom color, by default ex.Color.Transparent
+     */
+    color?: Color;
+    /**
+     * Add additional images to the material, you are limited by the GPU's maximum texture slots
+     *
+     * Specify a dictionary of uniform sampler names to ImageSource, they are also bound as named
+     * sources in every pass when `passes` is provided
+     */
+    images?: Record<string, ImageSource>;
+    /**
+     * Optionally set starting uniforms on a shader, they are also forwarded to every pass when
+     * `passes` is provided
+     */
+    uniforms?: UniformDictionary;
+};
+type MaterialShaderOptions = // single pass custom shading
+{
+    /**
+     * The fragment shader applied when the graphic is drawn on screen
+     *
+     * *Note: Excalibur image alpha's are pre-multiplied
+     *
+     * Pre-built varyings:
+     *
+     * * `in vec2 v_uv` - UV coordinate
+     * * `in vec2 v_screenuv` - UV coordinate
+     *
+     * Pre-built uniforms:
+     *
+     * * `uniform sampler2D u_graphic` - The current graphic displayed by the GraphicsComponent
+     * * `uniform sampler2D u_image` - Synonym for `u_graphic`
+     * * `uniform sampler2D u_original` - The pre-effect graphic; equal to `u_graphic`/`u_image` when there is no pipeline
+     * * `uniform sampler2D u_screen_texture` - The screen texture, bound when referenced in the source
+     * * `uniform vec2 u_resolution` - The current resolution of the screen (in pixels)
+     * * `uniform vec2 u_graphic_resolution` - The current resolution of the graphic (in pixels)
+     * * `uniform vec2 u_size;` - The current size of the graphic (in pixels)
+     * * `uniform vec4 u_color` - The current color of the material
+     * * `uniform float u_opacity` - The current opacity of the graphics context
+     * * `uniform float u_time_ms` - The current time in milliseconds
+     * * `uniform mat4 u_matrix` - The orthographic projection matrix
+     * * `uniform mat4 u_transform` - The current geometry transform matrix
+     */
+    fragmentSource: string;
+    passes?: undefined;
+    padding?: undefined;
+} | {
+    /**
+     * Multipass pipeline run on the graphic's texture offscreen before it is drawn.
+     *
+     * Provide an ordered list of passes (bare fragment strings or {@apilink ShaderPass}), or any
+     * {@apilink ShaderPipelineLike} implementation ({@apilink BloomEffect}, {@apilink GlowEffect},
+     * {@apilink BlurEffect}, or your own pass graph).
+     *
+     * The material's `uniforms`, `images`, and built-ins (`u_opacity`, `u_color`,
+     * `u_graphic_resolution`, `u_size`) are forwarded to every pass.
+     */
+    passes: ShaderPassLike[] | ShaderPipelineLike;
+    /**
+     * The **final composite** fragment shader: it draws the pipeline's output (bound as
+     * `u_graphic`, with `u_image` as a synonym) on screen and is where screen-space work like
+     * `u_screen_texture` belongs. The pre-effect graphic is also available as `u_original`, so
+     * the composite can mix the processed result with the untouched source.
+     *
+     * When omitted a passthrough composite is used that draws the pipeline output with the
+     * context opacity applied.
+     */
+    fragmentSource?: string;
+    /**
+     * Extra transparent pixels (in source-texture pixels) added around the graphic when running
+     * `passes`, so effects like blur/glow are not clipped to the graphic's quad. The on-screen
+     * quad expands to match. Default 0.
+     */
+    padding?: number;
+};
+export type MaterialOptions = MaterialShaderOptions & MaterialSharedOptions;
+/**
+ * {@apilink MaterialOptions} without the graphics context, preserving the valid
+ * fragmentSource/passes combinations, used by {@apilink ExcaliburGraphicsContextWebGL.createMaterial}
+ */
+export type MaterialOptionsWithoutContext = MaterialShaderOptions & Omit<MaterialSharedOptions, 'graphicsContext'>;
+export interface MaterialImageOptions {
+    filtering?: ImageFiltering;
+}
+/**
+ * Passed to {@apilink Material.update}'s callback for batch-updating a material mid-frame.
+ */
+export interface MaterialContext {
+    /**
+     * The material's uniforms, the same dictionary as `material.uniforms` changes
+     * reach the composite shader and, when `passes` is used, are forwarded to every pass
+     */
+    uniforms: UniformDictionary;
+    /**
+     * Every compiled {@apilink Shader} this material drives, in order
+     */
+    shaders: Shader[];
+    /**
+     * The same shaders as `shaders`, keyed by {@apilink Shader.name}.
+     */
+    shadersByName: Map<string, Shader>;
+}
+export declare class Material {
+    static BuiltInUniforms: string[];
+    private static _ID;
+    /**
+     * Unique identifier for this material, useful for debugging and tooling
+     */
+    readonly id: number;
+    private _logger;
+    private _name;
+    private _shader;
+    private _color;
+    private _initialized;
+    private _fragmentSource;
+    private _vertexSource;
+    private _images;
+    private _uniforms;
+    private _graphicsContext?;
+    private _passes?;
+    private _pipeline;
+    private _padding;
+    private _seedFramebuffer?;
+    private _outputFramebuffer;
+    constructor(options: MaterialOptions);
+    private _initialize;
+    get uniforms(): UniformDictionary;
+    get images(): Record<string, ImageSource>;
+    get color(): Color;
+    set color(c: Color);
+    get name(): string;
+    /**
+     * Vertex source this material was created with (before shader compilation)
+     */
+    get vertexSource(): string;
+    /**
+     * Fragment source this material was created with (before shader compilation)
+     */
+    get fragmentSource(): string;
+    get isOverridingGraphic(): boolean;
+    get isUsingScreenTexture(): boolean;
+    get isUsingOriginalTexture(): boolean;
+    /**
+     * The multipass pipeline run on the graphic before the composite fragment, if any
+     */
+    get pipeline(): ShaderPipelineLike | null;
+    /**
+     * Extra transparent pixels added around the graphic when running the pipeline
+     */
+    get padding(): number;
+    /**
+     * Lazily creates/resizes the padded framebuffer
+     * @internal
+     */
+    getSeedFramebuffer(width: number, height: number): Framebuffer;
+    /**
+     * Lazily creates/resizes the final output for compositing
+     * @internal
+     */
+    getOutputFramebuffer(width: number, height: number, filtering?: ImageFiltering | null): Framebuffer;
+    update(callback: (context: MaterialContext) => any): void;
+    getShader(): Shader | null;
+    addImageSource(samplerName: string, image: ImageSource): void;
+    removeImageSource(samplerName: string): void;
+    use(): void;
+}
+export {};

package/build/esm/src/engine/graphics/context/shader-pipeline/effects/bloom-effect.d.ts

@@ -0,0 +1,80 @@
+import type { ExcaliburGraphicsContextWebGL } from '../../excalibur-graphics-context-webgl';
+import type { Shader } from '../../shader';
+import type { ShaderPassDestination, ShaderPassSource } from '../shader-pass';
+import type { ShaderPipelineLike, ShaderPipelineProcessOptions } from '../shader-pipeline';
+export interface BloomEffectOptions {
+    graphicsContext: ExcaliburGraphicsContextWebGL;
+    /**
+     * Luminance cutoff (0-1) above which pixels contribute to the bloom, default 0.8
+     */
+    threshold?: number;
+    /**
+     * Multiplies the bloom light **added on top of** the original image, default 1.
+     *
+     * 1 is the neutral amount, values above 1 read as hotter, values below 1 are subtle.
+     */
+    intensity?: number;
+    /**
+     * Depth of the downsample/upsample ladder, default 4.
+     *
+     * Each level halves the resolution, more levels produce a wider, softer bloom for the same cost
+     * profile. Clamped to at least 1.
+     */
+    levels?: number;
+}
+/**
+ * Multipass bloom: bright areas of the source are extracted, blurred down a progressive
+ * downsample ladder, accumulated back up with tent-filter upsampling, and added onto the
+ * original image.
+ *
+ * Implements {@apilink ShaderPipelineLike} as a non-linear pass graph, so it plugs into either
+ * integration point:
+ *
+ * ```typescript
+ * // fullscreen
+ * game.graphicsContext.addPostProcessor(
+ *   new ex.ShaderPipelinePostProcessor({
+ *     passes: new ex.BloomEffect({ graphicsContext, threshold: 0.6, intensity: 1.5 })
+ *   })
+ * );
+ *
+ * // or per-graphic
+ * actor.graphics.material = new ex.Material({
+ *   graphicsContext,
+ *   passes: new ex.BloomEffect({ graphicsContext, threshold: 0.5 }),
+ *   padding: 32 // room for the bloom halo
+ * });
+ * ```
+ */
+export declare class BloomEffect implements ShaderPipelineLike {
+    private _graphicsContext;
+    private _levels;
+    private _threshold;
+    private _downsample;
+    private _upsampleMerge;
+    private _combine;
+    private _downFramebuffers;
+    private _upFramebuffers;
+    private _disposed;
+    constructor(options: BloomEffectOptions);
+    /**
+     * Luminance cutoff (0-1) above which pixels contribute to the bloom
+     */
+    get threshold(): number;
+    set threshold(value: number);
+    /**
+     * Multiplies the bloom light **added on top of** the original image.
+     *
+     * 1 is the neutral amount, values above 1 read as hotter, values below 1 are subtle.
+     */
+    get intensity(): number;
+    set intensity(value: number);
+    private _ensureFramebuffers;
+    process(source: ShaderPassSource, destination: ShaderPassDestination, options?: ShaderPipelineProcessOptions): void;
+    /**
+     * Every internal pass's compiled {@apilink Shader}, in the order they run: threshold,
+     * downsample, upsample-merge, combine
+     */
+    getShaders(): Shader[];
+    dispose(): void;
+}

package/build/esm/src/engine/graphics/context/shader-pipeline/effects/blur-passes.d.ts

@@ -0,0 +1,75 @@
+import type { ExcaliburGraphicsContextWebGL } from '../../excalibur-graphics-context-webgl';
+import type { Shader } from '../../shader';
+import type { ShaderPassDestination, ShaderPassSource } from '../shader-pass';
+import { ShaderPass } from '../shader-pass';
+import type { ShaderPipelineLike, ShaderPipelineProcessOptions } from '../shader-pipeline';
+export interface BlurPassesOptions {
+    graphicsContext: ExcaliburGraphicsContextWebGL;
+    /**
+     * Resolution the blur runs at relative to the source, default 0.5 (half resolution).
+     *
+     * Lower is cheaper and blurrier, the final pass linearly upsamples back to full resolution.
+     */
+    scale?: number;
+    /**
+     * Blur radius multiplier in texels of the (downsampled) blur resolution, default 1
+     */
+    strength?: number;
+}
+/**
+ * Blurring premultiplied colors directly is the correct alpha handling for a weighted average,
+ * so this fragment opts out of the glsl tag's straight-alpha authoring space.
+ *
+ * Expects `u_direction` (e.g. `vec(1, 0)` for horizontal) and `u_strength` uniforms.
+ */
+export declare const gaussianBlurFragmentSource: string;
+/**
+ * Separable 9-tap gaussian blur: a horizontal pass at `scale` resolution followed by a vertical
+ * pass that linearly upsamples back to the destination resolution.
+ *
+ * ```typescript
+ * const material = new ex.Material({
+ *   graphicsContext,
+ *   passes: createBlurPasses({ graphicsContext }),
+ *   padding: 8 // give the blur room so it is not clipped to the graphic
+ * });
+ *
+ * // or fullscreen
+ * game.graphicsContext.addPostProcessor(
+ *   new ex.ShaderPipelinePostProcessor({ passes: createBlurPasses({ graphicsContext }) })
+ * );
+ * ```
+ */
+export declare function createBlurPasses(options: BlurPassesOptions): ShaderPass[];
+/**
+ * Separable gaussian blur wrapped in a convenient object with live-tunable settings, the
+ * ergonomic counterpart to {@apilink createBlurPasses}.
+ *
+ * ```typescript
+ * const blur = new ex.BlurEffect({ graphicsContext, strength: 2 });
+ * actor.graphics.material = new ex.Material({ graphicsContext, passes: blur, padding: 16 });
+ *
+ * blur.strength = 4; // animate any time, applies next frame
+ * ```
+ */
+export declare class BlurEffect implements ShaderPipelineLike {
+    /**
+     * Resolution the blur runs at relative to the source, fixed at construction
+     */
+    readonly scale: number;
+    private _pipeline;
+    private _horizontal;
+    private _vertical;
+    constructor(options: BlurPassesOptions);
+    /**
+     * Blur radius multiplier in texels of the (downsampled) blur resolution
+     */
+    get strength(): number;
+    set strength(value: number);
+    process(source: ShaderPassSource, destination: ShaderPassDestination, options?: ShaderPipelineProcessOptions): void;
+    /**
+     * Every internal pass's compiled {@apilink Shader}, in the order they run
+     */
+    getShaders(): Shader[];
+    dispose(): void;
+}

package/build/esm/src/engine/graphics/context/shader-pipeline/effects/glow-passes.d.ts

@@ -0,0 +1,93 @@
+import { Color } from '../../../../color';
+import type { ExcaliburGraphicsContextWebGL } from '../../excalibur-graphics-context-webgl';
+import type { Shader } from '../../shader';
+import type { ShaderPassDestination, ShaderPassSource } from '../shader-pass';
+import { ShaderPass } from '../shader-pass';
+import type { ShaderPipelineLike, ShaderPipelineProcessOptions } from '../shader-pipeline';
+export interface GlowPassesOptions {
+    graphicsContext: ExcaliburGraphicsContextWebGL;
+    /**
+     * Glow color, default white
+     */
+    color?: Color;
+    /**
+     * Resolution the glow blur runs at relative to the source, default 0.5 (half resolution)
+     */
+    scale?: number;
+    /**
+     * Blur radius multiplier in texels of the (downsampled) glow resolution, default 2
+     */
+    strength?: number;
+    /**
+     * Multiplies the halo's **opacity**, default 1.
+     *
+     * The halo saturates at full opacity, so 0-1 is the useful range for fading a glow in and
+     * out; values above 1 make the core denser and hotter before saturating.
+     */
+    intensity?: number;
+}
+/**
+ * Outer glow: the graphic's silhouette is tinted with the glow color, gaussian blurred at reduced
+ * resolution, and the original graphic is composited back over the halo.
+ *
+ * Designed for per-graphic use with a {@apilink Material}, where `padding` gives the halo room
+ * outside the graphic's quad:
+ *
+ * ```typescript
+ * actor.graphics.material = new ex.Material({
+ *   graphicsContext,
+ *   passes: ex.createGlowPasses({ graphicsContext, color: ex.Color.Cyan, strength: 3 }),
+ *   padding: 16
+ * });
+ * ```
+ */
+export declare function createGlowPasses(options: GlowPassesOptions): ShaderPass[];
+/**
+ * Outer glow wrapped in a convenient object with live-tunable settings, the ergonomic
+ * counterpart to {@apilink createGlowPasses}.
+ *
+ * ```typescript
+ * const glow = new ex.GlowEffect({ graphicsContext, color: ex.Color.Cyan, strength: 3 });
+ * actor.graphics.material = new ex.Material({ graphicsContext, passes: glow, padding: 16 });
+ *
+ * glow.intensity = 2;            // animate any time, applies next frame
+ * glow.color = ex.Color.Magenta;
+ * ```
+ */
+export declare class GlowEffect implements ShaderPipelineLike {
+    /**
+     * Resolution the glow blur runs at relative to the source, fixed at construction
+     */
+    readonly scale: number;
+    private _pipeline;
+    private _silhouette;
+    private _horizontal;
+    private _vertical;
+    private _color;
+    constructor(options: GlowPassesOptions);
+    /**
+     * Glow color. Assign a new color to change it, mutating the color instance in place
+     * will not be picked up.
+     */
+    get color(): Color;
+    set color(value: Color);
+    /**
+     * Multiplies the halo's **opacity**.
+     *
+     * The halo saturates at full opacity, so 0-1 is the useful range for fading a glow in and
+     * out; values above 1 make the core denser and hotter before saturating.
+     */
+    get intensity(): number;
+    set intensity(value: number);
+    /**
+     * Blur radius multiplier in texels of the (downsampled) glow resolution
+     */
+    get strength(): number;
+    set strength(value: number);
+    process(source: ShaderPassSource, destination: ShaderPassDestination, options?: ShaderPipelineProcessOptions): void;
+    /**
+     * Every internal pass's compiled {@apilink Shader}, in the order they run
+     */
+    getShaders(): Shader[];
+    dispose(): void;
+}

package/build/esm/src/engine/graphics/context/shader-pipeline/shader-pass.d.ts

@@ -0,0 +1,138 @@
+import { ImageFiltering } from '../../filtering';
+import { ImageSource } from '../../image-source';
+import type { ExcaliburGraphicsContextWebGL } from '../excalibur-graphics-context-webgl';
+import { Framebuffer } from '../framebuffer';
+import type { Shader, UniformDictionary } from '../shader';
+/**
+ * Anything a {@apilink ShaderPass} can sample from: a {@apilink Framebuffer}, a loaded
+ * {@apilink ImageSource}, or a raw premultiplied `WebGLTexture`
+ */
+export type ShaderPassSource = Framebuffer | ImageSource | WebGLTexture;
+/**
+ * Where a {@apilink ShaderPass} renders to: a {@apilink Framebuffer}, or `null` for the canvas backbuffer.
+ *
+ * Inside an engine frame use {@apilink ExcaliburGraphicsContextWebGL.drawTarget} to composite into the frame.
+ */
+export type ShaderPassDestination = Framebuffer | null;
+export interface ShaderPassOptions {
+    graphicsContext: ExcaliburGraphicsContextWebGL;
+    /**
+     * Name the pass for debugging
+     */
+    name?: string;
+    /**
+     * Fragment source, processed with the {@apilink glsl} tagged template (straight-alpha authoring,
+     * automatic `#version`/`precision`).
+     *
+     * Conventions available to every pass:
+     *
+     * * `uniform sampler2D u_image` - the source (positional shorthand); named sources bind to their record keys
+     * * `uniform sampler2D u_graphic` - synonym for `u_image`
+     * * `uniform sampler2D u_original` - the pipeline's original, pre-pass source
+     * * `uniform vec2 u_resolution` - destination resolution in pixels
+     * * `uniform vec2 u_texelSize` - `1.0 / primary source resolution`
+     * * `uniform float u_time_ms` - total time in milliseconds
+     * * `uniform float u_elapsed_ms` - elapsed milliseconds since the last frame when provided
+     * * `in vec2 v_uv` - 0-1 UV over the destination
+     *
+     * If omitted the pass is a passthrough (`fragColor = texture(u_image, v_uv)`)
+     */
+    fragmentSource?: string;
+    /**
+     * Declarative per-pass uniforms, the same watched dictionary as {@apilink Shader.uniforms}
+     */
+    uniforms?: UniformDictionary;
+    /**
+     * Relative resolution of this pass's output when {@apilink ShaderPipeline} auto-allocates its
+     * intermediate framebuffer, e.g. `0.5` renders at half resolution. Default 1.
+     */
+    scale?: number;
+    /**
+     * Filtering used when this pass's auto-allocated intermediate framebuffer is sampled by the
+     * next pass. Default {@apilink ImageFiltering.Blended} (linear).
+     */
+    filtering?: ImageFiltering;
+}
+export interface ShaderPassDrawOptions {
+    /**
+     * Single-source shorthand, bound as `u_image`
+     */
+    source?: ShaderPassSource;
+    /**
+     * Named sources, each record key is bound as the sampler uniform of that name
+     */
+    sources?: Record<string, ShaderPassSource>;
+    /**
+     * Where to render: a {@apilink Framebuffer} or `null` for the canvas backbuffer
+     */
+    destination: ShaderPassDestination;
+    /**
+     * Per-draw uniform values, merged over (and persisted into) the pass uniforms
+     */
+    uniforms?: UniformDictionary;
+    /**
+     * Elapsed milliseconds forwarded to `u_elapsed_ms`
+     */
+    elapsed?: number;
+}
+/**
+ * Pixel dimensions of a {@apilink ShaderPassSource}, falling back to the canvas drawing buffer
+ * for raw `WebGLTexture`s which have no queryable dimensions
+ */
+export declare function getSourceDimensions(graphicsContext: ExcaliburGraphicsContextWebGL, source: ShaderPassSource): [width: number, height: number];
+/**
+ * A single shader pass: draws a full-destination quad with a fragment shader, reading explicit
+ * sources and writing to an explicit destination.
+ *
+ * ```typescript
+ * const tint = new ex.ShaderPass({ graphicsContext, fragmentSource: myGlsl });
+ * tint.draw(sourceFramebuffer, destinationFramebuffer);
+ *
+ * // multiple named sources + per-draw uniforms
+ * merge.draw({
+ *   sources: { u_smaller: quarterRes, u_larger: halfRes },
+ *   destination: halfResOut,
+ *   uniforms: { u_strength: 2 }
+ * });
+ * ```
+ *
+ * There is no hidden bind state to sequence, each draw states its inputs and output.
+ */
+export declare class ShaderPass {
+    private _logger;
+    readonly name: string;
+    /**
+     * Relative resolution used by {@apilink ShaderPipeline} for this pass's intermediate framebuffer
+     */
+    readonly scale: number;
+    /**
+     * Filtering used by {@apilink ShaderPipeline} for this pass's intermediate framebuffer
+     */
+    readonly filtering: ImageFiltering;
+    private _graphicsContext;
+    private _fragmentSource;
+    private _initialUniforms;
+    private _shader;
+    private _layout;
+    private _disposed;
+    constructor(options: ShaderPassOptions);
+    private _initialize;
+    /**
+     * The compiled {@apilink Shader} backing this pass, compiling it if necessary
+     */
+    getShader(): Shader;
+    /**
+     * Declarative uniforms for this pass, changes are uploaded on the next draw
+     */
+    get uniforms(): UniformDictionary;
+    private _resolveSource;
+    /**
+     * Draws the pass, `source` binds as `u_image`
+     */
+    draw(source: ShaderPassSource, destination: ShaderPassDestination): void;
+    draw(options: ShaderPassDrawOptions): void;
+    /**
+     * Deletes the compiled shader program, the pass cannot be used afterwards
+     */
+    dispose(): void;
+}

package/build/esm/src/engine/graphics/context/shader-pipeline/shader-pipeline.d.ts

@@ -0,0 +1,91 @@
+import type { ExcaliburGraphicsContextWebGL } from '../excalibur-graphics-context-webgl';
+import type { Shader, UniformDictionary } from '../shader';
+import type { ShaderPassDestination, ShaderPassSource } from './shader-pass';
+import { ShaderPass } from './shader-pass';
+export interface ShaderPipelineProcessOptions {
+    /**
+     * Elapsed milliseconds forwarded to each pass's `u_elapsed_ms`
+     */
+    elapsed?: number;
+    /**
+     * Uniform values forwarded to every pass, merged over each pass's own uniforms.
+     *
+     * Materials use this to flow their custom uniforms and built-ins into the pipeline.
+     */
+    uniforms?: UniformDictionary;
+    /**
+     * Additional named sources bound to every pass after its own (`u_image`, `u_graphic`, `u_original`, ...),
+     * each record key is bound as the sampler uniform of that name.
+     *
+     * Materials use this to flow their `images` into the pipeline. Reserved pass source names
+     * cannot be overridden.
+     */
+    sources?: Record<string, ShaderPassSource>;
+}
+/**
+ * Adds `extra` sources onto `sources` without clobbering the pass's own reserved names
+ * @internal
+ */
+export declare function mergePassSources(sources: Record<string, ShaderPassSource>, extra?: Record<string, ShaderPassSource>): Record<string, ShaderPassSource>;
+/**
+ * Anything that can transform a source into a destination through one or more shader passes.
+ *
+ * {@apilink ShaderPipeline} is the built-in linear implementation; implement this directly for
+ * non-linear pass graphs (for example bloom's downsample/upsample ladder) and plug it into a
+ * {@apilink Material} or {@apilink ShaderPipelinePostProcessor} the same way.
+ */
+export interface ShaderPipelineLike {
+    process(source: ShaderPassSource, destination: ShaderPassDestination, options?: ShaderPipelineProcessOptions): void;
+    dispose?(): void;
+    /**
+     * Every compiled {@apilink Shader} this pipeline drives, in pass order. Optional — a pass graph
+     * that can't enumerate its own passes may omit this; {@apilink Material.update} falls back to
+     * just the composite shader when it's missing.
+     */
+    getShaders?(): Shader[];
+}
+/**
+ * A {@apilink ShaderPass}, or a bare fragment source string that wraps into one
+ */
+export type ShaderPassLike = string | ShaderPass;
+export interface ShaderPipelineOptions {
+    graphicsContext: ExcaliburGraphicsContextWebGL;
+    /**
+     * Name the pipeline for debugging
+     */
+    name?: string;
+    /**
+     * Ordered passes, each one reads the previous pass's output as `u_image` (`u_graphic` is
+     * accepted as a synonym; the pipeline source for the first pass) and can read the original
+     * pipeline source as `u_original`
+     */
+    passes: ShaderPassLike[];
+}
+/**
+ * Runs an ordered chain of {@apilink ShaderPass}es:
+ * `source → pass0 → fb0 → pass1 → fb1 → ... → destination`
+ *
+ * Intermediate framebuffers are allocated lazily, one per pass, sized by each pass's `scale`
+ * relative to the source. The final pass renders into the caller's destination at the
+ * destination's own size, which is what upsamples a downscaled chain back up.
+ */
+export declare class ShaderPipeline implements ShaderPipelineLike {
+    readonly name: string;
+    readonly passes: ShaderPass[];
+    private _graphicsContext;
+    private _intermediates;
+    private _disposed;
+    constructor(options: ShaderPipelineOptions);
+    /**
+     * Runs every pass in order, rendering the final pass into `destination`
+     */
+    process(source: ShaderPassSource, destination: ShaderPassDestination, options?: ShaderPipelineProcessOptions): void;
+    /**
+     * Every pass's compiled {@apilink Shader}, in pass order
+     */
+    getShaders(): Shader[];
+    /**
+     * Disposes the passes and intermediate framebuffers, the pipeline cannot be used afterwards
+     */
+    dispose(): void;
+}