# pmndrs/postprocessing architecture

> Architecture diagram of the GitHub repository pmndrs/postprocessing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmndrs/postprocessing
- Repository: https://github.com/pmndrs/postprocessing

## Overview

##### Project type and purpose
- This is an open-source JavaScript/TypeScript library (“postprocessing”) that extends three.js with a flexible post-processing pipeline.
- Its main purpose is to provide pre-built “Effects” and “Passes” (bloom, antialiasing, depth of field, etc.) that can be composed via an EffectComposer to manipulate the final rendered image in WebGL.

##### High-level file structure analysis
- Top level
– src/ – the library’s core code, subdivided into modules:
- core (EffectComposer, Timer, Resolution, etc.)
- passes (RenderPass, EffectPass, CopyPass, DepthPass, etc.)
- effects (BloomEffect, SSAOEffect, ToneMappingEffect, etc.)
- materials (shader wrappers + GLSL under materials/glsl/)
- loaders (LUT loaders, SMAA loaders)
- textures (lookup tables, noise, smaa image data)
- utils (helper functions)
- enums (typed constants used across the library)
– demo/ – a standalone frontend showcasing each effect in action (HTML + JS demos + 3D models + assets)
– manual/ – documentation website source (Markdown, CSS/SCSS, JS for the site, layouts, static assets)
– test/ – unit tests mirroring src/ structure to verify each component
– types/, tsconfig.json – TypeScript definitions
– esbuild.js, package.json, CI/CD workflows, config files

##### Key insights from the README
- The library plugs into three.js by accepting a WebGLRenderer and providing an EffectComposer.
- Effects are implemented by combining Materials (wrapping GLSL shaders) with Pass logic.
- A single-triangle fullscreen pass optimization is applied for performance.

a. Main components
- External dependency: three.js (WebGLRenderer, Scene, Camera)
- Core: EffectComposer
- Passes: RenderPass, EffectPass, ShaderPass, CopyPass, DepthPass, etc.
- Effects: BloomEffect, SSAOEffect, GlitchEffect, ToneMappingEffect, etc.
- Materials + Shaders: shader wrappers + GLSL code under materials/glsl/ and effects/glsl/
- Loaders & Textures: LUT loaders, SMAA loaders, noise textures, lookup tables
- Utilities & Enums: shared helpers, timing, IDs, constant definitions
- Clients: Demo application, Documentation site, Consumer applications

b. Relationships and interactions
– Client instantiates a three.js WebGLRenderer → passed into EffectComposer
– Composer holds an ordered list of Pass objects
– Each Pass:
- may render the scene (RenderPass) or process a texture (EffectPass)
- may own one or more Materials (shaders) and use Textures/Loaders
– Effects are pure shader-based subcomponents that the EffectPass orchestrates
– Utilities and Enums flow into all modules as common dependencies

c. Architectural patterns & principles
– Plugin/composition pattern: Effects and Passes can be registered and chained
– Single-responsibility: each module (core, pass, effect, material, loader) has a well-defined role
– High cohesion: shader code grouped with its material wrapper
– Low coupling: Passes depend only on abstract interfaces (textures, materials, render targets)

