# metalpetal/metalpetal architecture

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

- Interactive diagram: https://gitdiagram.com/metalpetal/metalpetal
- Repository: https://github.com/metalpetal/metalpetal

## Overview

##### Project type and purpose
- MetalPetal is an open-source, cross-platform image-processing framework (library) built on Apple’s Metal GPU API. It provides a set of core components (MTIContext, MTIImage, MTIFilter, MTIKernel) to define image-processing pipelines, optimize render graphs, and dispatch GPU work.

##### File structure
- Top level
- CI/CD / repo metadata (.github/, .gitignore, CONTRIBUTING.md, README.md)
- Distribution (Podfile, Package.swift, MetalPetal.podspec.json)
- Core Objective-C implementation under Frameworks/MetalPetal (shaders, filters, kernel, context, UI adapters for SceneKit/SpriteKit)
- Swift overlay under Sources/MetalPetal (pure Swift wrappers, convenience APIs)
- Example apps under MetalPetalExamples (iOS, macOS targets, SwiftUI/bridging headers, shader samples)
- Unit tests under Tests/MetalPetalTests and TestHelpers
- Code-generation utilities under Utilities/ (BoilerplateGenerator, PodspecGenerator, SwiftPackageGenerator, etc.)

##### README for additional insights
- Core concepts: MTIContext (rendering context & caches), MTIImage (lazy “recipe” for a texture), MTIFilter (parameterized image transform), MTIKernel (compiles Metal pipelines)
- Design goals: easy API, high performance, extensibility, Swifty interfaces
- External integrations: SceneKit, SpriteKit, Core Image, VideoIO, AVFoundation

##### Components & interactions
a. Main components
- Client APIs (Swift & Objective-C fronts)
- Core library layers:
– MTIContext (render graph manager, cache)
– MTIImagePromise / MTIImage (immutable recipe nodes)
– MTIFilter (graph nodes with parameters)
– MTIKernel (render/compute pipeline builder)
- Metal runtime: MTLDevice → MTLCommandQueue → MTLCommandBuffer → MTLRenderCommandEncoder / MTLComputeCommandEncoder
- MetalPerformanceShaders (optional kernels)
- External adapters: SceneKitRenderer, SpriteKitRenderer, CoreImageKernel, VideoIO, AVFoundation
- Utilities & build tools (code generators, pods, SPM)
- Example applications (consume the public API)

b. Relationships & data flows
– Client code → constructs MTIImage and MTIFilter graph → submits to MTIContext
– MTIContext inspects graph → applies render-graph optimizations → compiles or reuses pipeline states via MTIKernel
– MTIContext issues commands to Metal:
· allocate textures → encode render or compute passes → store or cache intermediate results
· coordinate MPS kernels when available
– MTIContext returns final MTLTexture or populates CVPixelBuffer / CGImage / CIImage
– UI components (MTIImageView or MTIThreadSafeImageView) pull from MTIContext to display
– Adapters (SceneKit/SpriteKit) produce MTIImage inputs from scenes
– Utilities drive build-time code generation for function descriptors, shaders, podspecs, Swift packages

c. Architectural patterns & design principles
– Immutable dataflow graph (MTIImage) + builder pattern (filters)
– Lazy evaluation & “recipe” pattern (image promises)
– Render-graph optimization & caching in MTIContext
– Separation of concerns: core GPU pipeline vs. language bindings (Objective-C vs. Swift) vs. examples vs. build tools
– Plugin points: custom MTIImagePromise, custom MTITextureLoader, custom filters via MTIRenderPipelineKernel / MTIComputePipelineKernel / MTIMPSKernel

d. Key technologies & frameworks
– Metal API (MTLDevice, MTLCommandQueue, MTLRenderPipelineState)
– MetalPerformanceShaders (MPS convolution, gaussian blur, sobel, etc.)
– Swift & Objective-C binding layers
– CocoaPods & SwiftPM for distribution
– SceneKit, SpriteKit, CoreImage, AVFoundation / VideoIO for integrations

