Metal.NET 3.0.0

dotnet add package Metal.NET --version 3.0.0
                    
NuGet\Install-Package Metal.NET -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Metal.NET" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Metal.NET" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Metal.NET" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Metal.NET --version 3.0.0
                    
#r "nuget: Metal.NET, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Metal.NET@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Metal.NET&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Metal.NET&version=3.0.0
                    
Install as a Cake Tool

Metal.NET

NuGet Version License: MIT

Low-level C# bindings for Apple's Metal and MetalFX frameworks — auto-generated from the macOS 27.0 SDK via Clang AST + Swift Symbol Graph extraction.

Features

  • Comprehensive coverage — Metal, Metal 4 and MetalFX (257 generated files, including Objective-C interop), plus hand-written wrappers for CoreFoundation, CoreAnimation, CoreGraphics, GCD and SIMD types.
  • Clang AST + Swift Symbol Graph — bindings are extracted from SDK headers, not a hand-maintained IDL. Swift names provide human-readable method & parameter names where Clang only exposes selectors.
  • Zero-overhead value-type wrappers — All Objective-C and Metal objects are readonly struct handles wrapping a single nint, eliminating GC heap allocations, object headers, and finalizer queue pressure.
  • Hierarchy flattening & implicit upcasting — Inherited properties and methods are flattened directly onto derived structs, with zero-cost implicit operator conversions along the Objective-C inheritance chain.
  • Zero-copy span marshalling — Array-taking APIs accept ReadOnlySpan<T> and pin unmanaged wrapper structs directly without intermediate copying.
  • ObjC block support — NativeBlock uses UnmanagedCallersOnly function pointers for zero-overhead callbacks.
  • Native AOT & trimming ready — annotated with IsAotCompatible and IsTrimmable.

Installation

dotnet add package Metal.NET

Requirements: .NET 10+, macOS 15+

Quick Start

using Metal.NET;

// Obtain the default GPU device
MTLDevice device = MTLDevice.CreateSystemDefaultDevice();

// Create a command queue
using MTLCommandQueue queue = device.MakeCommandQueue();

// Load the default shader library
using MTLLibrary library = device.MakeDefaultLibrary();

// Look up a compute function and create a pipeline state
using NSString kernelName = new("myKernel");
using MTLFunction kernel = library.MakeFunction(kernelName);
using MTLComputePipelineState pso = device.MakeComputePipelineState(kernel, out NSError error);

// Create a buffer
using MTLBuffer buffer = device.MakeBuffer(1024, MTLResourceOptions.StorageModeShared);

API Coverage

Framework Files Highlights
Metal / Metal 4 238 Devices, command queues & buffers, render / compute / blit encoders, pipeline states, acceleration structures, tensors with auxiliary planes, MTL4* APIs
MetalFX 18 Temporal & spatial scalers, frame interpolators, content offsets and distortion textures

Hand-written wrappers are included for CoreFoundation (NSObject, NSString, NSArray, …), CoreAnimation (CAMetalLayer, CAMetalDrawable), CoreGraphics (CGColorSpace, CGSize), GCD (DispatchQueue, DispatchData) and SIMD types.

Memory Management

All wrapper types are 8-byte readonly struct handles (unmanaged) with zero GC allocation overhead. Native object lifetimes follow standard Objective-C reference counting (Retain() / Release() / Dispose()):

Origin Release() / Dispose() Typical Usage
new() (AllocInit) / Init* ✓ Descriptors and explicitly allocated objects (new MTLTextureDescriptor())
Make* / New* / Copy* ✓ Factory methods returning retained objects (device.MakeBuffer(...), device.MakeDefaultLibrary())
Property getters / NextDrawable() / transient encoders — Autoreleased or borrowed references managed by parent or NSAutoreleasePool
// Allocated object – dispose when done
using var desc = new MTLTextureDescriptor();

// Retained factory return – caller is responsible for disposal
using MTLLibrary library = device.MakeDefaultLibrary();

// Borrowed property – do not dispose
MTLDevice device = queue.Device;