d. Key technologies & frameworks
– three.js (WebGLRenderer, Scene, Camera, Texture types)
– esbuild (build script)
– SCSS & static site generator for manual/
– Jest (or similar) for tests
– TypeScript type definitions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        DemoApp["Demo Application"]:::client
        ManualSite["Documentation Site"]:::client
        ConsumerApp["Consumer Application"]:::client
    end

    %% External Dependency
    External["three.js (WebGLRenderer, Scene, Camera)"]:::external

    %% Core Modules
    subgraph "Core Modules"
        Composer["EffectComposer"]:::core
        Timer["Timer"]:::core
        Resolution["Resolution"]:::core
    end

    %% Passes
    subgraph "Passes"
        RenderPass["RenderPass"]:::pass
        EffectPass["EffectPass"]:::pass
        CopyPass["CopyPass"]:::pass
        DepthPass["DepthPass"]:::pass
        ShaderPass["ShaderPass"]:::pass
    end

    %% Effects
    subgraph "Effects"
        EffectBase["Effect (base)"]:::effect
        BloomEffect["BloomEffect"]:::effect
        SSAOEffect["SSAOEffect"]:::effect
        ToneMappingEffect["ToneMappingEffect"]:::effect
    end

    %% Materials & Shaders
    subgraph "Materials & Shaders"
        EffectMaterial["EffectMaterial"]:::material
        MaterialsGLSL["Materials GLSL shaders"]:::shader
        EffectsGLSL["Effects GLSL shaders"]:::shader
        BlendMode["BlendMode (blending)"]:::shader
        BlendGLSL["Blending GLSL shaders"]:::shader
    end

    %% Loaders & Textures
    subgraph "Loaders & Textures"
        LUT3dlLoader["LUT3dlLoader"]:::loader
        LUTCubeLoader["LUTCubeLoader"]:::loader
        SMAAImageLoader["SMAAImageLoader"]:::loader
        LoadersIndex["Loaders Index"]:::loader
        LookupTexture["LookupTexture"]:::texture
        NoiseTexture["NoiseTexture"]:::texture
        SMAATextures["SMAA Textures"]:::texture
    end

    %% Utilities & Enums
    subgraph "Utilities & Enums"
        UtilsIndex["Utils Index"]:::util
        IdManager["IdManager"]:::util
        Enums["Enums (constants)"]:::enum
    end

    %% Connections
    DemoApp -->|"instantiate"| Composer
    ManualSite -->|"instantiate"| Composer
    ConsumerApp -->|"instantiate"| Composer

    External -->|"provides Renderer"| Composer

    Composer -->|"addPass()"| RenderPass
    Composer -->|"addPass()"| EffectPass
    Composer -->|"addPass()"| CopyPass
    Composer -->|"addPass()"| DepthPass
    Composer -->|"addPass()"| ShaderPass

    EffectPass -->|"uses Effects"| BloomEffect
    EffectPass -->|"uses Effects"| SSAOEffect
    EffectPass -->|"uses Effects"| ToneMappingEffect

    RenderPass -->|"render() writes to"| Composer
    CopyPass -->|"processes texture"| Composer
    DepthPass -->|"captures depth"| Composer
    ShaderPass -->|"applies shader"| Composer

    RenderPass -->|"owns material"| EffectMaterial
    EffectPass -->|"owns material"| EffectMaterial
    CopyPass -->|"owns material"| EffectMaterial
    DepthPass -->|"owns material"| EffectMaterial
    ShaderPass -->|"owns material"| EffectMaterial

    EffectMaterial -->|"wraps shaders"| MaterialsGLSL
    BloomEffect -->|"shader code"| EffectsGLSL
    SSAOEffect -->|"shader code"| EffectsGLSL
    ToneMappingEffect -->|"shader code"| EffectsGLSL
    BlendMode -->|"blending logic"| BlendGLSL

    RenderPass -->|"may use textures"| LookupTexture
    EffectPass -->|"may use textures"| NoiseTexture
    EffectPass -->|"may use loaders"| LUT3dlLoader
    EffectPass -->|"may use loaders"| LUTCubeLoader
    EffectPass -->|"may use loaders"| SMAAImageLoader

    UtilsIndex -->|"shared helpers"| Composer
    UtilsIndex -->|"shared helpers"| RenderPass
    UtilsIndex -->|"shared helpers"| EffectPass
    IdManager -->|"ID management"| Composer

    Enums -->|"constants"| Composer
    Enums -->|"constants"| RenderPass
    Enums -->|"constants"| EffectPass

    %% Click Events
    click Composer "https://github.com/pmndrs/postprocessing/blob/main/src/core/EffectComposer.js"
    click RenderPass "https://github.com/pmndrs/postprocessing/blob/main/src/passes/RenderPass.js"
    click EffectPass "https://github.com/pmndrs/postprocessing/blob/main/src/passes/EffectPass.js"
    click CopyPass "https://github.com/pmndrs/postprocessing/blob/main/src/passes/CopyPass.js"
    click DepthPass "https://github.com/pmndrs/postprocessing/blob/main/src/passes/DepthPass.js"
    click BloomEffect "https://github.com/pmndrs/postprocessing/blob/main/src/effects/BloomEffect.js"
    click SSAOEffect "https://github.com/pmndrs/postprocessing/blob/main/src/effects/SSAOEffect.js"
    click ToneMappingEffect "https://github.com/pmndrs/postprocessing/blob/main/src/effects/ToneMappingEffect.js"
    click EffectBase "https://github.com/pmndrs/postprocessing/blob/main/src/effects/Effect.js"
    click EffectMaterial "https://github.com/pmndrs/postprocessing/blob/main/src/materials/EffectMaterial.js"
    click MaterialsGLSL "https://github.com/pmndrs/postprocessing/tree/main/src/materials/glsl/"
    click EffectsGLSL "https://github.com/pmndrs/postprocessing/tree/main/src/effects/glsl/"
    click BlendMode "https://github.com/pmndrs/postprocessing/blob/main/src/effects/blending/BlendMode.js"
    click BlendGLSL "https://github.com/pmndrs/postprocessing/tree/main/src/effects/blending/glsl/"
    click LUT3dlLoader "https://github.com/pmndrs/postprocessing/blob/main/src/loaders/LUT3dlLoader.js"
    click LUTCubeLoader "https://github.com/pmndrs/postprocessing/blob/main/src/loaders/LUTCubeLoader.js"
    click SMAAImageLoader "https://github.com/pmndrs/postprocessing/blob/main/src/loaders/SMAAImageLoader.js"
    click LoadersIndex "https://github.com/pmndrs/postprocessing/blob/main/src/loaders/index.js"
    click LookupTexture "https://github.com/pmndrs/postprocessing/blob/main/src/textures/LookupTexture.js"
    click NoiseTexture "https://github.com/pmndrs/postprocessing/blob/main/src/textures/NoiseTexture.js"
    click SMAATextures "https://github.com/pmndrs/postprocessing/tree/main/src/textures/smaa/"
    click UtilsIndex "https://github.com/pmndrs/postprocessing/blob/main/src/utils/index.js"
    click Enums "https://github.com/pmndrs/postprocessing/blob/main/src/enums/BlendFunction.js"
    click DemoApp "https://github.com/pmndrs/postprocessing/blob/main/demo/src/index.js"
    click ManualSite "https://github.com/pmndrs/postprocessing/blob/main/manual/assets/js/src/index.js"

    %% Styles
    classDef core fill:#cfe2ff,stroke:#325a9b,color:#000
    classDef pass fill:#ffe5b4,stroke:#c47f00,color:#000
    classDef effect fill:#d4edda,stroke:#2e7d32,color:#000
    classDef material fill:#fff3cd,stroke:#b38600,color:#000
    classDef shader fill:#fff3cd,stroke:#b38600,color:#000
    classDef loader fill:#e4d7f5,stroke:#5b2e8a,color:#000
    classDef texture fill:#e4d7f5,stroke:#5b2e8a,color:#000
    classDef util fill:#f0f0f0,stroke:#888,color:#000
    classDef enum fill:#f0f0f0,stroke:#888,color:#000
    classDef external fill:#f8d7da,stroke:#a71d2a,color:#000
    classDef client fill:#d1ecf1,stroke:#0c5460,color:#000
```
