Adamantium.Engine.Compiler 0.1.0-alpha.5

Adamantium Engine

A graphics engine for .NET on its own Vulkan bindings: a Vulkan renderer, effects compiled to SPIR-V at build time, fonts with MSDF atlases, image codecs, 3D model import and an entity-component system. It is the foundation of Adamantium UI, where a 3D scene and the interface around it are drawn by one renderer in one process.

Alpha. Windows only for now, and the API will change between releases.

Packages

All packages share one version and are released together.

Requirements

• .NET 10.

• Windows 10 or 11, x64. macOS and Linux are planned; the macOS code exists but has not been built and run recently, so it is not claimed.

• A GPU and driver with Vulkan 1.4 and the shaderInt64, shaderDrawParameters and samplerAnisotropy features, buffer device addresses and descriptor indexing - for descriptor sets, update after bind of sampled images. Neither of the newer extensions is needed from the driver: without VK_EXT_descriptor_heap the engine binds through descriptor sets, and VK_EXT_shader_object comes with the Adamantium.Vulkan.ShaderObjectLayer package - Khronos' shader object layer - where the driver lacks it. By the vendors' driver notes:

  • NVIDIA: Turing or newer - GeForce GTX 16 and RTX 20 series and later, Quadro RTX and T series, RTX A, Ada and Blackwell.
  • AMD: RDNA or newer - Radeon RX 5000 series and later, from Adrenalin 25.1.1. The RX 5000 and RX 6000 series now get their own driver from AMD.
  • Intel: Arc and Core Ultra graphics whose driver reports Vulkan 1.4 - vulkaninfo says which.

  The engine is developed and tested on an NVIDIA Quadro RTX 4000 with NVIDIA's Vulkan developer driver, with the descriptor heap and with descriptor sets; other GPUs have not been tested.

• No Vulkan SDK. The Slang shader compiler ships in the Adamantium.Vulkan.Slang package.

Getting started

dotnet add package Adamantium.Engine --prerelease

Adamantium.Engine brings in most of the others as dependencies. Add the input and platform packages you need beside it.

Your own effects

Every .fx file in a project becomes a class at build time, in the assembly's name and the folders the file sits in: Effects/Glow.fx in an assembly named MyApp gives MyApp.Effects.Glow, derived from Effect. The generator needs to see the files, the project's folder to find those folders, and where the Slang compiler is:

<ItemGroup>
  <PackageReference Include="Adamantium.Engine.Generators" Version="0.1.0-alpha.5" PrivateAssets="all" />
  <PackageReference Include="Adamantium.Vulkan.Slang" Version="1.1.0" GeneratePathProperty="true" PrivateAssets="all" />
  <AdditionalFiles Include="**\*.fx;**\*.fxh" />
  <CompilerVisibleProperty Include="ProjectDir;AdamantiumSlangPath" />
</ItemGroup>

<PropertyGroup>
  <AdamantiumSlangPath>$(PKGAdamantium_Vulkan_Slang)</AdamantiumSlangPath>
</PropertyGroup>

A shader that does not compile fails the build with the compiler's message.

Your own content

Assets live in a content project of their own, as in XNA: a library whose files are its assets. Every project that references it, directly or through another, gets them in its output.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Adamantium.Content.Build" Version="0.1.0-alpha.5" />
  </ItemGroup>
</Project>

• What is content. Every file of the project but its code, its build files and hidden files. Leave one out with <AdamantiumContent Remove="..." />; bring one in from elsewhere with <AdamantiumContent Include="..\Shared\logo.png" Link="Textures\logo.png" />.
• The build. A model (Collada, OBJ, 3DS, glTF) is imported into the engine's own format beside its source - Ship.dae.aemf beside Ship.dae - when it has none yet, or its source or its settings changed; that file goes to the output, the source does not. A new engine never rewrites them on its own. The rest is copied as it is. Only what changed is built again.
• Where it goes. To Content/{Name}/ of the application's folder, where {Name} is the last segment of the project's name (MyGame.ShipContent gives ShipContent), or AdamantiumContentName. Two content projects an application references need different names.
• Finding it. The class {Name}Assets has a constant for each asset: its path from the application's folder, a model's being its source's path. The universe's AssetService loads by it, taking the .aemf when there is one:

var scene = await universe.Assets.LoadAsync<SceneData>(ShipContentAssets.Models.Ship.Ship_dae);

dotnet new adamantium-content (from Adamantium.Engine.Templates) creates such a project; Rider and Visual Studio list it in New Project.

Building from source

git clone https://github.com/AdamantiumStudio/AdamantiumEngine.git
cd AdamantiumEngine
dotnet build AdamantiumEngine.sln -c Debug

Everything the build needs comes from nuget.org. The tests are in AdamantiumEngine.Tests.sln; Adamantium.Engine.GraphicsTests needs a Vulkan device that meets the requirements above.

Related repositories

• AdamantiumUI: the UI framework built on this engine.
• AdamantiumVulkan: the Vulkan, Slang and SPIR-V bindings.
• QuantumBinding: the generator those bindings are made with.

License

Apache-2.0. Parts of the engine are derived from third-party work under MIT and ISC; their notices are in the file headers and in THIRD-PARTY-NOTICES.md.