macOS Metal GPU Programming

Introduction to Metal GPU Programming on macOS

Metal is Apple's low-level, low-overhead hardware-accelerated graphics and compute API. Introduced in 2014, Metal provides near-direct access to the GPU (Graphics Processing Unit) on macOS, iOS, iPadOS, and tvOS devices. It replaces OpenGL as the primary graphics API on Apple platforms and offers developers fine-grained control over GPU resources, command scheduling, and memory management.

Unlike higher-level APIs, Metal is designed to minimize CPU overhead by allowing developers to pre-compile shaders, encode commands ahead of time, and reuse command buffers efficiently. This makes it ideal for demanding applications such as games, video editing software, machine learning pipelines, and scientific simulations.

Why Metal Matters

Before Metal, macOS developers relied on OpenGL, which carried significant CPU overhead due to its state validation and driver-side complexity. Metal addresses these limitations by exposing a thinner abstraction layer over the GPU hardware. The result is better performance, more predictable frame times, and the ability to leverage the GPU for general-purpose compute tasks—not just rendering.

Metal also integrates tightly with Apple Silicon. On M-series chips, the GPU shares unified memory with the CPU, eliminating the need to copy data across a PCIe bus. Metal exposes this unified memory architecture through features like MTLBuffer shared mode, enabling zero-copy data transfer between CPU and GPU code.

Core Concepts of Metal

Before writing Metal code, it is essential to understand the foundational objects and the rendering pipeline. Metal is built around a small set of core types that work together to submit work to the GPU.

The Metal Device

The MTLDevice object represents the GPU. It is the root object from which all other resources are created. On a Mac with both integrated and discrete GPUs, you can enumerate available devices and choose the most appropriate one.

Command Queues and Command Buffers

A MTLCommandQueue is a queue that accepts MTLCommandBuffer objects. Each command buffer contains a sequence of encoded commands—either render, compute, or blit commands—that the GPU executes in order. Command buffers are lightweight and can be created per frame without significant overhead.

The Render Pipeline State

The MTLRenderPipelineState object encapsulates a compiled graphics pipeline, including vertex and fragment shader functions, blend state, and pixel formats. Creating a pipeline state is expensive because it involves shader compilation, so you should create it once and reuse it.

Shaders and the Metal Shading Language

Metal shaders are written in the Metal Shading Language (MSL), a C++14-based language with additions for GPU programming. Shaders are typically stored in .metal files and compiled at build time by the Metal compiler, or at runtime from source strings.

Setting Up a Metal Project

To use Metal in a macOS application, you need a project configured with the Metal framework. In Xcode, create a new macOS app and link against Metal.framework and MetalKit.framework. MetalKit provides convenience classes like MTKView that handle the presentation layer for you.

The basic setup steps are:

• Create or obtain a MTLDevice instance.
• Create a MTLCommandQueue from the device.
• Configure a MTKView with the device and a delegate.
• Load and compile shader functions from a .metal file.
• Build a MTLRenderPipelineState object.
• In the draw callback, encode and commit a command buffer each frame.

Writing Your First Metal Shader

Let us start with a simple vertex and fragment shader pair. This example renders a single triangle with a solid color. The shader code goes in a file named Shaders.metal.

#include <metal_stdlib>
using namespace metal;

// Vertex input structure
struct VertexIn {
    float3 position [[attribute(0)]];
    float4 color    [[attribute(1)]];
};

// Vertex output structure passed to the fragment shader
struct VertexOut {
    float4 position [[position]];
    float4 color;
};

// Vertex shader
vertex VertexOut vertex_main(device VertexIn* vertices [[buffer(0)]],
                             uint vid [[vertex_id]])
{
    VertexOut out;
    out.position = float4(vertices[vid].position, 1.0);
    out.color = vertices[vid].color;
    return out;
}

// Fragment shader
fragment float4 fragment_main(VertexOut in [[stage_in]])
{
    return in.color;
}

The [[attribute(n)]] syntax binds vertex buffer attributes to shader inputs. The [[vertex_id]] attribute gives the shader the index of the current vertex. The [[position]] attribute marks the output field that the rasterizer uses to determine pixel positions. The [[stage_in]] attribute in the fragment shader receives interpolated values from the vertex shader output.

Creating the Pipeline and Rendering

Now let us look at the Swift code that sets up the pipeline and renders the triangle. This code goes in a Renderer class that conforms to MTKViewDelegate.

