HelixToolkit.Nex.Graphics.Vulkan 1.2.0

# HelixToolkit.Nex.Graphics.Vulkan

HelixToolkit.Nex.Graphics.Vulkan is a C# package that provides a robust and efficient interface for 3D graphics rendering using the Vulkan API. It is part of the HelixToolkit-Nex engine, designed to leverage Vulkan's capabilities for high-performance graphics applications.

## Overview

HelixToolkit.Nex.Graphics.Vulkan is a critical component of the HelixToolkit-Nex engine, responsible for managing Vulkan-based rendering operations. It provides abstractions for command buffers, pipelines, and other Vulkan constructs, facilitating the creation and management of complex 3D scenes. The package integrates with the engine's ECS architecture and render graph system, ensuring efficient rendering and resource management.

Key features include:
- Reverse-Z projection matrices for improved depth precision.
- Forward Plus light culling for efficient lighting calculations.
- GPU-based frustum and instance culling for optimized rendering.
- Support for Vulkan's advanced features like mesh shaders and dynamic rendering.
- Enhanced support for Vulkan features such as `shaderSampledImageArrayDynamicIndexing`, `shaderInt64`, `shaderInt16`, `extendedDynamicState`, and `colorWriteEnable`.
- Support for Linux configurations with `LinuxDebug` and `LinuxRelease`.
- New support for Linux external-memory-fd extensions for interop with Avalonia/EGL.

## Key Types

| Type                          | Description                                                                 |
|-------------------------------|-----------------------------------------------------------------------------|
| `CommandBuffer`               | Manages Vulkan command buffers for recording GPU commands.                  |
| `VulkanContext`               | Represents the Vulkan graphics context, managing device and resource setup. |
| `VulkanImage`                 | Encapsulates Vulkan image resources, including views and memory management. |
| `VulkanImmediateCommands`     | Handles immediate command buffer execution and synchronization.             |
| `VulkanPipelineBuilder`       | Facilitates the creation of Vulkan graphics pipelines.                      |
| `VulkanStagingDevice`         | Manages staging buffers for efficient data transfer to the GPU.             |
| `BarrierPlanner`              | Provides GPU-free helpers for deciding what barriers to emit.               |
| `Bindings` (enum)             | Defines descriptor set binding points for Vulkan pipelines.                 |
| `DeviceQueues`                | Manages Vulkan device queues for graphics, compute, and transfer operations.|

## Usage Examples

### Creating a Vulkan Context

```csharp
var config = new VulkanContextConfig
{
    EnableValidation = true,
    EnableVma = true,
    TerminateOnValidationError = false,
    PreferredPresentMode = VkPresentModeKHR.FifoRelaxed,
    ForceIntegratedGPU = false,
    MaxStagingBufferSize = 128u * 1024u * 1024u,
    EnableExternalMemoryFd = true // Enable external memory FD for Linux interop
};

var context = VulkanBuilder.Create(config, windowHandle, displayHandle);

Recording Commands

var commandBuffer = context.AcquireCommandBuffer();
commandBuffer.BeginEncoding();
commandBuffer.BeginRendering(renderPass, framebuffer, dependencies);
commandBuffer.BindRenderPipeline(pipelineHandle);
commandBuffer.Draw(vertexCount, instanceCount, firstVertex, baseInstance);
commandBuffer.EndRendering();
commandBuffer.EndEncoding();
context.Submit(commandBuffer, presentTexture, syncInfo);

Creating a Texture

var textureDesc = new TextureDesc
{
    Format = Format.RGBA_UN8,
    Dimensions = new Dimensions(1024, 1024, 1),
    Usage = TextureUsageBits.Sampled | TextureUsageBits.Storage
};

context.CreateTexture(textureDesc, out var textureResource, "MyTexture");

Generating Mipmaps

context.GenerateMipmap(textureResource.Handle, out uint levels);
Console.WriteLine($"Generated {levels} mipmap levels.");

Enabling Color Write

var colorWrites = new bool[] { true, false, true }; // Enable/disable color writes for attachments
commandBuffer.SetColorWriteEnabled(colorWrites);

Setting Color Write for Specific Attachments

commandBuffer.SetColorWriteEnabled(true, false, true, false);

Copying Texture to Buffer

commandBuffer.CopyTextureToBuffer(
    srcTextureHandle,
    dstBufferHandle,
    bufferOffset: 0,
    srcOffset: new Offset3D(0, 0, 0),
    extent: new Dimensions(512, 512, 1),
    layers: new TextureLayers(0, 1, 0, 1)
);

Setting Cull Mode

commandBuffer.SetCullMode(CullMode.Back);

Marking a Buffer as Dirty

context.MarkDirty(bufferHandle);

Marking a Buffer for Host Write

context.MarkHostWrite(bufferHandle, offset: 0, size: 1024);

Using Image Barriers

var transition = ImageTransition.ToShaderReadOnly;
if (commandBuffer.ImageBarrier(textureHandle, transition))
{
    Console.WriteLine("Image barrier applied successfully.");
}

Using Buffer Barriers

commandBuffer.Barrier(bufferHandle, PipelineStageFlags.FragmentShader, AccessFlags.ShaderRead);

Transitioning Textures to Shader Read-Only

commandBuffer.TransitionToShaderReadOnly(textureHandle, ShaderStage.Vertex);

Architecture Notes

Dependencies:

• HelixToolkit.Nex.Maths
• HelixToolkit.Nex.Shaders
• Vortice.Vulkan
• Microsoft.Extensions.Logging