How metalpetal/metalpetal works
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)