import MetalKit

class Renderer: NSObject, MTKViewDelegate {
    let device: MTLDevice
    let commandQueue: MTLCommandQueue
    let pipelineState: MTLRenderPipelineState
    var vertexBuffer: MTLBuffer?

    init?(metalView: MTKView) {
        guard let device = MTLCreateSystemDefaultDevice() else {
            fatalError("Metal is not supported on this device")
        }
        self.device = device
        self.commandQueue = device.makeCommandQueue()!

        metalView.device = device
        metalView.colorPixelFormat = .bgra8Unorm

        // Load the default Metal library containing our shaders
        let library = try! device.makeDefaultLibrary()
        let vertexFunction = library.makeFunction(name: "vertex_main")
        let fragmentFunction = library.makeFunction(name: "fragment_main")

        // Configure the pipeline descriptor
        let pipelineDescriptor = MTLRenderPipelineDescriptor()
        pipelineDescriptor.vertexFunction = vertexFunction
        pipelineDescriptor.fragmentFunction = fragmentFunction
        pipelineDescriptor.colorAttachments[0].pixelFormat = .bgra8Unorm

        // Describe the vertex buffer layout
        let vertexDescriptor = MTLVertexDescriptor()
        vertexDescriptor.attributes[0].format = .float3   // position
        vertexDescriptor.attributes[0].offset = 0
        vertexDescriptor.attributes[0].bufferIndex = 0
        vertexDescriptor.attributes[1].format = .float4   // color
        vertexDescriptor.attributes[1].offset = MemoryLayout<Float>.size * 3
        vertexDescriptor.attributes[1].bufferIndex = 0
        vertexDescriptor.layouts[0].stride = MemoryLayout<Float>.size * 7

        pipelineDescriptor.vertexDescriptor = vertexDescriptor

        do {
            pipelineState = try device.makeRenderPipelineState(descriptor: pipelineDescriptor)
        } catch {
            fatalError("Failed to create pipeline state: \(error)")
        }

        super.init()
        createVertexBuffer()
    }

    func createVertexBuffer() {
        // Three vertices: position (x, y, z) + color (r, g, b, a)
        let vertices: [Float] = [
             0.0,  0.7, 0.0,   1.0, 0.0, 0.0, 1.0,  // top - red
            -0.7, -0.5, 0.0,   0.0, 1.0, 0.0, 1.0,  // bottom left - green
             0.7, -0.5, 0.0,   0.0, 0.0, 1.0, 1.0,  // bottom right - blue
        ]
        vertexBuffer = device.makeBuffer(bytes: vertices,
                                         length: vertices.count * MemoryLayout<Float>.size,
                                         options: [])
    }

    func mtkView(_ view: MTKView, drawableSizeWillChange size: CGSize) {
        // Handle window resize if needed
    }

    func draw(in view: MTKView) {
        guard let drawable = view.currentDrawable,
              let renderPassDescriptor = view.currentRenderPassDescriptor else {
            return
        }

        let commandBuffer = commandQueue.makeCommandBuffer()!
        let renderEncoder = commandBuffer.makeRenderCommandEncoder(
            descriptor: renderPassDescriptor
        )!

        renderEncoder.setRenderPipelineState(pipelineState)
        renderEncoder.setVertexBuffer(vertexBuffer, offset: 0, index: 0)
        renderEncoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
        renderEncoder.endEncoding()

        commandBuffer.present(drawable)
        commandBuffer.commit()
    }
}

This renderer creates a pipeline state once during initialization, allocates a vertex buffer with three colored vertices, and then encodes a single draw call each frame. The drawPrimitives command tells the GPU to render a triangle from the three vertices in the buffer.

GPU Compute with Metal

Metal is not limited to graphics. You can also use it for general-purpose compute through kernel functions. A compute pipeline uses MTLComputePipelineState and MTLComputeCommandEncoder instead of their render counterparts. This is useful for image processing, physics simulations, and data transformations.

Here is a simple compute kernel that adds two arrays element-wise:

#include <metal_stdlib>
using namespace metal;

kernel void add_arrays(device const float* a [[buffer(0)]],
                       device const float* b [[buffer(1)]],
                       device float* result   [[buffer(2)]],
                       uint id [[thread_position_in_grid]])
{
    result[id] = a[id] + b[id];
}