How It Works

                  ┌──────────────────┐
    macOS SDK     │  Xcode / Clang   │
                  └────────┬─────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
     Clang AST (JSON)        Swift Symbol Graphs
              │                         │
              └────────────┬────────────┘
                           ▼
              parse_metal_ast.py (Python)
                           │
                           ▼
                    metal-ast.json
                           │
                           ▼
              Metal.NET.Generator (C#)
                           │
                           ▼
                  Generated bindings

The pipeline has four stages. The GitHub Actions workflow (extract-metal-api.yml) runs the first three on the xcode-27 runner; C# bindings are then generated locally:

  1. Dump the Clang AST — clang -Xclang -ast-dump=json produces a complete JSON representation of every declaration in the Metal / MetalFX headers.
  2. Extract Swift Symbol Graphs — swift-symbolgraph-extract provides the human-readable Swift names for methods and properties.
  3. Merge into metal-ast.json — A Python script merges both sources, applies Swift name propagation, resolves overload collisions, and outputs a compact JSON describing every enum, struct, protocol, class, property, method, free function and block typedef.
  4. Generate C# bindings — The C# generator reads metal-ast.json and emits idiomatic wrappers that call the Objective-C runtime directly via objc_msgSend.

Project Structure

Metal.NET.slnx
│
├─ Metal.NET/                            Runtime library (NuGet package)
│  ├─ Interop/                           Interop core (hand-written)
│  │  ├─ NativeBlock.cs                  ObjC block support (UnmanagedCallersOnly)
│  │  ├─ ObjectiveC.cs                   Auto-generated objc_msgSend overloads
│  │  ├─ Selector.cs                     Lazy selector handle
│  │  └─ Bool8.cs                        Boolean value type
│  ├─ CoreFoundation/                    Hand-written NS* wrappers
│  ├─ CoreAnimation/                     Hand-written CA* wrappers
│  ├─ CoreGraphics/                      Hand-written CG* wrappers
│  ├─ Dispatch/                          Hand-written Dispatch* wrappers
│  ├─ Simd/                              Hand-written SIMD value types
│  ├─ Metal/                             Auto-generated Metal & Metal 4 API
│  └─ MetalFX/                           Auto-generated MetalFX API
│
├─ Metal.NET.Generator/                  Code generator (not shipped)
│  ├─ AstJsonParser*.cs                  JSON → model (7 partial files)
│  ├─ CSharpEmitter*.cs                  Model → C# source (9 partial files)
│  ├─ TypeMapper.cs                      ObjC ↔ C# type mapping
│  ├─ Models.cs / AstModels.cs           Data models
│  ├─ GeneratorContext.cs                Shared state across stages
│  └─ metal-ast.json                     Extracted API snapshot (generated by CI)
│
└─ .github/
   ├─ workflows/extract-metal-api.yml    CI: extract AST → commit metal-ast.json
   └─ scripts/parse_metal_ast.py         Clang AST + Swift Symbol Graph → JSON

Updating Bindings

  1. Run the Extract Metal API workflow to regenerate metal-ast.json from the macOS SDK bundled with the xcode-27 runner's default Xcode.
  2. Regenerate and verify locally:
dotnet run --project Metal.NET.Generator
dotnet build Metal.NET

License

MIT

Disclaimer

This library was built with AI assistance. It has undergone preliminary testing but has not been exhaustively validated in production scenarios. Please test thoroughly before production use.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Metal.NET:

Package Downloads
Zenith.NET.Metal

A cross-platform rendering hardware interface for .NET with a shared C# API for graphics and compute across DirectX 12, Metal 4, and Vulkan 1.4.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Metal.NET:

Repository Stars
qian-o/Zenith.NET
A cross-platform rendering hardware interface for .NET with a shared C# API for graphics and compute across DirectX 12, Metal 4, and Vulkan 1.4.
Version Downloads Last Updated
3.0.0 53 11/13/2026
3.0.0-alpha.2 44 11/11/2026
3.0.0-alpha.1 47 11/10/2026
3.0.0-alpha.0 45 11/10/2026
2.7.0 225 10/31/2026
2.6.0 95 10/31/2026
2.5.0 121 10/27/2026
2.4.0 429 6/27/2026
2.3.0 323 3/31/2026
2.2.1 159 3/29/2026
2.2.0 140 3/20/2026
2.1.0 137 3/18/2026
2.0.1 139 3/17/2026
2.0.0 141 3/17/2026
1.4.2 152 3/13/2026
1.4.1 152 3/13/2026
1.4.0 153 3/11/2026
1.3.1 155 3/5/2026
1.3.0 143 3/5/2026
1.2.0 149 3/3/2026
Loading failed