##### Elements
- Clear, boxed components labeled: “Client API (Swift/ObjC)”, “MTIContext”, “MTIImage / ImagePromise”, “MTIFilter”, “MTIKernel”, “Metal Runtime”, “MPS”, “Adapters (SceneKit/SpriteKit)”, “Utilities”, “Examples”
- from Client API → Graph (MTIImage + MTIFilter) → MTIContext → Metal Runtime → Textures → back to API or UI
- from Utilities → Core Framework (code generation at build time)
- from Adapters → Graph (feeding MTIImage nodes)
- Core engine (e.g. blue rectangles)
- API layers (green)
- External dependencies (orange)
- Build tools & examples (gray)

## Diagram (Mermaid)

```mermaid
graph TB

    %% API Layer
    subgraph "Client API Layer"
        SwiftAPI["Client API (Swift)"]:::api
        ObjCAPI["Client API (ObjC)"]:::api
    end

    %% Core Engine
    subgraph "Core Engine"
        Context["MTIContext"]:::core
        Image["MTIImage / ImagePromise"]:::core
        Filter["MTIFilter"]:::core
        Kernel["MTIKernel"]:::core
    end

    %% Metal & MPS Runtime
    subgraph "Metal & MPS Runtime"
        Metal["Metal Runtime"]:::runtime
        MPS["MetalPerformanceShaders"]:::runtime
    end

    %% External Adapters
    subgraph "External Adapters"
        SceneKit["SceneKitRenderer"]:::external
        SpriteKit["SpriteKitRenderer"]:::external
        CoreImageExt["CoreImage Extension"]:::external
    end

    %% UI Components
    subgraph "UI Components"
        UIComp["MTIImageView / ThreadSafeImageView"]:::core
    end

    %% Utilities & Tools
    subgraph "Utilities & Build Tools"
        Utilities["Utilities & Code Generators"]:::tools
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        Examples["Example Applications"]:::tools
        Tests["Unit Tests"]:::tools
    end

    %% Distribution
    subgraph "Distribution"
        Dist["CocoaPods & SwiftPM Config"]:::tools
    end

    %% Relationships
    SwiftAPI -->|"constructs graph"| Image
    ObjCAPI -->|"constructs graph"| Image
    SceneKit -->|"feeds image nodes"| Image
    SpriteKit -->|"feeds image nodes"| Image
    Image -->|"graph nodes"| Filter
    Filter -->|"uses"| Kernel
    Context -->|"optimizes render graph"| Filter
    Context -->|"compiles/reuses pipeline states"| Kernel
    Context -->|"encode commands"| Metal
    Context -->|"coordinate MPS kernels"| MPS
    Metal -->|"executes on GPU"| Metal
    Metal -->|"returns textures"| Context
    Context -->|"outputs final texture"| UIComp
    Utilities -->|"generates code at build time"| Context
    Examples -->|"use public API"| SwiftAPI
    Tests -->|"validate core functionality"| Context
    Dist -->|"provides distribution configs"| SwiftAPI

    %% Click Events
    click SwiftAPI "https://github.com/metalpetal/metalpetal/tree/master/Sources/MetalPetal"
    click ObjCAPI "https://github.com/metalpetal/metalpetal/tree/master/Sources/MetalPetalObjectiveC"
    click Context "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/MTIContext.h"
    click Image "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/MTIImage.h"
    click Filter "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/Filters/MTIFilter.h"
    click Kernel "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/Kernels/MTIKernel.h"
    click SceneKit "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/SceneKit/MTISCNSceneRenderer.h"
    click SpriteKit "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/SpriteKit/MTISKSceneRenderer.h"
    click CoreImageExt "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/MTICoreImageExtension.swift"
    click UIComp "https://github.com/metalpetal/metalpetal/blob/master/Frameworks/MetalPetal/UI/MTIImageView.h"
    click Utilities "https://github.com/metalpetal/metalpetal/tree/master/Utilities/Sources/BoilerplateGenerator"
    click Examples "https://github.com/metalpetal/metalpetal/tree/master/MetalPetalExamples/Shared"
    click Tests "https://github.com/metalpetal/metalpetal/tree/master/Tests/MetalPetalTests"
    click Dist "https://github.com/metalpetal/metalpetal/tree/master/Podfile"

    %% Styles
    classDef api fill:#b2f2bb,stroke:#2f662f
    classDef core fill:#aedcff,stroke:#1f4f75
    classDef runtime fill:#ffd8a8,stroke:#995c00
    classDef external fill:#ffcccb,stroke:#a30000
    classDef tools fill:#e0e0e0,stroke:#888
```
