Bindings to the Metal framework

See Apple's docs and the general docs on framework crates for more information.

Metal has tools for validating that you're using it correctly, using these is highly recommended! See Apple's documentation on it, or run man MetalValidation to get information on environment variables.

NOTE: To use MTLCreateSystemDefaultDevice you need to link to CoreGraphics, this can be done by using objc2-core-graphics, or by doing:

#[link(name = "CoreGraphics", kind = "framework")]
extern "C" {}

Safety considerations

Metal allows running arbitrary code on the GPU. We treat memory safety issues on the GPU as just as unsafe as that which applies to the CPU. A few notes on this below.

Shaders

Shaders are (often) written in an unsafe C-like language.

Loading them (via MTLLibrary, function stitching etc.) is perfectly safe, it is similar to dynamic linking. The restrictions that e.g. libloading::Library::new labours under do not apply, since there are no ctors in the Metal Shading Language (see section 4.2).

Similarly, getting individual shaders (MTLFunction) is safe, we can model this as the same as calling dlsym (which just returns a pointer).

Calling functions though, is not safe. Even though they can have their parameter and return types checked at runtime, they may have additional restrictions not present in the signature (e.g. __builtin_unreachable() is possible in MSL, so is out-of-bounds accesses). If you view MTLFunction as essentially just an unsafe fn() pointer, this should be apparent.

Bounds checks

It is yet unclear whether Metal APIs are bounds-checked on the CPU side or not, so APIs that take offsets / lengths are often unsafe.

Synchronization

MTLResource subclasses such as MTLBuffer and MTLTexture require synchronization between the CPU and the GPU, or between different threads on the GPU itself, so APIs taking these are often unsafe.

Memory management and lifetimes

Resources used in MTL4CommandBuffers or command buffers with created with one of:

• MTLCommandBufferDescriptor::setRetainedReferences(false).
• MTLCommandQueue::commandBufferWithUnretainedReferences().

Must be kept alive for as long as they're used.

Type safety

MTLBuffer is untyped (in a similar manner as a [u8] slice), you must ensure that any usage of it is done with valid types.

objc2-metal

Rust bindings to Apple's framework Metal.

This README is kept intentionally small to consolidate the documentation, see the Rust docs for more details on this crate.

This crate is part of the objc2 project, see that for related crates.