Magnesium

C# Vulkan interface/polyfill for WINDOWS and MacOS

Quick Links

• CHANGELOG
• NUGET PACKAGES
• EXAMPLES
• BUILD INSTRUCTIONS
• DESIGN DECISIONS
• LICENSE
• WHY?
• CROSS PLATFORM DEV GUIDE
• PLATFORM SUMMARY
• IMPLEMENTATIONS TODOs

CHANGELOG

Magnesium and its implementations uses Semantic Versioning v2.0.0 for versioning assemblies

Version 5.2.8 (full release)

SHOULD BE LAST COMPATIBLE VERSION BEFORE INTERFACE CHANGE i.e. Mg 7.0.0

• Magnesium v5.2.9 - 10 Oct 2017
  • New enum value MgDeviceExtensionOption.SWAPCHAIN_ONLY
  • MgDefaultGraphicsConfiguration uses MgDeviceExtensionOption.SWAPCHAIN_ONLY as its default option
  • MgDefaultGraphicsDevice will ignore user specified DepthFormat and use highest available version
• Magnesium.OpenGL v6.1.4
  • Updated w.r.t Magnesium v5.2.9
• Magnesium.OpenGL.DesktopGL v6.1.5
  • Updated w.r.t Magnesium v5.2.9
  • GL002 - Fixed LineStrip issue (missing enum in switch)
• Magnesium.Vulkan v5.0.7
  • Updated w.r.t Magnesium v5.2.9
• Magnesium.PresentationSurfaces.OpenTK v1.0.4
  • Updated w.r.t Magnesium v5.2.9
• Magnesium.Ktx v1.0.4
  • Updated w.r.t Magnesium v5.2.9

Version 5.2.8-beta

• Magnesium v5.2.8 - 2 Sep 2017
  • New enum value MgDeviceExtensionOption.SWAPCHAIN_ONLY
  • MgDefaultGraphicsConfiguration uses MgDeviceExtensionOption.SWAPCHAIN_ONLY as its default option
  • MgDefaultGraphicsDevice will ignore user specified DepthFormat and use highest available version
• Magnesium.OpenGL v6.1.4 beta
• Magnesium.OpenGL.DesktopGL v6.1.4 beta
• Magnesium.Vulkan v5.0.7 beta
• Magnesium.PresentationSurfaces.OpenTK v1.0.4 beta
• Magnesium.Ktx v1.0.4 beta
  • Updated w.r.t Magnesium v5.2.7

Version 6.0.0

• Magnesium.OpenGL v6.0.0 - 8 Feb 2017
• Magnesium.OpenGL.DesktopGL v6.0.0 - 8 Feb 2017
  • w.r.t Magnesium v5.0.4
  • Implemented descriptor sets functionality
  • Implemented GLFullFence of IMgFence interface
  • Implemented CopyBuffers into CommandBuffers

Version 5.0.0

• Removing descriptor pool from IMgQueueInfo.CreatePartition because MgDescriptorPools should be explicitly set based on usage
• Added IMgGraphicsConfiguration/MgDefaultGraphicsConfiguration to process one IMgThreadPartition
• Modify IMgPresentationSurface.Initialize method signature
  • void Initialize(MgFormat format, uint width, uint height);
• New assembly created Magnesium.PresentationSurfaces.OpenTK
• (BUGFIX) Magnesium.Vulkan v5.0.2 - 9th Nov 2016
  • FIXED - CmdBindDescriptorSets to pass in null into dynamic offsets
  • FIXED - CreateGraphicsPipelines to accept array of dynamic states
• Magnesium.Metal v5.0.0 - 9 Nov 2016
  • Updated w.r.t Magnesium v5.0.4
• Magnesium.Ktx v1.0.0 - 24 Dec 2016
  • Loads Khronos .ktx image files

Version 4.0.0

• Moving all implementations under one roof/repository
  • Magnesium
    • interface only
  • Magnesium.Vulkan
    • Vulkan implementation from existing repository
  • Magnesium.OpenGL
    • partial implementation created for MonoGame
  • Magnesium.OpenGL.AndroidGL - implementation created for MonoGame + OpenTK
  • Magnesium.OpenGL.DesktopGL
    • implementation created for MonoGame + OpenTK
  • Magnesium.Metal
    • implementation using Metal iOS API for MacOS and iOS

Version 3.0.0

• Breaking changes from classes to interfaces due to Magnesium.Vulkan implementation

Version 2.0.0

• Breaking changes to function

Version 1.0.0

