# projectm-visualizer/frontend-sdl-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/projectm-visualizer/frontend-sdl-cpp
- Repository: https://github.com/projectm-visualizer/frontend-sdl-cpp

## Overview

##### Project type and purpose
- This is a desktop full-stack C++ application (“projectMSDL”), serving as an SDL2-based frontend for the projectM music visualization library.
- It captures audio input, feeds it into libprojectM, renders visuals in real time, and provides a GUI overlay plus system notifications.

##### File structure
- Top-level CMake files and scripts (CMakeLists.txt, cmake/*) define a cross-platform build system.
- src/ holds the core modules:
- AudioCapture (SDL and WASAPI backends)
- ProjectMWrapper (bridge to libprojectM)
- RenderLoop and FPSLimiter
- SDLRenderingWindow (window & OpenGL context)
- main.cpp (app entry point)
- src/gui/ contains the GUI windows and widgets (menus, dialogs, preset selector, toasts).
- src/notifications/ contains adapters to post system toast/playback control/quit notifications.
- src/resources/ holds shipped presets, desktop file, license.
- vendor/, vcpkg.json indicate dependency management; .github/ holds CI.

##### README for additional insights
- Lists external dependencies (SDL2, POCO, FreeType, libprojectM).
- Describes build & install via CMake.
- Mentions how the application uses configuration files and runtime arguments.

##### Main components & interactions
a. Components
1. Audio Capture Layer
- AudioCaptureSDL / AudioCaptureWASAPI
2. libprojectM Integration
- ProjectMWrapper → invokes projectM core for FFT + visual generation
3. Rendering Layer
- RenderLoop + FPSLimiter
- SDLRenderingWindow → OpenGL context
4. GUI Layer
- ProjectMGUI orchestrates windows (MainMenu, FileChooser, SettingsWindow, etc.)
5. Notification Layer
- DisplayToastNotification, PlaybackControlNotification, QuitNotification, UpdateWindowTitleNotification
6. Resources & Configuration
- presets, textures, projectMSDL.properties
7. External Dependencies
- SDL2, POCO, FreeType, libprojectM
b. Relationships & data flow
- Audio Capture → feeds audio samples → ProjectMWrapper
- RenderLoop + SDLRenderingWindow → draws visuals on screen
- GUI Layer → overlays UI, sends user commands → may affect ProjectMWrapper (e.g. change preset)
- Notification Layer → listens to events (track change, quit) → invokes OS notifications via POCO
- Resources loaded at startup (preset and texture paths)
c. Architectural patterns & principles
- Strategy pattern for pluggable AudioCapture backends
- Wrapper/facade around libprojectM
- Modular separation: capture → processing → rendering → UI → notifications
- CMake-driven dependency injection via FIND_PACKAGE and vcpkg
d. Key technologies
- C++17, CMake
- SDL2 for input, window, GL context
- OpenGL (via SDL2) for rendering visuals
- POCO for cross-platform notifications and filesystem
- FreeType for UI text (optional)
- libprojectM for FFT & visualization logic

##### Elements
- Audio data → ProjectMWrapper
- Frame commands → RenderLoop → SDLRenderingWindow
- UI actions → ProjectMWrapper or RenderLoop
- Events → Notification modules
- Core engine (blue)
- UI (green)
- Notifications (orange)
- External deps (gray)
- Rectangles for modules
- Clouds or parallelograms for external libs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level application container
    subgraph "projectMSDL Application"
        direction TB

        %% Audio Layer
        subgraph "Audio Layer"
            direction TB
            AC_BASE["AudioCapture (Interface)"]:::core
            AC_SDL["AudioCaptureSDL"]:::core
            AC_WASAPI["AudioCaptureWASAPI"]:::core
        end

        %% Visualization Engine
        subgraph "Visualization Engine"
            direction TB
            PM_WRAP["ProjectMWrapper"]:::core
        end

        %% Rendering Layer
        subgraph "Rendering Layer"
            direction TB
            RL["RenderLoop"]:::core
            FPS["FPSLimiter"]:::core
            WIN["SDLRenderingWindow"]:::core
        end

        %% GUI Layer
        subgraph "GUI Layer"
            direction TB
            GUI_MAIN["ProjectMGUI"]:::ui
            GUI_MENU["MainMenu"]:::ui
            GUI_FILE["FileChooser"]:::ui
            GUI_PRESET["PresetSelection"]:::ui
            GUI_SETTINGS["SettingsWindow"]:::ui
            GUI_ABOUT["AboutWindow"]:::ui
            GUI_HELP["HelpWindow"]:::ui
            GUI_BROWSER["SystemBrowser"]:::ui
            GUI_TOASTUI["ToastMessage"]:::ui
        end

        %% Notification Layer
        subgraph "Notification Layer"
            direction TB
            N_TOAST["DisplayToastNotification"]:::notif
            N_PLAY["PlaybackControlNotification"]:::notif
            N_QUIT["QuitNotification"]:::notif
            N_TITLE["UpdateWindowTitleNotification"]:::notif
        end

        %% Resources & Config
        RES["Resources & Configuration"]:::data

        %% Application Entry
        APP["ProjectMSDLApplication\n(main.cpp)"]:::core

    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        SDL2["SDL2"]:::ext
        POCO["POCO"]:::ext
        FT["FreeType"]:::ext
        LIBPM["libprojectM"]:::ext
    end

    %% Relationships
    AC_BASE --> AC_SDL
    AC_BASE --> AC_WASAPI
    AC_SDL --> PM_WRAP
    AC_WASAPI --> PM_WRAP
    PM_WRAP --> RL
    RL --> FPS
    RL --> WIN
    GUI_MAIN --> GUI_MENU
    GUI_MAIN --> GUI_FILE
    GUI_MAIN --> GUI_PRESET
    GUI_MAIN --> GUI_SETTINGS
    GUI_MAIN --> GUI_ABOUT
    GUI_MAIN --> GUI_HELP
    GUI_MAIN --> GUI_BROWSER
    GUI_MAIN --> GUI_TOASTUI
    GUI_MAIN --> PM_WRAP
    GUI_MAIN --> RL
    RL --> GUI_MAIN
    APP --> AC_BASE
    APP --> PM_WRAP
    APP --> RL
    APP --> GUI_MAIN
    APP --> N_TOAST
    APP --> N_PLAY
    APP --> N_QUIT
    APP --> N_TITLE
    RES --> PM_WRAP
    RES --> GUI_MAIN

    %% Notifications
    PM_WRAP --> N_TOAST
    PM_WRAP --> N_PLAY
    PM_WRAP --> N_QUIT
    PM_WRAP --> N_TITLE

    %% External links (dashed)
    SDL2 -.-> AC_SDL
    SDL2 -.-> WIN
    LIBPM -.-> PM_WRAP
    POCO -.-> N_TOAST
    POCO -.-> N_PLAY
    POCO -.-> N_QUIT
    POCO -.-> N_TITLE
    FT -.-> GUI_MAIN

    %% Click Events
    click AC_BASE "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/AudioCapture.h"
    click AC_BASE "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/AudioCapture.cpp"
    click AC_SDL "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/AudioCaptureImpl_SDL.h"
    click AC_SDL "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/AudioCaptureImpl_SDL.cpp"
    click AC_WASAPI "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/AudioCaptureImpl_WASAPI.h"
    click AC_WASAPI "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/AudioCaptureImpl_WASAPI.cpp"
    click PM_WRAP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/ProjectMWrapper.h"
    click PM_WRAP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/ProjectMWrapper.cpp"
    click RL "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/RenderLoop.h"
    click RL "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/RenderLoop.cpp"
    click FPS "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/FPSLimiter.h"
    click FPS "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/FPSLimiter.cpp"
    click WIN "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/SDLRenderingWindow.h"
    click WIN "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/SDLRenderingWindow.cpp"
    click APP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/main.cpp"
    click APP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/ProjectMSDLApplication.h"
    click APP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/ProjectMSDLApplication.cpp"
    click GUI_MAIN "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/ProjectMGUI.h"
    click GUI_MAIN "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/ProjectMGUI.cpp"
    click GUI_MENU "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/MainMenu.h"
    click GUI_MENU "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/MainMenu.cpp"
    click GUI_FILE "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/FileChooser.h"
    click GUI_FILE "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/FileChooser.cpp"
    click GUI_PRESET "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/PresetSelection.h"
    click GUI_PRESET "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/PresetSelection.cpp"
    click GUI_SETTINGS "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/SettingsWindow.h"
    click GUI_SETTINGS "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/SettingsWindow.cpp"
    click GUI_ABOUT "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/AboutWindow.h"
    click GUI_ABOUT "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/AboutWindow.cpp"
    click GUI_HELP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/HelpWindow.h"
    click GUI_HELP "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/HelpWindow.cpp"
    click GUI_BROWSER "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/SystemBrowser.h"
    click GUI_BROWSER "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/SystemBrowser.cpp"
    click GUI_TOASTUI "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/ToastMessage.h"
    click GUI_TOASTUI "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/gui/ToastMessage.cpp"
    click N_TOAST "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/DisplayToastNotification.h"
    click N_TOAST "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/DisplayToastNotification.cpp"
    click N_PLAY "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/PlaybackControlNotification.h"
    click N_PLAY "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/PlaybackControlNotification.cpp"
    click N_QUIT "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/QuitNotification.h"
    click N_QUIT "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/QuitNotification.cpp"
    click N_TITLE "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/UpdateWindowTitleNotification.h"
    click N_TITLE "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/notifications/UpdateWindowTitleNotification.cpp"
    click RES "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/resources/projectMSDL.properties.in"
    click RES "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/resources/projectMSDL.desktop"
    click RES "https://github.com/projectm-visualizer/frontend-sdl-cpp/blob/master/src/resources/gpl-3.0.txt"

    %% Styles
    classDef core fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef ui fill:#E6FFEA,stroke:#22863A,color:#22863A;
    classDef notif fill:#FFEFD5,stroke:#D57A00,color:#D57A00;
    classDef ext fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef data fill:#FFF5D1,stroke:#D4A12D,color:#D4A12D;
```
