HelixToolkit.Nex 1.2.0

# HelixToolkit.Nex

HelixToolkit.Nex is a powerful 3D graphics engine implemented in C# that leverages the Vulkan API. It is designed to provide high-performance rendering capabilities, supporting advanced features such as Reverse-Z projection matrices, Forward Plus light culling, and GPU-based frustum and instance culling. The engine is built on its own custom Entity Component System (ECS) architecture (`HelixToolkit.Nex.ECS`), and it manages rendering through a Render Graph for optimal execution order.

## Overview

HelixToolkit.Nex is part of the HelixToolkit suite, focusing on providing a robust and efficient 3D rendering engine. Key concepts include:
- **Reverse-Z Projection**: Enhances depth precision by reversing the depth buffer range.
- **Forward Plus Lighting**: Efficiently manages a large number of lights using a tiled light culling approach.
- **GPU-Based Culling**: Offloads frustum and instance culling to the GPU for improved performance.
- **Entity Component System (ECS)**: Uses the custom `HelixToolkit.Nex.ECS` framework for flexible and efficient entity management.
- **Render Graph**: Organizes rendering tasks into a directed acyclic graph to optimize execution order.

## Key Types

| Type                   | Description                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `DebugLogger`          | Logger that writes messages to the debug output window when a debugger is attached. |
| `DebugLoggerFactory`   | Factory for creating `DebugLogger` instances.                                       |
| `IServiceScopeFactory` | Interface for creating service scopes.                                              |
| `ServiceCollection`    | Implementation of `IServiceCollection` for managing service descriptors.            |
| `ServiceDescriptor`    | Describes a service with its type, implementation, and lifetime.                    |
| `ServiceLifetime`      | Enum defining service lifetimes: Singleton, Scoped, Transient.                      |
| `ServiceProvider`      | Provides services and manages their lifetimes.                                      |
| `Disposer`             | Utility for disposing `IDisposable` objects and setting references to null.         |
| `DoubleKeyDictionary`  | Dictionary supporting two keys for each value.                                      |
| `EventBus`             | Thread-safe event bus for publishing and subscribing to events.                     |
| `FastList`             | List implementation with direct access to the underlying array.                     |
| `Handle`               | Type-safe handle with generational versioning to prevent the ABA problem.           |
| `HxDebug`              | Provides debugging and assertion utilities.                                         |
| `IdHelper`             | Manages unique ID generation and recycling.                                         |
| `Initializable`        | Interface and base class for objects requiring initialization and cleanup.          |
| `Limits`               | Defines various engine limits, such as max entity and instance counts.              |
| `LogManager`           | Manages logger creation and customization.                                          |
| `NativeHelper`         | Helper methods for working with native memory and types.                            |
| `NumericHelpers`       | Provides parsing methods for numeric types from character spans.                    |
| `ObjectPool`           | Manages reusable objects with a maximum capacity.                                   |
| `Pool`                 | Generic object pool with generational handles.                                      |
| `ResultCode`           | Enum for result codes in graphics operations.                                       |
| `RingBuffer`           | Lock-free single-producer/single-consumer ring buffer.                              |
| `Scope`                | Disposable scope that executes an action on disposal.                               |
| `ShaderStage`          | Enum defining shader pipeline stages.                                               |
| `SystemInfo`           | Provides system and runtime information.                                            |
| `Time`                 | Provides methods for time measurement.                                              |
| `TokenizerHelper`      | Utility for tokenizing strings based on separators and quotes.                      |
| `ITracer`              | Interface for high-performance tracing.                                             |
| `NullTracer`           | Tracer that performs no operations, used when tracing is disabled.                  |
| `PerformanceTracer`    | High-performance tracer with object pooling and thread-safe operations.             |
| `TraceEntry`           | Represents a single trace entry.                                                    |
| `TraceEntryType`       | Enum defining types of trace entries.                                               |
| `TraceEventArgs`       | Event arguments for trace events.                                                   |
| `TraceScope`           | Represents a trace scope, automatically ends when disposed.                         |
| `TraceStatistics`      | Provides statistics for trace entries.                                              |
| `TracerConfiguration`  | Configuration settings for tracer instances.                                        |
| `TracerFactory`        | Factory for creating and managing tracer instances.                                 |

## Updated Limits

The `Limits` class has been updated to include new constants for managing light culling:

- `MaxLightsPerTileLimit`: The maximum number of lights per tile, constrained to 255 due to byte storage.
- `MaxRangeLightCount`: The maximum number of range lights considered for culling, limited to 65535 due to ushort storage.

## Usage Examples

### Logging with DebugLogger

```csharp
var loggerFactory = new DebugLoggerFactory();
var logger = loggerFactory.CreateLogger("ExampleLogger");

if (logger.IsEnabled(LogLevel.Information))
{
    logger.Log(LogLevel.Information, new EventId(1, "ExampleEvent"), "This is a log message.", null, (s, e) => s);
}

Dependency Injection

var services = new ServiceCollection();
services.AddSingleton<IMyService, MyServiceImplementation>();
var serviceProvider = services.BuildServiceProvider();

var myService = serviceProvider.GetRequiredService<IMyService>();

Event Bus

var eventBus = new EventBus();
eventBus.Subscribe<MyEvent>(e => Console.WriteLine("Event received!"));

// Publish synchronously
eventBus.Publish(new MyEvent());

// Publish asynchronously
eventBus.PublishAsync(new MyEvent());

// Process async events
eventBus.ProcessEvents();

Tracing

TracerFactory.Enable();
var tracer = TracerFactory.GetTracer("MyTracer");

using (tracer.BeginScope("MyOperation"))
{
    // Perform operation
}

tracer.TraceEvent("OperationCompleted", 1.0);

Ending a Trace Scope

var tracer = TracerFactory.GetTracer("MyTracer");
long startTicks = Stopwatch.GetTimestamp();
// Perform operation
long endTicks = Stopwatch.GetTimestamp();
tracer.EndScope("MyOperation", "Category", startTicks, endTicks, Environment.CurrentManagedThreadId);

Temporarily Disabling Assertions

using (HxDebug.TemporarilyDisableAsserts())
{
    // Code that should not trigger assertions
}

Architecture Notes

• Entity Component System (ECS): HelixToolkit.Nex uses its own custom HelixToolkit.Nex.ECS framework for efficient entity management, allowing for a flexible and scalable component-based architecture.
• Render Graph: The engine employs a Render Graph to manage the execution order of rendering tasks, ensuring optimal performance and resource utilization.
• Tracing: High-performance tracing is supported through the PerformanceTracer class, which provides detailed insights into application performance with minimal overhead.
• Dependency Injection: The engine includes a lightweight dependency injection framework, allowing for easy management of service lifetimes and dependencies.

HelixToolkit.Nex is designed to be modular and extensible, making it suitable for a wide range of 3D graphics applications.