Table of Contents

Project Setup

This page creates the .NET project used throughout the guides. It installs the current Zenith.NET packages, enables the low-level C# features used for GPU uploads, and configures shader and texture assets for the build output.

The runnable reference implementation is maintained separately in ZenithTutorials. You do not need to clone that repository to follow the guides.

Requirements

Install the .NET 10 SDK and a current graphics driver. Verify the SDK from a terminal:

dotnet --list-sdks

Zenith.NET selects a supported graphics API for the current operating system:

Operating system Graphics API
Windows DirectX 12
macOS Metal 4
Linux Vulkan 1.4

Ray tracing and mesh shading are optional device capabilities. The corresponding guides check support at runtime before creating those resources.

Create the project

Create a .NET 10 console application and enter its directory:

dotnet new console --framework net10.0 --name ZenithTutorials
cd ZenithTutorials

Add the windowing package, the Zenith.NET graphics packages, and the ImageSharp extension. No version is specified, so the CLI selects the latest compatible package available from the configured NuGet sources.

dotnet package add Silk.NET.Windowing
dotnet package add Zenith.NET
dotnet package add Zenith.NET.DirectX12
dotnet package add Zenith.NET.Metal
dotnet package add Zenith.NET.Vulkan
dotnet package add Zenith.NET.Extensions.ImageSharp

All three graphics packages can remain in one project. The application host creates only the graphics context selected for the current operating system.

Configure the project

Open ZenithTutorials.csproj. Keep the package references generated by the CLI and make sure the main property group contains these settings:

<PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>

Several guides upload unmanaged structures by pointer, so AllowUnsafeBlocks is required. Nullable analysis remains enabled for resources that are created lazily or recreated after a resize.

AllowUnsafeBlocks permits unsafe code to compile; the type or method containing each pointer expression must still be declared unsafe. The reference host and the renderers that upload structures by pointer include that declaration in their complete source files.

Shaders and textures are opened at runtime from the application directory. Add this item group after the package references:

<ItemGroup>
    <None Update="Assets/Shaders/**/*;Assets/Textures/**/*">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>

PreserveNewest copies changed assets without rewriting every file on every build.

Create the source layout

Create the following folders and files as the guides introduce them:

ZenithTutorials/
├── Assets/
│   ├── Shaders/
│   └── Textures/
├── Renderers/
├── App.cs
├── CocoaHelper.cs
├── IRenderer.cs
├── Program.cs
├── TexturePresenter.cs
├── Usings.cs
└── ZenithTutorials.csproj

The application host is shared by every guide. Each workload adds one renderer under Renderers and one Slang source file under Assets/Shaders.

These guides are walkthroughs of the current reference implementation rather than file-by-file listings. Each code fence is a contiguous excerpt from that implementation. Use the Complete source links at the end of a page when assembling the runnable file; the surrounding text explains why the excerpt exists and how it participates in the workload.

Add shared namespaces

Create Usings.cs:

global using System.Numerics;
global using System.Runtime.CompilerServices;
global using System.Runtime.InteropServices;
global using Zenith.NET;
global using Zenith.NET.Extensions.ImageSharp;
global using Buffer = Zenith.NET.Buffer;

The alias on the final line resolves the name shared by System.Buffer and Zenith.NET.Buffer. System.Numerics supplies the vectors and matrices used by both the CPU data structures and the camera calculations.

Build the empty project

Build once before adding the host:

dotnet build

A successful build confirms that the SDK and packages restore correctly. No graphics device or window is created during dotnet build; those operations begin when the application runs.

Continue with Application Host to add the shared window, graphics context, swap chain, and frame loop.

Reference project

The finished project configuration and shared usings are available in the tutorial repository:

The reference repository uses local project references so it can track Zenith.NET development. For a standalone reader project, keep the NuGet package references created above.

Edit this page