• Now using Semantic Versioning v2.0.0 (http://semver.org/)

NUGET PACKAGES

BUILD INSTRUCTIONS

1. Change directory to the Build folder in the repository
2. Open Mg ALL BUILD.sln in Visual Studio or Xamarin Studio
3. Build all projects attached to this solution. The assemblies can be found in the bin/
   • Magnesium
   • Magnesium.OpenGL
   • Magnesium.Vulkan

EXAMPLES

All Magnesium demos can be found in the examples folder

• InstanceDemo (Windows)
  • Console only Vulkan interface test
• MetalSample (MacOS)
  • IOC library used - SimpleInjector
  • Spinning cube translation of Metal cube demo
• KtxReader (Cross-Platform)
  • Opens a .ktx for testing
• TriangleDemo (Windows, OpenTK)
  • Shared application code running on Vulkan and OpenGL
  • IOC library used - LightInject
  • Simple Vulkan triangle demo based on Sascha Willems's triangle demo
• TextureDemo (Windows, OpenTK)
  • IOC library used - DryIoc
  • Opens a .ktx image file and display it on a plane. Code based on Sascha Willems's texture demo

DESIGN DECISIONS

1. It is the responsibility of the programmer to clean up any unmanaged memory used by Mg objects themselves after use. Almost Mg interfaces require explicit calls to its DestoryXXX methods (e.g. void vkDestroyInstance ) to dispose any memory associated to the objects.

2. Magnesium does not SPECIFIC a shader language of choice, rather relying on the shader language available to the platform itself.

3. To benefit more multi-threaded application use in Vulkan/Magnesium, it is recommended to restrict instances of command pools (i.e. IMgCommandPool) and descriptor pools (i.e. IMgDescriptorPool) to a single thread. For example, in application that uses 2 thread, each thread would have its own descriptor pool(s) and command pool(s) and none of the instances should be shared between those threads.

4. (TODO) You will not directly modify/set for any indirect draw call buffer data as the structs used for indirect draws. Therefore a indirect interface class must be created act as a bridge to allow improve portability.

LICENSE

Licensed under MIT license

WHY?

Scenario 1: You want to implement a cross-platform C#/.net 2D/3D application with graphics API/library that uses modern high-performance features such as

• compute shaders
• tessellation shaders
• immutable storage
• compiled shader bytecode
• constant buffers/shader storage buffer objects
• upfront memory allocation
• general purpose memory
• multi-indirect instanced draws

However, the choice of the graphics API is dependant on the platform itself.

1. DirectX 11/12: Available for Windows 10 and Xbox. No support for MacOS or Linux (double check?).
2. OpenGL and OpenGL ES: Available on all platforms. Yet Mac devices are limited to OpenGL 4.1.
3. Vulkan: a next generation low level graphics library designed with respect to multi-threading devices. Now available on Windows, Android N devices and Linux. Unofficial MacOS driver support available via MoltenVK
4. Metal: Apple's own graphics rendering library that has modern features such as compute shaders.

Vulkan is almost the correct choice for a modern graphics library because there is native driver support for Windows, Linux and Android N platforms.

So Magnesium is primarily a C#/.net interface for Vulkan (for Windows).

However, Vulkan itself is not available or arriving on a number of platforms (e.g Apple) and leaves a number of the devices i.e. iPad, iPhone, pre Android-N devices and even HTML 5 browsers unsupported.

Here is where Magnesium comes to the rescue; it is an interface of Vulkan. We can use dependency injection (i.e. BYO C# IOC container not MEF) to load a polyfill instead into your applications if native Vulkan support is not available.

To reach a wider number of platforms, all implementations have compiled as portable core library profile 111. Maybe moving to .NET standard 2.0 when released. To reduce recompilation, Magnesium libraries are compiled with minimal preprocessor defines

• Most debug assemblies only use DEBUG

A exception is Magnesium.Metal which uses UNIFIED for both debug and release assemblies as Xamarin assemblies that are compiled with UNIFIED can be both for iOS and MacOS applications.

CROSS PLATFORM DEV GUIDE

IMgShaderModule

Magnesium does not SPECIFIC a shader language of choice, rather relying on the shader language available to the platform itself.

By passing a System.IO.Stream handle contain some data and its length in bytes into IMgDevice.CreateShaderModule, Magnesium and its implementation can cater to any shader file type.

public class MgShaderModuleCreateInfo
{
	public Stream Code { get; set; }
	public UIntPtr CodeSize { get; set; }
}

OPENGL: Since METAL does not allow "main" as a function entrypoint in MgPipelineStageCreateInfo.Name,
OpenGL GLSL shaders should not include void main() function section in the source code. To work around GLSL inability to specify a shader name, the Magnesium.OpenGL implementation will append the void main() { <shader_name>() } dynamically.

public class MgPipelineStageCreateInfo
{
	public MgPipelineStageFlagBits Stage { get; set; }
	public string Name { get; set; }	
}

VULKAN: Since METAL does not allow "main" as a function entrypoint in MgPipelineStageCreateInfo.Name, please use another entrypoint other than "main". See SPIRVReplace CLI to convert glsl to valid SPIRV bytecode on Windows.

METAL: final Position.y should be flipped in the vertex shader

OPENGL: gl_Position.y should be flipped in the vertex shader

	gl_Position = vec4(in_position.x, -in_position.y, 0, 1);

Compute

METAL: compute pipelines need to specify the dimensions of the workgroup therefore you must specify ThreadsPerWorkgroup when calling IMgDevice.CreateComputePipelines.

public class MgComputePipelineCreateInfo
{
	public MgPipelineCreateFlagBits Flags { get; set; }
	public MgPipelineShaderStageCreateInfo Stage { get; set; }
	public IMgPipelineLayout Layout { get; set; }
	// REQUIRED FOR METAL
	public MgVec3Ui ThreadsPerWorkgroup { get; set;}
	public IMgPipeline BasePipelineHandle { get; set; }
	public Int32 BasePipelineIndex { get; set; }
}

Descriptor Sets

OPENGL: Only one of the descriptor sets can be bound.
METAL: Only one of the descriptor sets can be bound. Internally, descriptor sets, vertex buffers, samplers and textures are combined together within the shaders.

PLATFORM SUMMARY

IMPLEMENTATIONS TODOs

Written with StackEdit & Visual Studio Code