mattercontrol/research/01-core-architecture.md

Core Architecture

Summary

MatterControl is a comprehensive 3D printing workflow application built on .NET 6.0, utilizing a custom 2D/3D rendering engine (agg-sharp) with OpenGL acceleration. The architecture follows a modular design with clear separation between UI, printing infrastructure, slicing, and data persistence layers.

Technical Description

Overall Architecture

MatterControl employs a layered architecture consisting of:

1. Presentation Layer - Custom UI framework (agg-sharp/Gui) with OpenGL rendering
2. Application Layer - Central controller pattern via ApplicationController
3. Domain Layer - Printing, slicing, mesh operations, design tools
4. Infrastructure Layer - SQLite persistence, file I/O, serial communication

Entry Point and Initialization Flow

The application entry point is Program.cs which orchestrates the following initialization sequence:

1. StaticData Resolution - Locates the StaticData directory containing resources (icons, fonts, profiles, translations)
2. Culture Configuration - Sets CultureInfo.InvariantCulture globally for consistent number/date formatting
3. Serial Port Factory - Registers platform-specific serial port implementation (CSharpSerialPortWrapper)
4. Window Provider Selection - Configures either GLFW or WinForms-based window provider
5. Single Instance Handling - Uses LocalService to ensure only one instance runs (production builds)
6. Configuration Loading - Loads settings from appsettings.json and user profile MatterControl.json
7. Database Initialization - Initializes SQLite datastore via Datastore.Instance.Initialize()
8. DPI Awareness - Configures per-monitor DPI awareness on Windows
9. Root Window Creation - Creates RootSystemWindow and displays it

Design Rationale

Custom Rendering Engine (agg-sharp): Rather than using WPF or WinForms controls directly, MatterControl uses a custom rendering abstraction. This provides:

• Cross-platform consistency (same rendering on Windows, Mac, Linux)
• Direct control over 3D viewport rendering with OpenGL
• Pixel-perfect UI scaling with GuiWidget.DeviceScale
• Unified input handling across platforms

Single ApplicationController Instance: The singleton ApplicationController.Instance serves as the central coordination point, managing:

• Active workspaces and printers
• Theme configuration
• Library and content providers
• Plugin registration points
• Application lifecycle events

Workspace-Based Model: The application uses PartWorkspace objects to represent open "tabs" which can be either:

• Design workspaces (standalone 3D scenes)
• Printer workspaces (associated with a specific printer)

This allows multiple concurrent editing sessions while supporting multiple connected printers.

Module Organization

Project	Purpose
MatterControl	Main executable, entry point, Windows-specific code
MatterControlLib	Core application logic, UI, all major features
MatterControl.Printing	GCode processing, printer communication abstractions
MatterControl.OpenGL	OpenGL rendering utilities
MatterControl.MeshOperations	Property grid and mesh editing interfaces
MatterControl.SLA	SLA/resin printer support (Photon format)
MatterControl.Winforms	WinForms window provider implementation
MatterControl.Common	Shared utilities and interfaces
Community.CsharpSqlite	SQLite database implementation

Key External Dependencies

• agg-sharp: Custom 2D graphics, UI widgets, vector math, polygon mesh operations
• MatterSlice: Integrated slicing engine
• Newtonsoft.Json: JSON serialization
• Markdig: Markdown rendering
• PDFsharpNetStandard2: PDF generation
• Lucene.Net: Full-text search indexing
• Zeroconf: Network printer discovery

Configuration System

Configuration is loaded from multiple sources with increasing priority:

1. Built-in defaults
2. appsettings.json (application-level)
3. ~/MatterControl.json (user-level)
4. Command-line arguments

The IConfiguration interface binds to:

• Agg:ProviderTypes - Window/graphics providers
• Agg:GraphicsMode - OpenGL configuration
• MatterControl:Slicer:Debug - In-process slicing for debugging
• MatterControl:Application:EnableNetworkTraffic - Network features toggle

Reference

Entry Point

Class/Method	Location	Description
Program.Main()	Program.cs:83	Application entry point
MainOutputDirectoryAttribute	Program.cs:326	Assembly attribute for build path resolution

Core Classes

Class	Location	Description
ApplicationController	MatterControlLib/ApplicationView/ApplicationController.cs	Central singleton managing application state
RootSystemWindow	MatterControlLib/RootSystemWindow.cs	Main application window
MatterControlApplication	MatterControlLib/MatterControlApplication.cs	Static configuration (MCWS base URI)
AppContext	MatterControlLib/ApplicationView/AppContext.cs	Global context (theme, platform features)

Key Interfaces

Interface	Purpose
INativePlatformFeatures	Platform-specific functionality abstraction
ISystemWindowProvider	Window creation and management
IStaticData	Static resource access

Important Events

Event	Publisher	Description
WorkspacesChanged	ApplicationController	Fired when tabs are added/removed
ApplicationError	ApplicationController	Error logging hook
ApplicationEvent	ApplicationController	General event logging
AnyPrintStarted/Canceled/Complete	ApplicationController	Print lifecycle events

Initialization Order

Program.Main()
├── StaticData.OverrideRootPath()
├── CultureInfo configuration
├── FrostedSerialPortFactory setup
├── AggContext.Config.ProviderTypes
├── LocalService.TryStartServer()
├── IConfiguration loading
├── Datastore.Instance.Initialize()
├── DPI awareness setup
├── RootSystemWindow.GetStartupBounds()
├── Application.LoadRootWindow()
├── ApplicationController.Instance.Theme
└── rootSystemWindow.ShowAsSystemWindow()