Silk.NET Documentation

Silk.NET 3.0 is a major update focused on portability, maintainability, usability, and performance. Key objectives include:

• Framework Integration: Allowing Silk.NET abstractions to integrate with frameworks like WPF, WinForms, MAUI, and Avalonia.
• Portable Windowing: A rewritten windowing system for true write-once-run-everywhere capability.
• Improved Bindings: Moving away from custom binding generation towards more mature alternatives (SilkTouch).
• SIMD-Accelerated Maths: Accelerating the maths library using SIMD hardware intrinsics.
• Redesigned Input: A multi-backend input library designed to be less prone to breaking changes and compatible with multiple environments.

Note on Previews:

• 3.0 Preview 1-3: Highly experimental; not production-ready.
• 3.0 Preview 4: Considered "production-ready"; users are encouraged to start integrating this into their workloads.
• 3.0 Preview 5: Primarily a bugfix release focusing on final breaking changes and platform integrations (MAUI/Avalonia).

Silk.NET APIs (specifically in the Silk.NET.Vulkan package) often use singly linked lists of structures, referred to as 'chains', to pass data. These chains use a void* pointer (PNext) to link to the next item, with nullptr indicating the end.

To handle the risks of pointer manipulation in a managed environment (like Garbage Collection moving objects), Silk.NET provides three methodologies for managing these chains:

1. Managed Chaining (Recommended): Uses a Chain object to manage memory and ensure pointers remain valid. This is the safest and easiest approach.
2. Structure Chaining: Uses fluent extension methods on IChainable structures. This is stack-based and avoids the heap, making it suitable for performance-sensitive code where structures do not leave the stack.
3. Raw Chaining: Direct pointer manipulation. This is the lowest-level approach for maximum optimization in hot paths but requires unsafe code and manual pointer management.

Managed chaining uses the Silk.NET.Vulkan.Chain abstract class and its descendants to handle Vulkan's structure chaining (e.g., pNext chains). These are auto-generated types like Chain<TChain, T1, T2, ...> that support chain lengths from 1 to 16.

Key characteristics:

• Type Constraints: Every item in a chain must implement IChainable and be unmanaged.
• Strict vs. Loose Constraints:
  • Standard methods (like Create) use strict constraints: the head must implement IChainStart, and subsequent items must implement IExtendsChain<TChain> to ensure valid Vulkan structure sequences.
  • *Any overloads (like CreateAny) use loose constraints (IChainable), allowing you to build chains even when the specification doesn't strictly define the required sequence. Use *Any versions only when necessary.
• Memory Management: Each Chain instance holds a pointer to an unmanaged block of memory. You must always dispose of a Chain instance (ideally using a using statement) to prevent memory leaks.

If you have an unmanaged chain (from raw chaining or other sources), you can load it into a managed Chain using Chain.Load<TChain...>().

There are several overloads:

• Chain.Load<TChain...>(unmanagedChain): Standard load.
• Chain.Load<TChain...>(out string errors, unmanagedChain): Returns an errors string. If no errors occurred, errors is string.Empty. Each error is on a new line.
• Chain.Load<TChain...>(unmanagedChain): A single-argument overload (often used in Debug builds).

Note: The loading process always succeeds even if the unmanaged chain doesn't match the expected types or length exactly. Any structure type found in the expected position will be loaded into the new Chain.

// Loads a new managed chain from an unmanaged chain
using var managedChain = 
    Chain.Load<PhysicalDeviceFeatures2, PhysicalDeviceDescriptorIndexingFeatures, 
        PhysicalDeviceAccelerationStructureFeaturesKHR>(unmanagedChain);

In Silk.NET 3.0, the Surface class manages the application's execution loop. You can control how frequently Tick, Render, and Update events are raised using SurfaceTickOptions, SurfaceTimingOptions, and frequency properties.

Event Types

• Tick: Raised as frequently as possible (or according to TickOptions).
• Render: Raised for redrawing graphics, governed by RenderOptions.
• Update: Raised for logic updates, governed by UpdateOptions.

Controlling Frequency

• Run as fast as possible: Set FramesPerSecond or UpdatesPerSecond to a negative number (which sets TargetDelta to a value close to zero).
• Disable execution: Set FramesPerSecond or UpdatesPerSecond to 0 (which sets TargetDelta to double.MaxValue).
• Event-Driven Ticking: Set TickOptions.IsEventDriven to true to ensure Tick only executes in response to an event or a call to Continue().