# pixpark/gpupixel architecture

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

- Interactive diagram: https://gitdiagram.com/pixpark/gpupixel
- Repository: https://github.com/pixpark/gpupixel

## Overview

##### Main Components
- Filter Module: The “src/filter” directory contains many filter implementations (e.g., beauty_face_filter, canny_edge_detection_filter, grayscale_filter) which implement distinct image/video processing effects.
- Face Detection and Advanced Processing: The “src/face_detect” and integration with third-party libraries (in “src/third_party/mars-face” and “src/third_party/mnn”) indicate extra functionality, such as face alignment and neural network support.
- Source & Sink Modules: The “src/source” and “src/sink” directories (including objc subdirectories) abstract input (camera, images, raw data) and output mechanisms (rendering to a view, writing data).
- Demo Applications: The “demo” directory includes multiple platform-specific demos (desktop, iOS, mac) to show how GPUPixel is integrated into applications.
- Build and Configuration: The project uses a mixture of CMake (e.g., CMakeLists.txt in root, src, demo directories) and toolchain files. There are also Dockerfiles and gradle files for Android, emphasizing a uniform build configuration across platforms.
- Third-Party Integrations: Inside “src/third_party” are libraries like glad, glfw, imgui, libyuv, mars-face, and MNN. These provide low-level graphics, UI helpers, and even supplemental neural network functionality. They are key dependencies.

##### Relationships/Interactions
- Data Flow: The overall data flow resembles a pipeline. Input is captured by “source” modules, passed to the core processing engine (which manages framebuffers and GPU contexts), processed by one or more filters (which can be grouped), and then output via the “sink” modules or rendered in demo applications.
- Control Flow: The demo apps provide a front-end that calls into the core library. They often instantiate a “GPUPixel” object, set up a rendering context (using OpenGL/ES), and then apply a chain of filters.
- External Dependencies: Third-party libraries are used to simplify or extend certain functionalities (e.g., imgui for UI elements, mars-face for face detection, libyuv for format conversions, and MNN for neural network operations).

##### Architectural Patterns and Design Principles
- Modular Pipeline Architecture: Clearly, the design separates image acquisition (source), processing (core, filters), and output (sink) in a pipeline style.
- Cross-Platform Abstraction: There are platform-adapted implementations (e.g., Android Java wrappers, iOS Objective-C source files) that abstract platform-specific details away from the core library.
- Reusable and Extensible: The use of subdirectories like “filter” and “third_party” indicates that the design emphasizes modularity, easing the addition of new functionality or integration with other systems.

##### Relevant Technologies/Frameworks
- C++11, OpenGL/ES for graphics processing.
- CMake for cross-platform builds.
- Platform-specific build systems for Android (Gradle) and iOS (Xcode projects).
- Third-party libraries: imgui, glfw, glad, libyuv, mars-face, and MNN play significant roles.

- Application Layer: Demo apps (iOS, Android, Desktop, Mac).
- Interface Layer: Platform-specific bindings/wrappers.
- Core Engine: Includes the core context (GPU pipeline), filter chain (as a set of modules), face detection module.
- External Collaborators: Outward connections to third-party libraries.
- Then, drill down into the core engine: show how input data is received by “source” classes, passed to “gpupixel_context” which manages GPU framebuffers and then sent through a series of filters.
- Design for extendability (how filters are grouped and can be added/removed dynamically).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        Demo("Demo Applications"):::demo
    end

    %% Interface Layer
    subgraph "Interface Layer"
        Source("Input/Source Modules"):::source
        Sink("Output/Sink Modules"):::sink
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        Core("Core GPU Processing Engine"):::core
        Filter("Filter Module\n(Beauty,Edge,Grayscale)"):::filter
        subgraph "Face Detection & Advanced"
            FaceDet("Face Detector"):::face
            Mars("Mars-Face Integration"):::face
            MNN("Neural Network Support"):::face
        end
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        ThirdParty("Third-Party Libraries\n(glad,glfw,imgui,libyuv,etc.)"):::thirdparty
        Build("Build & Config\n(CMake,Gradle,Docker)"):::build
    end

    %% Data Flow Connections
    Source -->|"frames"| Core
    Core -->|"processes"| Filter
    Filter -->|"outputs"| Sink
    Demo -->|"calls"| Core

    %% Integration within Core Engine
    Core -->|"integrates"| FaceDet
    FaceDet -->|"uses"| Mars
    FaceDet -->|"uses"| MNN

    %% External Dependencies Connections
    Build -->|"builds"| Demo
    ThirdParty -->|"supports"| Core
    ThirdParty -->|"assists"| Filter
    ThirdParty -->|"used by"| FaceDet

    %% Click Events
    click Core "https://github.com/pixpark/gpupixel/tree/main/src/core"
    click Filter "https://github.com/pixpark/gpupixel/tree/main/src/filter"
    click FaceDet "https://github.com/pixpark/gpupixel/tree/main/src/face_detect"
    click Mars "https://github.com/pixpark/gpupixel/tree/main/src/third_party/mars-face"
    click MNN "https://github.com/pixpark/gpupixel/tree/main/src/third_party/mnn"
    click Source "https://github.com/pixpark/gpupixel/tree/main/src/source"
    click Sink "https://github.com/pixpark/gpupixel/tree/main/src/sink"
    click Demo "https://github.com/pixpark/gpupixel/tree/main/demo"
    click Build "https://github.com/pixpark/gpupixel/blob/main/CMakeLists.txt"
    click ThirdParty "https://github.com/pixpark/gpupixel/tree/main/src/third_party"

    %% Styles
    classDef demo fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef source fill:#e6ffe6,stroke:#009900,stroke-width:2px;
    classDef sink fill:#e6e6ff,stroke:#0000cc,stroke-width:2px;
    classDef core fill:#e6ffff,stroke:#00cccc,stroke-width:2px;
    classDef filter fill:#ffffe6,stroke:#cccc00,stroke-width:2px;
    classDef face fill:#f0e6ff,stroke:#9900cc,stroke-width:2px;
    classDef thirdparty fill:#e6f7ff,stroke:#0099cc,stroke-width:2px;
    classDef build fill:#f2e6d9,stroke:#cc6600,stroke-width:2px;
```