And the corresponding Swift code to dispatch the compute kernel:

func runCompute() {
    let count = 1024
    let size = count * MemoryLayout<Float>.size

    let aBuffer = device.makeBuffer(length: size, options: [])!
    let bBuffer = device.makeBuffer(length: size, options: [])!
    let resultBuffer = device.makeBuffer(length: size, options: [])!

    // Fill aBuffer and bBuffer with data (omitted for brevity)

    let library = try! device.makeDefaultLibrary()
    let kernelFunction = library.makeFunction(name: "add_arrays")!
    let computePipelineState = try! device.makeComputePipelineState(function: kernelFunction)

    let commandBuffer = commandQueue.makeCommandBuffer()!
    let computeEncoder = commandBuffer.makeComputeCommandEncoder()!

    computeEncoder.setComputePipelineState(computePipelineState)
    computeEncoder.setBuffer(aBuffer, offset: 0, index: 0)
    computeEncoder.setBuffer(bBuffer, offset: 0, index: 1)
    computeEncoder.setBuffer(resultBuffer, offset: 0, index: 2)

    let threadGroupSize = MTLSize(width: 64, height: 1, depth: 1)
    let threadGroups = MTLSize(width: (count + 63) / 64, height: 1, depth: 1)

    computeEncoder.dispatchThreadgroups(threadGroups,
                                        threadsPerThreadgroup: threadGroupSize)
    computeEncoder.endEncoding()
    commandBuffer.commit()
    commandBuffer.waitUntilCompleted()

    // Read back results from resultBuffer
}

The thread_position_in_grid attribute gives each thread a unique index, allowing each thread to process one element. The dispatchThreadgroups call divides the work into thread groups, each containing 64 threads. Choosing the right thread group size depends on the GPU architecture and the workload, but 64 or 256 threads per group is a common starting point.

Best Practices for Metal Development

Reuse Pipeline State Objects

Creating a MTLRenderPipelineState or MTLComputePipelineState involves shader compilation and is expensive. Always create these objects during initialization or loading screens, never during per-frame rendering. Cache them and switch between cached states as needed.

Minimize Synchronization

CPU-GPU synchronization is costly. Avoid calling waitUntilCompleted in performance-critical paths. Instead, use double or triple buffering for resources that the CPU writes to and the GPU reads from. This allows the CPU to prepare frame N+1 while the GPU processes frame N without stalling.

Use Constant Buffers Efficiently

Small, frequently updated data like transformation matrices should be placed in a shared MTLBuffer using the .storageModeShared option on Apple Silicon. You can use a ring buffer approach to write new constant data each frame without waiting for the GPU to finish reading previous data.

Profile with Metal System Trace

Xcode Instruments includes a Metal System Trace template that shows detailed timing of GPU command execution, CPU encoding, and synchronization events. Use it to identify bottlenecks—whether your application is CPU-bound (encoding takes too long) or GPU-bound (the shader is the bottleneck).

Validate with the Metal Validation Layer

During development, enable the Metal validation layer in Xcode's scheme settings. It catches errors such as invalid pipeline configurations, missing vertex attributes, and incorrect buffer bindings. Disable it for release builds, as it adds overhead.

Choose the Right Storage Mode

Metal buffers support several storage modes. On Apple Silicon, .storageModeShared allows both CPU and GPU to access the buffer through unified memory. .storageModePrivate is GPU-only and is faster for GPU-exclusive data. On Intel Macs with discrete GPUs, .storageModeManaged requires explicit synchronization between CPU and GPU memory. Understanding these modes is critical for performance.

Batch Draw Calls

Each draw call has overhead. Use instanced rendering (drawIndexedPrimitives with an instance count) to render many copies of the same geometry in a single call. Use indirect command buffers to let the GPU generate draw commands, reducing CPU involvement.

Conclusion

Metal is a powerful and expressive API that gives macOS developers direct control over the GPU for both graphics and compute workloads. By understanding the core objects—the device, command queue, command buffers, pipeline states, and shaders—you can build high-performance rendering and computation pipelines. The key to getting the most out of Metal is to minimize CPU overhead by reusing compiled pipeline states, avoiding unnecessary synchronization, choosing appropriate memory storage modes, and profiling regularly with Metal System Trace. Whether you are building a game, a creative tool, or a data processing application, Metal provides the low-level access needed to squeeze maximum performance from Apple's GPU hardware.