# albeno-degra/custom_shader architecture

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

- Interactive diagram: https://gitdiagram.com/albeno-degra/custom_shader
- Repository: https://github.com/albeno-degra/custom_shader

## Overview

##### Project type and purpose
- This is a single‐codebase Flutter demo app (mobile) that integrates custom GLSL fragment shaders to render a dynamic checkerboard background (Photoshop‐style transparency visualization).
- Primary use case: teach and experiment with Flutter’s shader API, blending UI widgets with GPU‐accelerated fragment shaders.

##### File structure
Top-level:
- .fvm, fvm_config.json, fvmrc – Flutter version management
- pubspec.yaml / pubspec.lock – dependency and asset declaration
- ios/… – native iOS project generated by Flutter
- lib/… – Dart code, organized into subfolders:
– core/ – shared services (image_loader.dart, shader_cache.dart)
– features/ – UI features grouped by functionality (dash, photo_shimmer, pokemons)
– shaders/ – Flutter widgets wrapping shader programs and helper code
– main.dart – application entrypoint
- shaders/*.frag – raw GLSL fragment shader source

##### Key insights from README
- Emphasis on a custom FragmentShader using Flutter’s API.
- GPU‐accelerated demo.

##### Main components
A. Flutter Application Layer (Dart)
1. main.dart (App bootstrap)
2. Feature Widgets (/features/dash, /features/photo_shimmer, /features/pokemons)
B. Core Services
1. image_loader.dart – async image loading
2. shader_cache.dart – compiles / caches FragmentShaders
C. Shader Layer
1. CheckerboardShaderWidget, FlickBoxShaderWidget, etc. (lib/shaders/…)
2. Raw GLSL files (shaders/checkerboard.frag, shaders/pixel_flicker.frag)
D. Flutter Engine & GPU
1. Dart VM & Skia renderer
2. GPU executes compiled fragment shaders
E. Native Platform
1. iOS Runner project (AppDelegate.swift, Info.plist, asset catalogs)
2. Asset pipeline (images, shader .frag files bundled via pubspec.yaml)
F. External Tools
1. FVM – locks Flutter SDK version
2. pub – package manager

##### Relationships & data flows
1. User taps / interacts → Dart UI (Feature Widget)
2. Feature Widget requests shader from shader_cache
3. shader_cache compiles .frag GLSL → FragmentShader object
4. Flutter Engine uploads shader to GPU
5. GPU runs shader each frame → draws checkerboard pattern into a Canvas
6. Canvas is composited into Flutter scene → displayed on iOS screen
7. image_loader (if used) fetches image bits and feeds into shader inputs

##### Architectural patterns & design principles
- Modular “feature” folder structure: each UI feature isolated
- Separation of concerns: core services vs feature widgets vs shader code
- GPU offload: heavy work in shader layer, minimal CPU-side logic
- Flutter’s standard layering: Dart UI → engine → native host

##### Specific elements
- Asset bundling path: pubspec.yaml → Runner.app → GPU
- Notes on FVM version lock and pub dependencies

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Flutter Application Layer
    subgraph "Flutter Application Layer"
        direction TB
        main["main.dart"]:::dart
        subgraph "Feature Widgets"
            direction TB
            dashWidget["DashWidget"]:::dart
            dashProps["DashWidget Props"]:::dart
            magicBg["MagicBackground"]:::dart
            magicDash["MagicDash"]:::dart
            photoShimmer["PhotoShimmerWidget"]:::dart
            pokemons["PokemonsWidget"]:::dart
        end
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        imageLoader["image_loader.dart"]:::dart
        shaderCache["shader_cache.dart"]:::dart
    end

    %% Shader Layer
    subgraph "Shader Layer"
        direction TB
        checkerWidget["CheckerboardShaderWidget"]:::dart
        flickWidget["FlickBoxesShaderWidget"]:::dart
        subgraph "Raw GLSL Shaders"
            direction TB
            checkerFrag["checkerboard.frag"]:::shaderAsset
            pixelFrag["pixel_flicker.frag"]:::shaderAsset
        end
    end

    %% Flutter Engine & GPU
    subgraph "Flutter Engine & GPU"
        direction TB
        engine["Dart VM & Skia Renderer"]:::engine
        gpu["GPU"]:::engine
    end

    %% Native iOS Layer
    subgraph "Native iOS Layer"
        direction TB
        runner["Runner Project"]:::native
        appDelegate["AppDelegate.swift"]:::native
        infoPlist["Info.plist"]:::native
        assetsCat["Assets.xcassets"]:::native
    end

    %% External Tools & Assets
    subgraph "External Tools & Assets"
        direction TB
        fvm[".fvm Config"]:::tool
        pubspec["pubspec.yaml"]:::tool
    end

    %% Connections
    main -->|UI Event| dashWidget
    main -->|UI Event| photoShimmer
    main -->|UI Event| pokemons
    dashWidget -->|load image| imageLoader
    photoShimmer -->|load image| imageLoader
    dashWidget -->|request shader| shaderCache
    magicBg -->|request shader| shaderCache
    magicDash -->|request shader| shaderCache
    pokemons -->|request shader| shaderCache
    shaderCache -->|"compile & cache shader"| checkerWidget
    shaderCache -->|"compile & cache shader"| flickWidget
    checkerWidget -->|"upload shader"| engine
    flickWidget -->|"upload shader"| engine
    engine -->|"execute shader each frame"| gpu
    gpu -->|"draw frame"| engine
    engine -->|"composite canvas"| dashWidget
    engine -->|"composite canvas"| photoShimmer
    engine -->|"composite canvas"| pokemons
    pubspec -.->|bundles assets| runner
    runner -->|includes shaders| checkerFrag
    runner -->|includes shaders| pixelFrag

    %% Click Events
    click main "https://github.com/albeno-degra/custom_shader/blob/main/lib/main.dart"
    click dashWidget "https://github.com/albeno-degra/custom_shader/blob/main/lib/features/dash/widgets/dash_widget.dart"
    click dashProps "https://github.com/albeno-degra/custom_shader/blob/main/lib/features/dash/widgets/dash_widgets_props.dart"
    click magicBg "https://github.com/albeno-degra/custom_shader/blob/main/lib/features/dash/widgets/magic_background.dart"
    click magicDash "https://github.com/albeno-degra/custom_shader/blob/main/lib/features/dash/widgets/magic_dash.dart"
    click photoShimmer "https://github.com/albeno-degra/custom_shader/blob/main/lib/features/photo_shimmer/widgets/photo_shimmer.dart"
    click pokemons "https://github.com/albeno-degra/custom_shader/blob/main/lib/features/pokemons/widgets/pokemons_widget.dart"
    click imageLoader "https://github.com/albeno-degra/custom_shader/blob/main/lib/core/image_loader.dart"
    click shaderCache "https://github.com/albeno-degra/custom_shader/blob/main/lib/shaders/shader_cache.dart"
    click checkerWidget "https://github.com/albeno-degra/custom_shader/blob/main/lib/shaders/checkerboard_shader/checkerboard_shader_widget.dart"
    click flickWidget "https://github.com/albeno-degra/custom_shader/blob/main/lib/shaders/flick_box_shader/flick_boxes_shader_widget.dart"
    click checkerFrag "https://github.com/albeno-degra/custom_shader/blob/main/shaders/checkerboard.frag"
    click pixelFrag "https://github.com/albeno-degra/custom_shader/blob/main/shaders/pixel_flicker.frag"
    click fvm "https://github.com/albeno-degra/custom_shader/blob/main/.fvm/fvm_config.json"
    click pubspec "https://github.com/albeno-degra/custom_shader/blob/main/pubspec.yaml"
    click runner "https://github.com/albeno-degra/custom_shader/tree/main/ios/Runner"
    click appDelegate "https://github.com/albeno-degra/custom_shader/blob/main/ios/Runner/AppDelegate.swift"
    click infoPlist "https://github.com/albeno-degra/custom_shader/blob/main/ios/Runner/Info.plist"
    click assetsCat "https://github.com/albeno-degra/custom_shader/blob/main/ios/Runner/Assets.xcassets"

    %% Styles
    classDef dart fill:#D6EAF8,stroke:#2E86C1,color:#1B4F72
    classDef shaderAsset fill:#ABEBC6,stroke:#27AE60,color:#145A32
    classDef engine fill:#D5D8DC,stroke:#797D7F,color:#424949
    classDef native fill:#FAD7A0,stroke:#D68910,color:#7E5109
    classDef tool fill:#F5B7B1,stroke:#EC7063,color:#7B241C
```
