Metal.NET
3.0.0
dotnet add package Metal.NET --version 3.0.0
NuGet\Install-Package Metal.NET -Version 3.0.0
<PackageReference Include="Metal.NET" Version="3.0.0" />
<PackageVersion Include="Metal.NET" Version="3.0.0" />
<PackageReference Include="Metal.NET" />
paket add Metal.NET --version 3.0.0
#r "nuget: Metal.NET, 3.0.0"
#:package Metal.NET@3.0.0
#addin nuget:?package=Metal.NET&version=3.0.0
#tool nuget:?package=Metal.NET&version=3.0.0
Metal.NET
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 structhandles wrapping a singlenint, 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 operatorconversions along the Objective-C inheritance chain. - Zero-copy span marshalling — Array-taking APIs accept
ReadOnlySpan<T>and pinunmanagedwrapper structs directly without intermediate copying. - ObjC block support —
NativeBlockusesUnmanagedCallersOnlyfunction pointers for zero-overhead callbacks. - Native AOT & trimming ready — annotated with
IsAotCompatibleandIsTrimmable.
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:
- Dump the Clang AST —
clang -Xclang -ast-dump=jsonproduces a complete JSON representation of every declaration in the Metal / MetalFX headers. - Extract Swift Symbol Graphs —
swift-symbolgraph-extractprovides the human-readable Swift names for methods and properties. - 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. - Generate C# bindings — The C# generator reads
metal-ast.jsonand emits idiomatic wrappers that call the Objective-C runtime directly viaobjc_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
- Run the Extract Metal API workflow to regenerate
metal-ast.jsonfrom the macOS SDK bundled with thexcode-27runner's default Xcode. - Regenerate and verify locally:
dotnet run --project Metal.NET.Generator
dotnet build Metal.NET
License
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 | Versions 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. |
-
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 |