Metal.NET 2.0.0

Metal.NET

C# bindings for Apple's Metal graphics API, auto-generated from the Objective-C headers via Clang AST extraction.

The generator parses metal-ast.json — an AST snapshot extracted directly from the macOS SDK using clang -ast-dump=json — and emits idiomatic C# wrappers that call into the Objective-C runtime via objc_msgSend.

Features

• Comprehensive API coverage — Metal, Metal 4, MetalFX, QuartzCore, Foundation, CoreGraphics and GCD bindings.
• Clang AST-based generation — bindings are extracted from the SDK headers, not from a hand-maintained IDL.
• Automatic memory management — three ownership modes (Borrowed, Owned, Managed) with deterministic disposal and optional finalizer safety net.
• Objective-C block support — NativeBlock wrappers use UnmanagedCallersOnly function pointers for zero-overhead callbacks.
• Native AOT & trimming ready — the library is 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.NewCommandQueue();

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

// Look up a compute function and create a pipeline state
using MTLFunction kernel = library.NewFunction("myKernel");
using MTLComputePipelineState pso = device.NewComputePipelineState(kernel);

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

API Coverage

Memory Management

Every NativeObject wrapper has a NativeObjectOwnership that controls its lifetime:

// Managed – finalizer will release if not disposed
var desc = new MTLTextureDescriptor();

// Owned – caller is responsible for disposal
using MTLLibrary library = device.NewDefaultLibrary();

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

Project Structure

Metal.NET.slnx
├── Metal.NET/                          ← Runtime library (NuGet package)
│   ├── Common/                         ← Hand-written interop core
│   │   ├── NativeObject.cs             ← Base class for all ObjC wrappers
│   │   ├── NativeBlock.cs              ← ObjC block wrappers (UnmanagedCallersOnly)
│   │   ├── ObjectiveC.cs               ← Auto-generated objc_msgSend overloads
│   │   └── ...
│   ├── Foundation/                     ← Hand-written NS* wrappers
│   ├── CoreGraphics/                   ← Hand-written CG* wrappers
│   ├── GCD/                            ← Hand-written Dispatch* wrappers
│   ├── Metal/                          ← Auto-generated Metal & Metal 4 API
│   │   ├── MTLEnums.cs                 ← All Metal enumerations
│   │   ├── MTLStructs.cs               ← All Metal structs
│   │   ├── MTLDelegates.cs             ← Block handler classes
│   │   └── MTL*.cs / MTL4*.cs          ← Protocol & class wrappers
│   ├── MetalFX/                        ← Auto-generated MetalFX API
│   └── QuartzCore/                     ← Auto-generated QuartzCore API
│
└── Metal.NET.Generator/                ← Code generator (not shipped)
    ├── AstJsonParser.cs                ← Parses metal-ast.json
    ├── CSharpEmitter.cs                ← Emits C# source files
    ├── TypeMapper.cs                   ← ObjC → C# type mapping
    └── metal-ast.json                  ← Extracted API definitions (generated by CI)

Updating Bindings

1. Run the Extract Metal API GitHub Action (extract-metal-api.yml) to regenerate metal-ast.json from the latest Xcode SDK.
2. Regenerate the C# bindings and verify:

dotnet run --project Metal.NET.Generator
dotnet build Metal.NET

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.