HelixToolkit.Nex.Graphics 1.2.0

# HelixToolkit.Nex.Graphics

HelixToolkit.Nex.Graphics is a comprehensive 3D graphics engine implemented in C# that leverages the Vulkan API. It provides a robust framework for creating and managing GPU resources, recording and executing command buffers, and performing advanced rendering operations. The package is designed to integrate seamlessly with the HelixToolkit.Nex engine, offering high-performance graphics capabilities for real-time applications.

## Overview

HelixToolkit.Nex.Graphics is a core component of the HelixToolkit.Nex engine, responsible for managing GPU resources and executing rendering operations. It supports advanced graphics features such as asynchronous GPU uploads, command buffer management, and shader module creation. The package is built around a flexible architecture that includes:

- **Reverse-Z Projection**: Utilizes reverse-Z for improved depth precision.
- **Forward Plus Light Culling**: Efficiently manages lighting calculations.
- **GPU-based Culling**: Performs frustum and instance culling on the GPU.
- **Entity Component System (ECS)**: Uses the custom `HelixToolkit.Nex.ECS` framework for efficient entity management.
- **Render Graph**: Manages the execution order of render nodes.

## Key Types

| Type                   | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| `IAsyncUploadHandle`   | Interface for asynchronous GPU upload operations.                          |
| `AsyncUploadHandle`    | Represents the result of an asynchronous GPU upload operation.             |
| `BufferDesc`           | Describes the properties required to create a GPU buffer.                  |
| `ICommandBuffer`       | Interface for recording GPU commands in a rendering pipeline.              |
| `ComputePipelineDesc`  | Describes the configuration for creating a compute pipeline.               |
| `IContext`             | Interface for creating and managing GPU resources.                         |
| `BufferUsageBits`      | Enum describing buffer usage flags.                                        |
| `TextureDesc`          | Describes the properties required to create a GPU texture.                 |
| `RenderPipelineDesc`   | Represents the configuration for a render pipeline.                        |
| `ShaderModuleDesc`     | Describes the properties required to create a shader module.               |
| `VertexInput`          | Describes the complete vertex input configuration for a graphics pipeline. |
| `TextureResource`      | Represents a GPU texture resource.                                         |
| `Dependencies`         | Manages dependencies for command buffer submissions.                       |
| `DependencyScope`      | Provides a scoped management for dependencies.                             |
| `ElementBuffer<T>`     | Represents a buffer for storing elements of type `T`.                      |
| `RingElementBuffer<T>` | Manages a ring buffer for dynamic element storage.                         |
| `SamplerStateDesc`     | Describes the configuration for a texture sampler.                         |
| `DepthState`           | Describes depth test configuration, including new `ReadOnlyInvZBias`.      |
| `Format`               | Enum describing texture and buffer formats, including new `A_UN8`.         |
| `PipelineStageFlags`   | Enum for backend-agnostic pipeline stage flags for GPU memory barriers.    |
| `AccessFlags`          | Enum for backend-agnostic memory access flags for GPU memory barriers.     |
| `TextureLayout`        | Enum for backend-agnostic image layouts used by image/texture barriers.    |
| `BarrierDescriptor`    | Describes a fully custom GPU memory barrier.                               |
| `BarrierPreset`        | Enum for predefined buffer barrier configurations.                         |
| `ImageTransition`      | Enum for named image/texture layout transitions.                           |
| `KeyedMutexSyncInfo`   | Struct for keyed mutex synchronization, including new semaphore handles.   |

## Usage Examples

### Creating a Buffer

