944 lines
29 KiB
Markdown
944 lines
29 KiB
Markdown
# agg-sharp Submodule Documentation
|
|
|
|
This directory contains comprehensive documentation of the agg-sharp submodule, the custom graphics and UI framework powering MatterControl.
|
|
|
|
## Overview
|
|
|
|
**agg-sharp** (Anti-Grain Geometry for C#) is a comprehensive graphics library providing:
|
|
- 2D software rasterization and vector graphics
|
|
- Custom widget-based UI framework
|
|
- 3D mesh data structures and operations
|
|
- OpenGL rendering integration
|
|
- Font/typography support
|
|
- Mathematical primitives and geometry algorithms
|
|
|
|
**Technology Stack:**
|
|
- .NET 6.0 (C#)
|
|
- OpenGL (via abstraction layer)
|
|
- Software rasterization (AGG port)
|
|
- Multiple font format support (TTF, OTF, WOFF)
|
|
|
|
## Documentation Index
|
|
|
|
| # | Feature | Description |
|
|
|---|---------|-------------|
|
|
| 1 | [Core Graphics (agg)](#1-core-graphics-agg) | 2D vector rendering, image buffers, colors, transforms |
|
|
| 2 | [GUI Widget System](#2-gui-widget-system) | Widget hierarchy, layout, input, theming |
|
|
| 3 | [PolygonMesh](#3-polygonmesh) | 3D mesh structures, CSG, file formats |
|
|
| 4 | [VectorMath](#4-vectormath) | Vectors, matrices, geometric primitives |
|
|
| 5 | [RenderOpenGL](#5-renderopengl) | OpenGL integration, mesh rendering |
|
|
| 6 | [DataConverters](#6-dataconverters) | 2D/3D format conversion, Object3D hierarchy |
|
|
| 7 | [Typography](#7-typography) | Font loading, text shaping, glyph layout |
|
|
| 8 | [CSG Module](#8-csg-module) | Declarative solid geometry |
|
|
| 9 | [Supporting Libraries](#9-supporting-libraries) | Clipper, Triangle, geometry3Sharp, etc. |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
Submodules/agg-sharp/
|
|
├── agg/ # Core 2D graphics (Anti-Grain Geometry)
|
|
├── Gui/ # Widget system and UI framework
|
|
├── PolygonMesh/ # 3D mesh data structures
|
|
├── VectorMath/ # Linear algebra primitives
|
|
├── RenderOpenGl/ # OpenGL rendering integration
|
|
├── DataConverters2D/ # 2D data conversion utilities
|
|
├── DataConverters3D/ # 3D scene graph and file formats
|
|
├── Typography/ # Font loading and text rendering
|
|
├── Csg/ # Constructive Solid Geometry
|
|
├── clipper_library/ # 2D polygon clipping
|
|
├── Tesselate/ # Polygon tessellation
|
|
├── Triangle/ # Delaunay triangulation
|
|
├── geometry3Sharp/ # 3D geometry algorithms
|
|
├── ImageProcessing/ # Image manipulation
|
|
├── Localizations/ # Translation support
|
|
├── QuadTree/ # Spatial indexing
|
|
└── examples/ # Sample applications
|
|
```
|
|
|
|
---
|
|
|
|
# 1. Core Graphics (agg)
|
|
|
|
## Quick Summary
|
|
|
|
The `agg` module is a C# port of Anti-Grain Geometry providing high-quality 2D software rasterization with anti-aliasing, vector path rendering, image compositing, and color management.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Architecture
|
|
|
|
The rendering pipeline follows the classic AGG model:
|
|
|
|
```
|
|
IVertexSource (paths)
|
|
→ ScanlineRasterizer
|
|
→ IScanlineCache
|
|
→ ScanlineRenderer
|
|
→ ImageBuffer (with blenders)
|
|
```
|
|
|
|
### Core Components
|
|
|
|
**Graphics2D** - Main rendering API (`agg/Graphics2D.cs`)
|
|
- Abstract base class for all 2D rendering operations
|
|
- Provides drawing primitives: `Line()`, `Circle()`, `Rectangle()`, `FillRectangle()`
|
|
- Text rendering: `DrawString()` with font support
|
|
- Transform stack: `PushTransform()`, `PopTransform()`, `SetTransform()`
|
|
- Extensible via `ImageGraphics2D` concrete implementation
|
|
|
|
**ImageBuffer** - Pixel storage (`agg/Image/ImageBuffer.cs`)
|
|
- BGRA pixel format (32-bit and 24-bit support)
|
|
- Configurable stride for memory alignment
|
|
- Events: `ImageChanged` for reactive updates
|
|
- Float variant: `ImageBufferFloat` for high-precision
|
|
|
|
**ScanlineRasterizer** - Anti-aliased rasterization (`agg/ScanlineRasterizer.cs`)
|
|
- 24.8 fixed-point subpixel precision
|
|
- Filling rules: Non-zero and Even-odd
|
|
- Gamma correction support
|
|
- Cell-based anti-aliasing via `RasterizerCellsAa`
|
|
|
|
**Vertex Sources** (`agg/VertexSource/`)
|
|
- `VertexStorage` - Path container with MoveTo/LineTo/Curve commands
|
|
- `Ellipse`, `Arc`, `RoundedRect` - Geometric primitives
|
|
- `Stroke` - Converts paths to stroked outlines (configurable joins/caps)
|
|
- `FlattenCurves` - Bezier to line segment conversion
|
|
- `VertexSourceApplyTransform` - Applies affine transforms
|
|
|
|
**Transforms** (`agg/Transform/`)
|
|
- `Affine` - 2x3 affine transformation matrix
|
|
- `Bilinear`, `Perspective` - Advanced transformations
|
|
- Factory methods: `NewTranslation()`, `NewRotation()`, `NewScaling()`
|
|
|
|
**Color System** (`agg/Primitives/Color.cs`)
|
|
- `Color` struct - BGRA 8-bit per channel
|
|
- `ColorF` - Floating-point precision variant
|
|
- Both 0-255 and 0.0-1.0 property accessors
|
|
- Predefined constants: Black, White, Red, etc.
|
|
|
|
**Blenders** (`agg/Image/Blenders/`)
|
|
- `BlenderBGRA` - Standard alpha blending
|
|
- `BlenderPreMultBGRA` - Pre-multiplied alpha
|
|
- `BlenderGammaBGRA` - Gamma-corrected blending
|
|
- Interface: `IRecieveBlenderByte`, `IRecieveBlenderFloat`
|
|
|
|
### Design Choices
|
|
|
|
- **Software rendering**: Provides pixel-perfect cross-platform consistency
|
|
- **Scanline-based**: Cache-friendly horizontal processing
|
|
- **Subpixel precision**: 8 fractional bits for smooth anti-aliasing
|
|
- **Composable transforms**: Matrix multiplication via operator overloading
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `Graphics2D` | agg/Graphics2D.cs | Abstract rendering API |
|
|
| `ImageGraphics2D` | agg/Image/ImageGraphics2D.cs | ImageBuffer renderer |
|
|
| `ImageBuffer` | agg/Image/ImageBuffer.cs | Pixel buffer |
|
|
| `ScanlineRasterizer` | agg/ScanlineRasterizer.cs | AA rasterization |
|
|
| `ScanlineRenderer` | agg/ScanlineRenderer.cs | Scanline to pixels |
|
|
| `Color` | agg/Primitives/Color.cs | BGRA color |
|
|
| `Affine` | agg/Transform/Affine.cs | 2D transformation |
|
|
| `VertexStorage` | agg/VertexSource/VertexStorage.cs | Path container |
|
|
|
|
### Key Interfaces
|
|
|
|
| Interface | Purpose |
|
|
|-----------|---------|
|
|
| `IVertexSource` | Path/shape data provider |
|
|
| `IColorType` | Color abstraction |
|
|
| `IScanlineCache` | Scanline coverage data |
|
|
| `IRecieveBlenderByte` | Pixel blending strategy |
|
|
|
|
---
|
|
|
|
# 2. GUI Widget System
|
|
|
|
## Quick Summary
|
|
|
|
The `Gui` module provides a complete widget-based UI framework with hierarchical layouts, input handling, theming, and platform abstraction. All UI elements inherit from `GuiWidget`.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Widget Hierarchy
|
|
|
|
```
|
|
GuiWidget (base)
|
|
├── Properties: BackgroundColor, Border, Padding, Margin
|
|
├── Layout: HAnchor, VAnchor, LayoutEngine
|
|
├── Children: AscendableSafeList<GuiWidget>
|
|
├── Input: Mouse/Keyboard events, Focus management
|
|
└── Rendering: Invalidation, double-buffering
|
|
```
|
|
|
|
### Layout System
|
|
|
|
**Anchoring** (`GuiWidget.cs`)
|
|
- `HAnchor`: Left, Center, Right, Fit, Stretch, MaxFitOrStretch
|
|
- `VAnchor`: Bottom, Center, Top, Fit, Stretch, MaxFitOrStretch
|
|
- Controls automatic sizing and positioning relative to parent
|
|
|
|
**Layout Engines** (`Gui/LayoutEngines/`)
|
|
- `LayoutEngineSimpleAlign` - Basic anchor-based alignment
|
|
- `LayoutEngineFlow` - Sequential flow layout (horizontal/vertical)
|
|
- `FlowLayoutWidget` - Convenience container using flow layout
|
|
|
|
**FlowDirection Enum:**
|
|
- `LeftToRight`, `RightToLeft`, `TopToBottom`, `BottomToTop`
|
|
|
|
### Input Handling
|
|
|
|
**Mouse Events:**
|
|
- `MouseDown`, `MouseUp`, `Click` - Button interactions
|
|
- `MouseMove`, `MouseEnter`, `MouseLeave` - Position tracking
|
|
- `MouseWheel` - Scroll support
|
|
- `GestureFling` - Touch gestures
|
|
|
|
**Keyboard Events:**
|
|
- `KeyDown`, `KeyUp` - Key state changes
|
|
- `KeyPressed` - Character input
|
|
|
|
**Focus Management:**
|
|
- `Focus()`, `Unfocus()` - Manual control
|
|
- `Focused`, `ContainsFocus` - State queries
|
|
- `TabStop`, `TabIndex` - Tab navigation
|
|
|
|
### Platform Abstraction
|
|
|
|
**SystemWindow** (`Gui/SystemWindow/SystemWindow.cs`)
|
|
- Top-level window container
|
|
- Properties: `Title`, `IsModal`, `UseOpenGL`
|
|
- Manages tooltip display via `ToolTipManager`
|
|
|
|
**IPlatformWindow** Interface:
|
|
- `Caption`, `DesktopPosition`, `MinimumSize`
|
|
- `BringToFront()`, `Activate()`, `Close()`
|
|
- `SetCursor()`, `NewGraphics2D()`
|
|
|
|
**ISystemWindowProvider** Interface:
|
|
- Abstracts window creation across platforms
|
|
- Implementations: `SingleWindowProvider`, platform-specific providers
|
|
|
|
### Theming
|
|
|
|
**ThemeConfig** (`Gui/Theme/ThemeConfig.cs`)
|
|
- Color palette: `BackgroundColor`, `TextColor`, `PrimaryAccentColor`
|
|
- Typography: `DefaultFontSize`, `FontSize7-14`
|
|
- Button styling: `ButtonHeight`, `ButtonRadius`, `ButtonBackgroundColor`
|
|
- State colors: `ThreeStateColor` (Focused, Hovered, Inactive)
|
|
|
|
**ThemeConfig Methods:**
|
|
- `MakeRoundedButton()` - Apply rounded style
|
|
- `ApplyBottomBorder()` - Add border decoration
|
|
- `CreateHeading()`, `CreateDialogButton()` - Themed widget factories
|
|
|
|
### Animation & Threading
|
|
|
|
**Animation** (`Gui/Animation.cs`)
|
|
- `DrawTarget`, `FramesPerSecond`, `SecondsPerUpdate`
|
|
- `Start()`, `Stop()` - Animation lifecycle
|
|
- `Animation.Run()` - Static helper for timed animations
|
|
|
|
**UiThread** (`Gui/UiThread.cs`)
|
|
- `RunOnUiThread()`, `RunOnIdle()` - Deferred execution
|
|
- `SetInterval()`, `ClearInterval()` - Repeated actions
|
|
- `ExecuteWhen()` - Condition-based execution
|
|
|
|
### Key Widgets
|
|
|
|
| Widget | Location | Purpose |
|
|
|--------|----------|---------|
|
|
| `Button` | Gui/Button/ | Clickable button |
|
|
| `CheckBox` | Gui/CheckBox/ | Toggle checkbox |
|
|
| `TextEditWidget` | Gui/TextWidgets/ | Text input |
|
|
| `TextWidget` | Gui/TextWidgets/ | Static text display |
|
|
| `Slider` | Gui/Slider/ | Value slider |
|
|
| `Menu`, `MenuItem` | Gui/Menu/ | Dropdown menus |
|
|
| `ScrollableWidget` | Gui/ScrollableWidget/ | Scrolling container |
|
|
| `DropDownList` | Gui/Menu/ | Selection dropdown |
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `GuiWidget` | Gui/GUIWidget.cs | Base widget class |
|
|
| `SystemWindow` | Gui/SystemWindow/SystemWindow.cs | Top-level window |
|
|
| `FlowLayoutWidget` | Gui/FlowLayoutWidget.cs | Flow layout container |
|
|
| `ThemeConfig` | Gui/Theme/ThemeConfig.cs | Theme configuration |
|
|
| `Animation` | Gui/Animation.cs | Animation timing |
|
|
| `UiThread` | Gui/UiThread.cs | UI thread utilities |
|
|
|
|
### Key Events
|
|
|
|
| Event | Source | Description |
|
|
|-------|--------|-------------|
|
|
| `Click` | GuiWidget | Mouse click completed |
|
|
| `MouseDown/Up` | GuiWidget | Button press/release |
|
|
| `KeyDown/Up` | GuiWidget | Key press/release |
|
|
| `FocusChanged` | GuiWidget | Focus state changed |
|
|
| `BoundsChanged` | GuiWidget | Size/position changed |
|
|
| `TextChanged` | GuiWidget | Text property changed |
|
|
|
|
---
|
|
|
|
# 3. PolygonMesh
|
|
|
|
## Quick Summary
|
|
|
|
The `PolygonMesh` module provides 3D mesh data structures, CSG (boolean) operations, spatial acceleration structures, file format support, and ray tracing capabilities.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Mesh Data Structure
|
|
|
|
**Mesh** (`PolygonMesh/Mesh.cs`)
|
|
- `Vertices`: List<Vector3Float> - Vertex positions
|
|
- `Faces`: FaceList - Triangles (3 vertex indices each)
|
|
- `FaceTextures`: Dictionary<int, FaceTextureData> - Per-face textures
|
|
- `FaceBspTree`: BspNode - Spatial acceleration
|
|
- `PropertyBag`: Dictionary<string, object> - Extensible metadata
|
|
|
|
**Key Operations:**
|
|
- `Transform(Matrix4X4)` - Apply transformation
|
|
- `MergeVertices()` - Weld coincident vertices
|
|
- `ReverseFaces()` - Flip normals
|
|
- `Split(Plane)` - Split mesh on plane
|
|
- `GetAxisAlignedBoundingBox()` - Bounds calculation
|
|
- `CalculateNormals()` - Recompute face normals
|
|
|
|
### CSG Operations
|
|
|
|
**CsgOperations** (`PolygonMesh/Csg/CsgOperations.cs`)
|
|
- `Union(meshA, meshB)` - Boolean union
|
|
- `Subtract(meshA, meshB)` - Boolean difference
|
|
- `Intersect()` - Boolean intersection
|
|
|
|
**CsgBySlicing** (`PolygonMesh/Csg/CsgBySlicing.cs`)
|
|
- Polygon-based CSG implementation
|
|
- Uses Clipper library for 2D polygon operations
|
|
- BVH acceleration for spatial queries
|
|
- `SimilarPlaneFinder` for coplanar face grouping
|
|
|
|
**Processing Modes:**
|
|
- `Polygons` - Standard polygon-based CSG
|
|
- `Marching_Cubes` - Experimental implicit surface
|
|
- `Dual_Contouring` - Feature-preserving implicit
|
|
|
|
### Spatial Acceleration
|
|
|
|
**FaceBspTree** (`PolygonMesh/Processors/FaceBspTree.cs`)
|
|
- Binary Space Partition for faces
|
|
- `Create()` - Build from mesh
|
|
- `GetFacesInVisibilityOrder()` - Depth-sorted rendering
|
|
- Used for transparent object rendering
|
|
|
|
**BoundingVolumeHierarchy** (`PolygonMesh/RayTracer/Bvh/`)
|
|
- `BvhBuilderAac` - Axis-aligned clustering
|
|
- `BvhBuilderBottomUp` - Bottom-up construction
|
|
- `BvhBuilderLocallyOrderedClustering` - Morton code ordering
|
|
- O(log n) ray intersection queries
|
|
|
|
### File Format Support
|
|
|
|
| Format | Class | Features |
|
|
|--------|-------|----------|
|
|
| STL | `StlProcessing` | Binary/ASCII, streaming |
|
|
| OBJ | `ObjSupport`, `Obj` | Materials, textures |
|
|
| AMF | `AmfDocument` | Multi-material, compressed |
|
|
| 3MF | `IxMilia.ThreeMf` | Full 3MF spec support |
|
|
|
|
### Ray Tracing
|
|
|
|
**RayTracer** (`PolygonMesh/RayTracer/RayTracer.cs`)
|
|
- Anti-aliasing: None, Low(4), Medium(8), High(16), VeryHigh(32)
|
|
- Buffers: Color, Depth, Normal
|
|
- Features: Diffuse, Highlights, Reflection, Refraction, Shadows
|
|
|
|
**Primitives** (`PolygonMesh/RayTracer/Primitive/Shapes/`)
|
|
- `TriangleShape`, `BoxShape`, `SphereShape`, `CylinderShape`, `PlaneShape`
|
|
- Materials: Solid, Chessboard, Texture
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `Mesh` | PolygonMesh/Mesh.cs | Mesh data structure |
|
|
| `Face` | PolygonMesh/Face.cs | Triangle face |
|
|
| `CsgOperations` | PolygonMesh/Csg/CsgOperations.cs | Boolean ops |
|
|
| `FaceBspTree` | PolygonMesh/Processors/FaceBspTree.cs | BSP tree |
|
|
| `StlProcessing` | PolygonMesh/Processors/StlProcessing.cs | STL I/O |
|
|
|
|
### Mesh Extensions
|
|
|
|
| Method | Purpose |
|
|
|--------|---------|
|
|
| `Copy()` | Deep copy mesh |
|
|
| `GetCoplanarFaces()` | Find faces on same plane |
|
|
| `GetMeshEdges()` | Extract edge topology |
|
|
| `GetNonManifoldEdges()` | Detect topology errors |
|
|
| `IsManifold()` | Validate mesh topology |
|
|
| `RepairTJunctions()` | Fix T-junction artifacts |
|
|
|
|
---
|
|
|
|
# 4. VectorMath
|
|
|
|
## Quick Summary
|
|
|
|
The `VectorMath` module provides double-precision vector types, matrices, geometric primitives (rays, planes, AABBs), quaternions, and mathematical utilities for 3D graphics.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Vector Types
|
|
|
|
**Vector2** (`VectorMath/Vector2.cs`)
|
|
- Components: X, Y (double)
|
|
- Constants: Zero, One, UnitX, UnitY
|
|
- Operations: Dot, Cross (2D scalar), Lerp, Rotate
|
|
- Extensions: Polygon utilities, path analysis
|
|
|
|
**Vector3** (`VectorMath/Vector3.cs`)
|
|
- Components: X, Y, Z (double)
|
|
- Operations: Dot, Cross, Normalize, Lerp
|
|
- Transforms: Position, Normal, Vector transforms with Matrix4X4
|
|
- Float variant: `Vector3Float` for GPU compatibility
|
|
|
|
**Vector4** (`VectorMath/Vector4.cs`)
|
|
- Components: X, Y, Z, W (double)
|
|
- Homogeneous coordinates support
|
|
- Matrix transformation with perspective division
|
|
- Swizzle: `.Xy`, `.Xyz` properties
|
|
|
|
### Matrix Types
|
|
|
|
**Matrix4X4** (`VectorMath/Matrix4x4.cs`)
|
|
- 4x4 double-precision matrix (row-major)
|
|
- Position in Row3 (graphics convention)
|
|
- Factory methods:
|
|
- `CreateTranslation()`, `CreateRotation()`, `CreateScale()`
|
|
- `CreatePerspectiveFieldOfView()`, `CreateOrthographic()`
|
|
- `LookAt()` - Camera view matrix
|
|
- Operations: Mult, Invert, Transpose, GetRotation
|
|
|
|
**Quaternion** (`VectorMath/Quaternion.cs`)
|
|
- Unit quaternion rotation representation
|
|
- Construction: Component, from matrix, from two directions
|
|
- Properties: X, Y, Z, W, Xyz
|
|
|
|
### Geometric Primitives
|
|
|
|
**Ray** (`VectorMath/Ray.cs`)
|
|
- Origin + Direction (normalized)
|
|
- Precomputed: `oneOverDirection`, `sign` array
|
|
- Range: `minDistanceToConsider`, `maxDistanceToConsider`
|
|
- Fast AABB intersection (slab method)
|
|
|
|
**Plane** (`VectorMath/Plane.cs`)
|
|
- Normal + DistanceFromOrigin
|
|
- Construction: From normal+distance, normal+point, three points
|
|
- Methods: `GetDistanceFromPlane()`, `LineHitPlane()`, `RayHitPlane()`
|
|
|
|
**AxisAlignedBoundingBox** (`VectorMath/AxisAlignedBoundingBox.cs`)
|
|
- MinXYZ, MaxXYZ corners
|
|
- Methods: `ExpandToInclude()`, `Intersects()`, `Contains()`
|
|
- Properties: Center, Size, Volume, SurfaceArea
|
|
|
|
**Frustum** (`VectorMath/Frustum.cs`)
|
|
- 6 planes: Left, Right, Top, Bottom, Near, Far
|
|
- View frustum culling support
|
|
|
|
### Math Utilities
|
|
|
|
**MathHelper** (`VectorMath/MathHelper.cs`)
|
|
- Constants: Pi, Tau, E, various Pi fractions
|
|
- Trigonometric helpers
|
|
|
|
**Easing** (`VectorMath/Easing.cs`)
|
|
- Animation curves from Tween.js
|
|
- Types: Linear, Quadratic, Cubic, Elastic, Bounce, etc.
|
|
- Modes: EaseIn, EaseOut, EaseInOut
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `Vector2` | VectorMath/Vector2.cs | 2D vector |
|
|
| `Vector3` | VectorMath/Vector3.cs | 3D vector |
|
|
| `Vector4` | VectorMath/Vector4.cs | 4D/homogeneous |
|
|
| `Matrix4X4` | VectorMath/Matrix4x4.cs | 4x4 transform |
|
|
| `Quaternion` | VectorMath/Quaternion.cs | Rotation quaternion |
|
|
| `Ray` | VectorMath/Ray.cs | Ray primitive |
|
|
| `Plane` | VectorMath/Plane.cs | Plane primitive |
|
|
| `AxisAlignedBoundingBox` | VectorMath/AxisAlignedBoundingBox.cs | AABB |
|
|
|
|
### Coordinate Conventions
|
|
|
|
- Right-handed coordinate system
|
|
- Row-major matrix layout
|
|
- Position in Row3 of Matrix4X4
|
|
- Unit quaternions for rotation
|
|
|
|
---
|
|
|
|
# 5. RenderOpenGL
|
|
|
|
## Quick Summary
|
|
|
|
The `RenderOpenGL` module integrates OpenGL rendering with agg-sharp, providing hardware-accelerated mesh rendering, shader management, and texture handling.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Core Graphics
|
|
|
|
**Graphics2DOpenGL** (`RenderOpenGl/Renderer/Graphics2DOpenGL.cs`)
|
|
- Extends `Graphics2D` for OpenGL context
|
|
- Orthographic projection management
|
|
- Anti-aliased 2D rendering via texture-based alpha
|
|
- Scissor test for clipping
|
|
|
|
### Mesh Rendering Plugins
|
|
|
|
Plugins cache rendering data in mesh `PropertyBag`:
|
|
|
|
**GLMeshTrianglePlugin** (`RenderOpenGl/GLMeshTrianglePlugin.cs`)
|
|
- Groups faces by texture into `SubTriangleMesh` objects
|
|
- Data: positions, normals, UVs, per-vertex colors
|
|
- Invalidation tracking via `mesh.ChangedCount`
|
|
|
|
**GLMeshVertexArrayObjectPlugin** (`RenderOpenGl/GLMeshVertexArrayObjectPlugin.cs`)
|
|
- Modern VAO-based rendering
|
|
- VBO for positions, EBO for indices
|
|
- Uses `GL.DrawElements()`
|
|
|
|
**GLMeshWirePlugin** (`RenderOpenGl/GLMeshWirePlugin.cs`)
|
|
- Wireframe edge rendering
|
|
- Optional angle-based edge filtering
|
|
- Background processing for complex meshes
|
|
|
|
**GLMeshNonManifoldPlugin** (`RenderOpenGl/GLMeshNonManifoldPlugin.cs`)
|
|
- Highlights non-manifold edges
|
|
- Background edge analysis
|
|
|
|
### Texture Management
|
|
|
|
**ImageGlPlugin** (`RenderOpenGl/ImageGlPlugin.cs`)
|
|
- Weak-reference caching by image buffer
|
|
- Power-of-2 texture handling
|
|
- Mipmap generation support
|
|
- Format: RGBA (converted from BGRA)
|
|
|
|
### Rendering Pipeline
|
|
|
|
**GLHelper** (`RenderOpenGl/RenderMeshToGl.cs`)
|
|
- High-level mesh rendering orchestration
|
|
- RenderTypes: Shaded, Wireframe, Outlines, NonManifold, Overhang
|
|
|
|
**SetGlContext():**
|
|
- Viewport, face culling, depth function
|
|
- Lighting setup (2 directional lights)
|
|
- Projection/modelview matrices
|
|
|
|
**Render Types:**
|
|
| Type | Description |
|
|
|------|-------------|
|
|
| Shaded | Textured/lit solid mesh |
|
|
| Wireframe | Edges only |
|
|
| Outlines | Solid + wireframe overlay |
|
|
| NonManifold | Highlight topology errors |
|
|
| Overhang | Overhang analysis coloring |
|
|
|
|
### Lighting
|
|
|
|
**LightingData** (`RenderOpenGl/LightingData.cs`)
|
|
- Two directional lights
|
|
- Ambient, Diffuse, Specular components
|
|
- Per-vertex color material support
|
|
|
|
### 3D Line Rendering
|
|
|
|
**WorldViewExtensions** (`RenderOpenGl/WorldViewExtensions.cs`)
|
|
- `Render3DLine()` - Screen-space width lines
|
|
- `RenderCylinderOutline()`, `RenderRing()`, `RenderAabb()`
|
|
- Frustum clipping before rendering
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `Graphics2DOpenGL` | RenderOpenGl/Renderer/Graphics2DOpenGL.cs | 2D GL rendering |
|
|
| `GLMeshTrianglePlugin` | RenderOpenGl/GLMeshTrianglePlugin.cs | Triangle cache |
|
|
| `ImageGlPlugin` | RenderOpenGl/ImageGlPlugin.cs | Texture management |
|
|
| `GLHelper` | RenderOpenGl/RenderMeshToGl.cs | Render pipeline |
|
|
| `LightingData` | RenderOpenGl/LightingData.cs | Light config |
|
|
|
|
### GL Abstraction
|
|
|
|
| Interface/Class | Purpose |
|
|
|-----------------|---------|
|
|
| `IOpenGL` | OpenGL operation abstraction |
|
|
| `GL` | Thread-safe GL facade |
|
|
| `GL/Enums/` | OpenGL constant definitions |
|
|
|
|
---
|
|
|
|
# 6. DataConverters
|
|
|
|
## Quick Summary
|
|
|
|
The `DataConverters2D` and `DataConverters3D` modules handle format conversion between 2D/3D data types, scene graph management, and file format import/export.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### DataConverters2D
|
|
|
|
**Tessellation** (`DataConverters2D/`)
|
|
- `CachedTesselator` - Caches vertices/indices during tessellation
|
|
- `VertexSourceToTesselator` - Converts IVertexSource to tessellator input
|
|
- Processes vertex commands: MoveTo, LineTo, Close
|
|
|
|
**Polygon Operations** (`DataConverters2D/VertexSourceToClipperPolygons.cs`)
|
|
- `CreatePolygons()` - IVertexSource to Clipper polygons
|
|
- `Offset()` - Polygon expansion/contraction
|
|
- `GetCorrectedWinding()` - Fix winding direction
|
|
|
|
**Image I/O** (`DataConverters2D/ImageIO.cs`)
|
|
- Load/Save: PNG, JPG, GIF (with animation)
|
|
- Uses SixLabors.ImageSharp
|
|
- `ConvertImageToImageBuffer()` - Format conversion
|
|
|
|
### DataConverters3D
|
|
|
|
**Object3D Hierarchy** (`DataConverters3D/Object3D/`)
|
|
|
|
**IObject3D Interface:**
|
|
- `Children` - Hierarchical scene graph
|
|
- `Mesh` - Associated geometry
|
|
- `Matrix` - Local transformation
|
|
- `Color`, `MaterialIndex`, `OutputType`
|
|
- Methods: `Clone()`, `GetAxisAlignedBoundingBox()`, `ToJson()`
|
|
|
|
**Object3D Class:**
|
|
- Concrete IObject3D implementation
|
|
- GUID-based identification
|
|
- Thread-safe rebuild locking
|
|
- JSON serialization support
|
|
|
|
**InteractiveScene:**
|
|
- Selection management
|
|
- `SelectedItem`, `SelectedItemRoot`
|
|
- Scene-level operations
|
|
|
|
**File Format Support:**
|
|
|
|
| Format | Class | Features |
|
|
|--------|-------|----------|
|
|
| AMF | `AmfDocument` | ZIP compression, streaming |
|
|
| OBJ/MTL | `ObjSupport` | Materials, vertices, faces |
|
|
| 3MF | `IxMilia.ThreeMf` | Full 3MF specification |
|
|
|
|
**Conversion Utilities:**
|
|
- `MeshToBVH` - Convert Object3D to ray-traceable BVH
|
|
- `CenterAndHeightMaintainer` - Position preservation during operations
|
|
- `CsgToRayTraceable` - CSG to ray tracer primitives
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `CachedTesselator` | DataConverters2D/ | Tessellation cache |
|
|
| `VertexSourceToClipperPolygons` | DataConverters2D/ | Polygon conversion |
|
|
| `ImageIO` | DataConverters2D/ | Image I/O |
|
|
| `IObject3D` | DataConverters3D/Object3D/ | Scene interface |
|
|
| `Object3D` | DataConverters3D/Object3D/ | Scene implementation |
|
|
| `InteractiveScene` | DataConverters3D/Object3D/ | Selection management |
|
|
| `AmfDocument` | DataConverters3D/ | AMF loader |
|
|
| `ObjSupport` | DataConverters3D/ | OBJ loader |
|
|
|
|
---
|
|
|
|
# 7. Typography
|
|
|
|
## Quick Summary
|
|
|
|
The `Typography` module provides comprehensive font loading, glyph management, and text shaping using OpenType features.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Font Loading
|
|
|
|
**Typeface** (`Typography.OpenFont/Typeface.cs`)
|
|
- Core font representation
|
|
- Properties: Name, UnitsPerEm, Ascender, Descender, LineGap
|
|
- Manages glyph array and all font tables
|
|
|
|
**OpenFontReader** (`Typography.OpenFont/OpenFontReader.cs`)
|
|
- Reads: TTF, OTF, WOFF, WOFF2, TTC
|
|
- `ReadPreview()` - Lightweight metadata
|
|
- `Read()` - Full font parsing
|
|
|
|
### Font Tables
|
|
|
|
**Core Tables:**
|
|
- `Head` - Font header, metrics
|
|
- `HorizontalMetrics` - Advance widths
|
|
- `Cmap` - Character to glyph mapping
|
|
- `OS2` - Font classification
|
|
|
|
**TrueType:**
|
|
- `Glyf` - TrueType outlines
|
|
- `GlyphLocations` - Glyph offsets
|
|
|
|
**CFF (PostScript):**
|
|
- `CFFTable` - Compact Font Format
|
|
- `Type2CharStringParser` - Charstring evaluation
|
|
|
|
**OpenType Layout:**
|
|
- `GSUB` - Glyph Substitution (ligatures, alternates)
|
|
- `GPOS` - Glyph Positioning (kerning, marks)
|
|
- `GDEF` - Glyph Definition
|
|
|
|
### Text Shaping
|
|
|
|
**GlyphLayout** (`Typography.GlyphLayout/GlyphLayout.cs`)
|
|
- Text shaping engine
|
|
- Process: chars → codepoints → glyphs → GSUB → GPOS
|
|
- Output: `UnscaledGlyphPlan` list
|
|
|
|
**GlyphSubstitution** (`Typography.GlyphLayout/GlyphSubstitution.cs`)
|
|
- GSUB feature application
|
|
- Ligatures, composition, alternates
|
|
|
|
**GlyphSetPosition** (`Typography.GlyphLayout/GlyphPosition.cs`)
|
|
- GPOS feature application
|
|
- Kerning, mark positioning
|
|
|
|
### Glyph Representation
|
|
|
|
**Glyph** (`Typography.OpenFont/Glyph.cs`)
|
|
- Index, Bounds, GlyphPoints, AdvanceWidth
|
|
- TTF: Point arrays
|
|
- CFF: Cff1GlyphData
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `Typeface` | Typography.OpenFont/ | Font representation |
|
|
| `OpenFontReader` | Typography.OpenFont/ | Font file parser |
|
|
| `GlyphLayout` | Typography.GlyphLayout/ | Text shaping |
|
|
| `Glyph` | Typography.OpenFont/ | Single glyph |
|
|
|
|
### Font Tables
|
|
|
|
| Table | Purpose |
|
|
|-------|---------|
|
|
| `Head` | Font header |
|
|
| `Cmap` | Character mapping |
|
|
| `GSUB` | Glyph substitution |
|
|
| `GPOS` | Glyph positioning |
|
|
| `Glyf` | TrueType outlines |
|
|
|
|
---
|
|
|
|
# 8. CSG Module
|
|
|
|
## Quick Summary
|
|
|
|
The standalone `Csg` module provides declarative Constructive Solid Geometry with primitives, transformations, and boolean operations that can be converted to polygon meshes.
|
|
|
|
## Technical In-Depth Review
|
|
|
|
### Primitive Classes
|
|
|
|
**Box** (`Csg/Solids/Box.cs`)
|
|
- Rectangular prisms
|
|
- Methods: `BevelEdge()`, `ChamferEdge()`, `BevelAll()`
|
|
|
|
**Sphere** (`Csg/Solids/Sphere.cs`)
|
|
- Defined by radius
|
|
|
|
**Cylinder** (`Csg/Solids/Cylinder.cs`)
|
|
- Dual-radius cones
|
|
- Configurable polygon sides
|
|
|
|
**LinearExtrude** (`Csg/Solids/LinearExtrude.cs`)
|
|
- 2D polygon → 3D solid
|
|
- Optional twist
|
|
|
|
**RotateExtrude** (`Csg/Solids/RotateExtrude.cs`)
|
|
- Revolution of 2D profile
|
|
|
|
### Transformations
|
|
|
|
| Class | Operation |
|
|
|-------|-----------|
|
|
| `Translate` | Vector3 translation |
|
|
| `Rotate` | Euler angle rotation |
|
|
| `Scale` | Per-axis scaling |
|
|
| `Align` | Align face to position |
|
|
| `SetCenter` | Recenter object |
|
|
|
|
### Boolean Operations
|
|
|
|
| Class | Operator | Operation |
|
|
|-------|----------|-----------|
|
|
| `Union` | `+` | Combine objects |
|
|
| `Difference` | `-` | Subtract objects |
|
|
| `Intersection` | - | Common volume |
|
|
|
|
### Conversion
|
|
|
|
**CsgToMesh** (`Csg/Processors/CsgToMesh.cs`)
|
|
- Visitor pattern converter
|
|
- `Convert(CsgObject) → Mesh`
|
|
|
|
**OpenSCadOutput** (`Csg/Processors/OpenSCadOutput.cs`)
|
|
- Generate OpenSCAD scripts
|
|
- `GetScadString(CsgObject) → string`
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
| Class | Location | Description |
|
|
|-------|----------|-------------|
|
|
| `CsgObject` | Csg/CsgObject.cs | Base class |
|
|
| `Box` | Csg/Solids/Box.cs | Box primitive |
|
|
| `Cylinder` | Csg/Solids/Cylinder.cs | Cylinder primitive |
|
|
| `Union` | Csg/Operations/Union.cs | Boolean union |
|
|
| `Difference` | Csg/Operations/Difference.cs | Boolean difference |
|
|
| `CsgToMesh` | Csg/Processors/CsgToMesh.cs | Mesh conversion |
|
|
|
|
---
|
|
|
|
# 9. Supporting Libraries
|
|
|
|
## Quick Summary
|
|
|
|
Several supporting libraries provide specialized functionality for polygon operations, triangulation, and computational geometry.
|
|
|
|
## Module Overview
|
|
|
|
### clipper_library
|
|
|
|
**Purpose:** Robust 2D polygon clipping using the Vatti algorithm.
|
|
|
|
**Key Classes:**
|
|
- `Clipper` - Main clipping engine
|
|
- `ClipperOffset` - Polygon offsetting
|
|
- `PolyTree` - Hierarchical result structure
|
|
|
|
**Operations:** Union, Intersection, Difference, XOR
|
|
|
|
### Tesselate
|
|
|
|
**Purpose:** GLU-style polygon tessellation.
|
|
|
|
**Key Classes:**
|
|
- `Tesselator` - Main tessellation engine
|
|
- Callback interface for triangle output
|
|
|
|
**Features:** Handles complex polygons with holes
|
|
|
|
### Triangle
|
|
|
|
**Purpose:** Constrained Delaunay triangulation via Triangle.NET.
|
|
|
|
**Key Classes:**
|
|
- `Mesh` - Triangulation result
|
|
- `ConstraintMesher` - Constrained triangulation
|
|
- `QualityMesher` - Mesh refinement
|
|
|
|
### geometry3Sharp
|
|
|
|
**Purpose:** Comprehensive 3D geometry library (ported from WildMagic5).
|
|
|
|
**Modules:**
|
|
- `math/` - Vectors, boxes, transforms
|
|
- `mesh/` - DMesh3, mesh operators
|
|
- `curve/` - Bezier, NURBS, polygons
|
|
- `distance/` - Point-to-geometry queries
|
|
- `comp_geom/` - Convex hull, arrangements
|
|
|
|
### ImageProcessing
|
|
|
|
**Purpose:** Image manipulation filters.
|
|
|
|
**Key Classes:**
|
|
- `Blur`, `Dilate`, `Erode`, `Threshold`
|
|
- `InvertLightness`, `Subtract`
|
|
|
|
### Localizations
|
|
|
|
**Purpose:** Multi-language translation support.
|
|
|
|
**Key Classes:**
|
|
- `TranslationMap` - Translation dictionary
|
|
- Extension: `"text".Localize()`
|
|
|
|
### QuadTree
|
|
|
|
**Purpose:** 2D spatial indexing.
|
|
|
|
**Key Classes:**
|
|
- `QuadTree<T>` - Generic quad tree
|
|
- `Branch<T>`, `Leaf<T>` - Tree nodes
|
|
- Object pooling for efficiency
|
|
|
|
## Dependencies
|
|
|
|
```
|
|
PolygonMesh ──┬── VectorMath
|
|
├── clipper_library
|
|
├── geometry3Sharp
|
|
└── Triangle
|
|
|
|
DataConverters3D ──┬── PolygonMesh
|
|
├── DataConverters2D
|
|
└── Csg
|
|
|
|
RenderOpenGl ──┬── Agg
|
|
└── PolygonMesh
|
|
|
|
Gui ──┬── Agg
|
|
├── DataConverters2D
|
|
└── Localizations
|
|
|
|
Agg ──┬── VectorMath
|
|
└── Typography
|
|
```
|
|
|
|
---
|
|
|
|
## Key Namespaces
|
|
|
|
| Namespace | Purpose |
|
|
|-----------|---------|
|
|
| `MatterHackers.Agg` | Core 2D graphics |
|
|
| `MatterHackers.Agg.UI` | Widget system |
|
|
| `MatterHackers.PolygonMesh` | 3D mesh operations |
|
|
| `MatterHackers.VectorMath` | Linear algebra |
|
|
| `MatterHackers.RenderOpenGl` | OpenGL integration |
|
|
| `MatterHackers.DataConverters2D` | 2D conversion |
|
|
| `MatterHackers.DataConverters3D` | 3D scene graph |
|
|
| `Typography.OpenFont` | Font loading |
|
|
| `Typography.GlyphLayout` | Text shaping |
|
|
| `MatterHackers.Csg` | Solid geometry |
|
|
| `ClipperLib` | Polygon clipping |
|
|
| `TriangleNet` | Mesh triangulation |
|
|
| `g3` | geometry3Sharp |
|