How harley-xk/maliang works
Project Type and Purpose
• The README shows that MaLiang is a painting framework based on Metal that enables drawing, handwriting, and special effects (like texture rotation, glowing brushes, and force/3D Touch support) in iOS. The project also supplies a sample (“Example”) Xcode project demonstrating its usage.
• It is provided as a CocoaPod (and also Carthage-compatible) and forms a core library for rendering strokes and chartlet elements on a canvas.
File Structure
• There are two major areas:
– The “Example” directory contains an Xcode project that demonstrates usage of MaLiang. This project includes view controllers, storyboards, and various UI components.
– The “MaLiang” directory (and its internal structure) houses the core classes and modules for the library. Within this directory you see:
• “Classes” which is further subdivided into modules such as Brush, Canvas, Data & Documents, Elements, Math & Utils, and MetalBase.
• The modular structure hints that the code is organized by functionality:
▸ The Brush module (with files like Brush.swift, ChartletBrush.swift, Eraser.swift etc.) is responsible for managing different brush types.
▸ The Canvas module (with Canvas.swift, ActionObserver.swift, ScrollableCanvas.swift, etc.) represents the drawable area handling drawing and rendering logic.
▸ Data & Documents, Elements, and Math & Utils provide support for saving/restoring, organizing drawn elements, and computational geometry (Bezier curves and gesture recognition).
▸ The MetalBase module indicates that the framework uses Metal for rendering. It contains classes like MetalView, Renderer, and shader files.
• The presence of configuration files (Podspec, .podspecs.json files in Pods) and external dependencies (Pods for SnapKit, Comet, Chrysan, Zip) shows integration with third-party libraries.
Main Components
• Library Core Components:
• Brush: Contains various brush types and related properties (opacity, pointSize, force sensitivity, etc.). It manages texture registration and usage.
• Elements: Represents drawing elements such as strokes, chartlets, line strips, etc.
• Data & Documents: Responsible for capturing the current state (CanvasData) and enabling Undo, Redo, saving, and restoring (DataExporter, DataImporter).
• Math & Utils: Provides computational routines (Bezier curve creation, gesture recognition, etc.) and general utility support.
• MetalBase: Acts as the bridge to Apple’s Metal API, hosting core rendering functionality (Renderer, MetalView, shader code, texture management).
• Sample Application Components (from the Example folder):
• The Example project’s view controllers (like RootViewController, File Samples view controllers, Painting Samples, Scroll Samples) that demonstrate how to integrate and use the library.
• Storyboard and XIB files that bind to the Canvas and other UI components.
• External Dependencies and Pods:
• Components such as SnapKit (for layout constraints), Comet (possibly for utility extensions), Chrysan, and Zip that may play auxiliary roles in UI and data handling.
Relationships and Interactions
• The sample application (client) instantiates a Canvas instance (a subclass of MTKView via MetalView) and configures it.
• As strokes are drawn, the Canvas collaborates with the MetalBase module to render using Metal’s GPU acceleration.
• Helper modules in Math & Utils process gesture input, generate Bezier paths, and adjust brush properties (such as handling force or 3D Touch).
• The Data & Documents module observes changes via CanvasData and enables Undo/Redo as well as exporting snapshots or vector documents.
• External dependencies may be used by the sample project or even the library (e.g., SnapKit for layout, Zip for archiving saved drawing data).
Architectural Patterns and Design Principles
• The design uses a modular architecture where each logical component (Canvas, Brush, Data, Elements, Math/Utils, MetalBase) is separated into its own subdirectory or module. This follows separation of concerns.
• The dependency on Metal for rendering encapsulated inside MetalBase is a key pattern, making the higher-level components (Canvas, Brush) independent of low-level GPU management.
• The use of observer patterns (CanvasData, DataObserver) facilitates undo/redo and real-time data tracking.
• The inclusion of third-party libraries via CocoaPods emphasizes reusability and integration with existing iOS layout and utility frameworks.
Extra Detail
• A separate block for the External Dependencies used in the Example project (showing pods like SnapKit, Comet, etc.).
• For the sample app, mention how it uses view controllers and storyboards to hook up the Canvas.