```csharp
var context = /* obtain IContext instance */;
var bufferDesc = new BufferDesc(BufferUsageBits.Vertex, StorageType.Device, IntPtr.Zero, 1024);
context.CreateBuffer(bufferDesc, out var buffer);

Creating a Render Target 2D Texture

var renderTarget = context.CreateRenderTarget2D(
    Format.RGBA_UN8,
    1920,
    1080,
    numSamples: 4,
    debugName: "MainRenderTarget"
);

Uploading Data Asynchronously

var data = new float[] { /* vertex data */ };
var uploadHandle = context.UploadAsync(buffer.Handle, 0, data, data.Length);
await uploadHandle.WhenCompleted;

Recording Command Buffers

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.BeginRendering(renderPass, framebuffer, dependencies);
commandBuffer.BindRenderPipeline(renderPipeline.Handle);
commandBuffer.Draw(3);
commandBuffer.EndRendering();
context.Submit(commandBuffer);

Transitioning Texture Layouts

var commandBuffer = context.AcquireCommandBuffer();
bool transitionCreated = commandBuffer.ImageBarrier(textureHandle, ImageTransition.ToShaderReadOnly);
if (!transitionCreated)
{
    // Handle error
}

Transitioning Multiple Textures to Shader Read-Only

var commandBuffer = context.AcquireCommandBuffer();
var textures = new TextureHandle[] { texture1.Handle, texture2.Handle };
commandBuffer.TransitionToShaderReadOnly(textures, ShaderStage.FragmentShader);

Creating a Memory Barrier with Presets

var commandBuffer = context.AcquireCommandBuffer();
bool barrierCreated = commandBuffer.Barrier(buffer.Handle, BarrierPreset.ComputeWriteToShaderRW, force: true);
if (!barrierCreated)
{
    // Handle error
}

Creating a Custom Memory Barrier

var commandBuffer = context.AcquireCommandBuffer();
var descriptor = new BarrierDescriptor(
    PipelineStageFlags.ComputeShader,
    PipelineStageFlags.FragmentShader,
    AccessFlags.ShaderWrite,
    AccessFlags.ShaderRead
);
bool barrierCreated = commandBuffer.Barrier(buffer.Handle, descriptor, force: true);
if (!barrierCreated)
{
    // Handle error
}

Using RingElementBuffer with State-Based Write

var ringBuffer = new RingElementBuffer<float>(context, initialCapacity: 1024, isDynamic: true);
var commandBuffer = context.AcquireCommandBuffer();
var state = new { /* state data */ };
ringBuffer.WriteDynamic(100, state, (ctx, s) => {
    // Write data using ctx and state s
});

Marking a Buffer as Dirty

context.MarkDirty(buffer.Handle);

Committing In-Place CPU Writes

context.MarkHostWrite(buffer.Handle, offset: 0, size: 256);

Waiting for Command Buffer Completion

var submitHandle = context.Submit(commandBuffer);
context.Wait(submitHandle, reset: true);

Monitoring Draw and Dispatch Calls

var commandBuffer = context.AcquireCommandBuffer();
// Record commands...
uint drawCalls = commandBuffer.DrawCallCount;
uint dispatchCalls = commandBuffer.DispatchCallCount;

Using Debug Labels and Checkpoints

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.PushDebugGroupLabel("RenderPass", new Color4(0.5f, 0.5f, 0.5f, 1.0f));
commandBuffer.SetCheckpointMarker("MidFrame");
commandBuffer.PopDebugGroupLabel();

Clearing Depth Stencil Image

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.ClearDepthStencilImage(textureHandle, depth: 1.0f, stencil: 0);

Managing Dependencies with Scoped Operations

var dependencies = new Dependencies();
using (dependencies.PushBufferScoped(bufferHandle))
{
    // Perform operations that require the buffer
}

Enabling/Disabling Color Write for Render Targets

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.SetColorWriteEnabled(c0: true, c1: false, c2: true, c3: false);

Setting Cull Mode

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.SetCullMode(CullMode.Back);

Copying Texture to Buffer

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.CopyTextureToBuffer(
    src: textureHandle,
    dst: bufferHandle,
    bufferOffset: 0,
    srcOffset: new Offset3D(0, 0, 0),
    extent: new Dimensions(1920, 1080, 1),
    layers: new TextureLayers(0, 1)
);

Architecture Notes

• Design Patterns: The package uses an Entity Component System (ECS) for efficient entity management and a Render Graph to manage render node execution order.
• Dependencies: HelixToolkit.Nex.Graphics depends on other HelixToolkit.Nex packages for math operations and ECS management.
• Matrix Conventions: C# matrices are row-major, while GLSL matrices are column-major, which is important for shader interoperability.
• Reverse-Z: The engine uses reverse-Z for projection matrices to improve depth buffer precision.

HelixToolkit.Nex.Graphics is designed to provide a flexible and high-performance graphics framework for C# developers, enabling the creation of sophisticated 3D applications with ease.