269 lines
11 KiB
Markdown
269 lines
11 KiB
Markdown
# Nitload
|
|
|
|
|
|
|
|
Nitload (formerly StgSharp) is an experimental .NET framework for graphics, numerical computing, language analysis, and other performance-sensitive applications. It began as the foundation of a next-generation STG (shoot 'em up) engine, but the current repository focuses on reusable low-level infrastructure rather than a complete, ready-to-use game engine.
|
|
|
|
The managed libraries now use the `Nitload.*` namespace and project prefix. Repository URLs, the logo filename, and some legacy test artifacts still retain the StgSharp name.
|
|
|
|
## Overview
|
|
|
|
The framework combines managed C# APIs with a C native library. Its current work includes OpenGL bindings and rendering infrastructure, generic matrix and vector types, SIMD-accelerated native kernels, custom allocators and collections, regular-language analysis, and state-oriented UI infrastructure. Nitload targets .NET 8; platform and architecture coverage varies by module, with Windows and Linux as the principal native targets.
|
|
|
|
## Core Modules
|
|
|
|
### Nitload.Common
|
|
|
|
The foundational library containing shared functionality:
|
|
|
|
- **High Performance**: Native-memory allocators and processor abstractions
|
|
- **Collections**: Specialized data structures and containers
|
|
- **Threading and Timing**: Synchronization primitives, task helpers, and time providers
|
|
- **Pipeline and State**: Processing pipelines and reusable state-machine primitives
|
|
- **Environment**: Platform abstraction and system integration
|
|
|
|
### Nitload.Mathematics (Numeric)
|
|
|
|
Numerics and linear algebra built on top of the core library:
|
|
|
|
- **Matrix & Vector Types**: High-performance math primitives
|
|
- **Numeric Utilities**: Core numeric helpers and algorithms
|
|
- **SIMD-Friendly Kernels**: Data layouts optimized for hardware acceleration
|
|
|
|
### Nitload.RegularAnalysis
|
|
|
|
Nitload General Regular Analysis (NGRA) infrastructure for recognizing and processing regular languages:
|
|
|
|
- **NFA Direction**: Planned generic ε-NFA sequence execution, followed by weighted automata and NGRA-Tensor research
|
|
- **Parsing Primitives**: Reusable tokenizer and grammar building blocks
|
|
- **Analysis Pipeline**: Structured processing for language-like inputs
|
|
|
|
NGRA is a foundation for higher-level language tooling. It does not replace `Nitload.Script`; the planned Script implementation depends on NGRA and has not started yet. The source currently under `Nitload.Script` is retained from the earlier EXPRESS implementation and is not part of the active core solution.
|
|
|
|
The former Text Regex parser, matcher, and source generator are [archived](src/Nitload.RegularAnalysis/Legacy/README.md)
|
|
and excluded from compilation. Generic AST and token infrastructure remain active.
|
|
|
|
Although Text Regex development is frozen, it produced valuable reusable results: the five-link
|
|
AST model, tree normalization and merging techniques, token/analysis infrastructure, and practical
|
|
experience with COUNT continuations, group boundaries, and rollback. These results remain available
|
|
to inform the new NFA architecture.
|
|
|
|
Future string-regex functionality will use .NET `GeneratedRegex`. NGRA will no longer pursue
|
|
custom `Span<char>` or SIMD optimizations for string matching; its research focus is generalized
|
|
sequence analysis and, later, weighted relation networks.
|
|
|
|
### Nitload.Graphics
|
|
|
|
Managed graphics infrastructure built on Common and Mathematics:
|
|
|
|
- **OpenGL Bindings**: Broad OpenGL 3.3-4.6 API bindings and context management
|
|
- **Rendering Infrastructure**: Render streams, viewports, textures, framebuffers, and geometry
|
|
- **Shader Support**: Shader compilation, program management, and shader-generation utilities
|
|
- **Window Integration**: GLFW-based window and input access
|
|
|
|
### Nitload.Native
|
|
|
|
Native library integration:
|
|
|
|
- **GLFW Integration**: Native loading and interoperation used by the graphics layer
|
|
- **SIMD Operations**: Hardware-accelerated vector operations
|
|
- **Matrix Kernels**: Optimized matrix computation routines
|
|
- **Platform Runtime**: Native thread and platform support for Windows and Linux
|
|
|
|
### Nitload.TerminalDialogue
|
|
|
|
Terminal-based user interface application and components:
|
|
|
|
- **Interactive Terminal**: Command-line UI components
|
|
- **Dialogue System**: User interaction and input handling
|
|
- **Terminal Graphics**: Text-based UI rendering
|
|
|
|
> Note: `Nitload.Script` is planned as a consumer of NGRA and has not started yet. Its existing EXPRESS sources belong to the earlier implementation. `Nitload.Model` is currently an empty placeholder while its design is being reconsidered.
|
|
|
|
## Key Features
|
|
|
|
### High-Performance Computing
|
|
|
|
- **Parallel Matrix Operations**: Multi-threaded matrix computations with optimized scheduling
|
|
- **SIMD Acceleration**: Hardware-optimized vector operations
|
|
- **Memory Management**: Arena, slab, and TLSF (Two-Layer Segregated Fit) allocators
|
|
- **Parallel Runtime**: Dedicated scheduling and worker infrastructure for matrix operations
|
|
|
|
#### TLSF Benchmark Snapshot (BenchmarkDotNet)
|
|
|
|
```
|
|
BenchmarkDotNet v0.15.8, Windows 10 (10.0.19045.7548)
|
|
Proxmox VE guest, 30 vCPUs, host CPU reported as Intel Xeon Gold 6242R 3.10GHz
|
|
.NET SDK 10.0.301
|
|
[Host] : .NET 8.0.28 (8.0.28, 8.0.2826.26413), X64 RyuJIT x86-64-v4
|
|
|
|
Toolchain=InProcessEmitToolchain InvocationCount=3 IterationCount=15
|
|
LaunchCount=1 UnrollFactor=1 WarmupCount=6
|
|
```
|
|
|
|
| Method | Mean | Error | StdDev | Ratio | RatioSD |
|
|
|------- |-----:|------:|-------:|------:|--------:|
|
|
| Libc | 129.96 ns | 10.123 ns | 9.469 ns | 1.00 | 0.10 |
|
|
| Tlsf | 81.39 ns | 1.039 ns | 0.971 ns | 0.63 | 0.05 |
|
|
|
|
This benchmark was run inside a Proxmox VE virtual machine configured with 30 vCPUs. BenchmarkDotNet reports those virtual CPUs as 30 logical and 30 physical processors; that is the guest topology rather than the physical topology of the Xeon Gold 6242R host CPU, whose nominal topology is 20 cores and 40 threads.
|
|
|
|
The benchmark reports normalized time per allocation/free operation. Each iteration uses a 512 MB arena and 256 batches of 2,048 allocations, drawing request sizes from 64, 100, 200, 400, 1,024, and 4,096 bytes and freeing them in a deterministic shuffled order. TLSF uses a local coalescing window of four blocks. In this run TLSF used about 63% of the libc baseline time, or approximately 1.60x the throughput. The result describes this fixed small-block workload only; it is not a general-purpose allocator comparison.
|
|
|
|
### Graphics and Rendering
|
|
|
|
- **OpenGL Integration**: Broad OpenGL 3.3-4.6 bindings
|
|
- **Cross-Platform Direction**: Windows and Linux native targets, with feature coverage dependent on platform
|
|
- **Rendering Pipeline**: Flexible and extensible graphics framework
|
|
- **Shader Management**: Dynamic shader compilation and management
|
|
|
|
### Framework Infrastructure
|
|
|
|
- **State Machines**: Reusable state and transition primitives
|
|
- **Processing Pipelines**: Schedulable nodes and typed connections
|
|
- **Window and Input Access**: Low-level GLFW integration
|
|
- **Image and Texture Handling**: Image loading and GPU texture infrastructure
|
|
|
|
### Data Processing
|
|
|
|
- **NGRA**: Regex analysis, intermediate representation, optimization, and source generation
|
|
- **EXPRESS (legacy/inactive)**: The repository retains an earlier experimental EXPRESS parser/compiler under `Nitload.Script`
|
|
- **Script (planned)**: A future language layer intended to build on NGRA; development has not started
|
|
|
|
## Requirements
|
|
|
|
- .NET 8.0 or later
|
|
- Windows 10/11 or Linux
|
|
- x64 or ARM64 architecture
|
|
- OpenGL 3.3+ support
|
|
|
|
## Installation
|
|
|
|
Nitload is currently in development and requires compilation from source. **NuGet packages are not yet available** - you must build the project from source code.
|
|
|
|
### Prerequisites
|
|
|
|
- CMake 3.16 or later
|
|
- Clang and a Ninja-compatible build environment for the supported C targets
|
|
- **Windows (optional)**: Visual Studio may open the provided `.vcxproj` for navigation and editing
|
|
- .NET 8.0 SDK or later
|
|
- Git for source code retrieval
|
|
|
|
### Building from Source
|
|
|
|
1. **Clone the repository**:
|
|
|
|
```bash
|
|
git clone https://github.com/Nitload-NSI/StgSharp.git
|
|
cd StgSharp
|
|
```
|
|
|
|
2. **Build the native library (recommended toolchain)**:
|
|
|
|
```bash
|
|
cmake --preset clang-release -S src/Nitload.Native
|
|
cmake --build cmake_build/clang-release
|
|
```
|
|
|
|
The supplied presets use Clang with Ninja and place native output under the repository's platform-specific `bin` directory. Use `clang-debug` for a debug build.
|
|
|
|
3. **Build the managed projects**:
|
|
|
|
```bash
|
|
dotnet build Nitload.sln
|
|
```
|
|
|
|
Managed library builds copy an existing native binary into their output directory. Build `Nitload.Native` first when native functionality is required. The `StgSharpDebug` executable is an exception: its project enables an incremental CMake build before managed compilation and requires the native DLL for the normal runtime path.
|
|
|
|
### Build Configuration
|
|
|
|
- **Debug**: Full debugging symbols, unoptimized
|
|
- **Release**: Optimized for performance
|
|
|
|
### Notes
|
|
|
|
- CMake is the maintained build path for `Nitload.Native`; the checked-in presets primarily target Clang
|
|
- The Visual Studio C project may be opened with MSVC tooling, but MSVC IntelliSense behavior and MSVC-produced binaries are not maintained or guaranteed
|
|
- Windows and Linux platform implementations exist; actual feature and architecture coverage may differ
|
|
- x86-64 currently has the most complete optimized kernel coverage
|
|
- Some features may not be available on all platforms
|
|
|
|
## Quick Start
|
|
|
|
### Basic Graphics Application
|
|
|
|
```csharp
|
|
|
|
/*To be implemented*/
|
|
|
|
```
|
|
|
|
### Matrix Operations
|
|
|
|
```csharp
|
|
using Nitload.Common.HighPerformance.Memory;
|
|
using Nitload.Mathematics.Numeric;
|
|
|
|
// Matrix storage is allocated explicitly from a native-memory arena.
|
|
using var allocator = new TwoLayerSegregatedFitAllocator(64 * 1024 * 1024);
|
|
|
|
var matrix = Matrix<float>.Create(
|
|
4,
|
|
4,
|
|
MatrixLayout.DenseRectangle,
|
|
allocator);
|
|
|
|
matrix[0, 0] = 1.0f;
|
|
```
|
|
|
|
General matrix arithmetic does not currently provide operator overloads. Because matrix storage and result ownership involve explicit native-memory control, arithmetic operations are exposed through explicit computation APIs as they are implemented.
|
|
|
|
### Memory Management
|
|
|
|
```csharp
|
|
using Nitload.Common.HighPerformance.Memory;
|
|
|
|
// Create a 64 MiB TLSF arena
|
|
using var allocator = new TwoLayerSegregatedFitAllocator(64 * 1024 * 1024);
|
|
|
|
// Allocate memory
|
|
var handle = allocator.Alloc(1024);
|
|
Span<byte> buffer = handle.AsSpan();
|
|
buffer[0] = 42;
|
|
|
|
allocator.Free(handle);
|
|
```
|
|
|
|
|
|
## Documentation
|
|
|
|
### Technical Documentation
|
|
|
|
- [TLSF Allocator](doc/InroductionToTLSF.md) - Arena layout, allocation behavior, and benchmark methodology
|
|
- [Native Library Build](src/Nitload.Native/README.md) - Native build and source-layout notes
|
|
- [Native Library Naming](src/Nitload.Native/naming.md) - Native library file naming conventions
|
|
|
|
## Contributing
|
|
|
|
Nitload is developed by Nitload Space. Contributions are welcome, particularly in:
|
|
|
|
- Performance optimizations
|
|
- Cross-platform compatibility
|
|
- Documentation improvements
|
|
- New feature implementations
|
|
|
|
## License
|
|
|
|
Nitload is licensed under the MIT License. See [LICENSE](LICENSE) for details.
|
|
|
|
## Future Plans
|
|
|
|
- **Vulkan Support**: Planned for version 2.0
|
|
- **Enhanced Cross-Platform**: Improved Linux and mobile support
|
|
- **Performance Optimizations**: Further SIMD and parallel processing improvements
|
|
- **Extended Language Support**: Additional domain-specific languages
|
|
|
|
## Support
|
|
|
|
For questions, issues, or contributions, please refer to the project repository or contact the development team.
|