Preparation

Before writing any Metal code, this page walks you through cloning the project, understanding its structure, and the key concepts behind Metal rendering.

Prerequisites

Before diving into Metal, it’s helpful to have a solid foundation in key concepts.

• Swift
  • Swift is the language used for iOS development, including Metal.
  • Resources: Swift Programming Language Book
• Graphics Fundamentals
  • Understanding how graphics work under the hood helps you optimize performance and troubleshoot issues.
  • Resources:
    • Learn OpenGL — Great for understanding the basics of rendering pipelines.
    • Scratchapixel — In-depth tutorials on graphics algorithms.
• Metal API
  • Metal is Apple’s low-level graphics framework, optimized for performance on Apple Silicon and GPUs. It abstracts hardware details while giving you fine-grained control over rendering pipelines.
    • Resources:
      • Metal Programming Guide — Official guide to Metal concepts and APIs.
      • Metal Shading Language Specification — The complete MSL language reference (PDF). Bookmark §2 (address spaces) and §5 (vertex/fragment attributes) — you’ll return to both constantly.
      • Metal Feature Set Tables — Per-device capability matrix: max texture size, buffer binding slots, supported pixel formats, and more.
• Useful other resources:
  • Metal by Example
  • Real-Time Rendering

Setting up the project

Clone the repository

git clone https://github.com/Fe0437/MetalTutorials.git

Launch Xcode and open the MetalTutorials.xcodeproj file to begin exploring the project structure and tutorials.

🔄 Switching between tutorials

To switch between tutorials, open MTMetalTutorialsApp.swift and modify the content view by changing the function call in the WindowGroup:

@main
struct MetalTutorialsApp: App {
    var body: some Scene {
        WindowGroup {
            // substitute here to choose the tutorial
            MT1ContentView()   // ← change to MT2ContentView(), MT3ContentView(), …
        }
    }
}

Each MTxContentView wires up the corresponding MTKView and renderer for that tutorial.

Each tutorial folder is self-contained and builds on the previous one. The Metal shader namespaces (MT1::, MT2::, MT3::) keep everything clearly separated.

How Metal works

The Metal rendering loop

To understand each tutorial, follow this basic Metal rendering loop pattern:

flowchart TD
    subgraph setup["One-time setup"]
        direction TB
        A([App launch]) --> B[/"Create MTLDevice\n— the GPU handle"/]
        B --> C[/"Create MTKView\n— the Metal-backed window"/]
        C --> D[/"Assign MTKViewDelegate\n— your renderer object"/]
        D --> E[/"Compile pipelines,\nallocate buffers & textures"/]
    end

    subgraph loop["Per-frame render loop  ↺"]
        direction TB
        F([draw called by MTKView]) --> G[/"new MTLCommandBuffer\n— records this frame"/]
        G --> H[/"new MTLRenderCommandEncoder\n— encodes draw calls"/]
        H --> I[["setVertexBuffer · setRenderPipelineState\n· drawPrimitives / drawIndexedPrimitives"]]
        I --> J[/"endEncoding"/]
        J --> K[/"present drawable\nthen commit"/]
    end

    setup --> loop
    K -.->|next frame| F

Understanding this loop before diving into the tutorials will make the code much easier to follow.

UIViewRepresentable pattern

sequenceDiagram
    participant SwiftUI
    participant MyMetalView as MyMetalView<br/>(UIViewRepresentable)
    participant MTRenderer as MTRenderer<br/>(MTKViewDelegate)
    participant MTKView

    SwiftUI->>MyMetalView: makeCoordinator()
    MyMetalView-->>SwiftUI: MTRenderer instance

    SwiftUI->>MyMetalView: makeUIView(context:)
    MyMetalView->>MTKView: init(frame:device:)
    MyMetalView->>MTKView: delegate = context.coordinator
    MyMetalView-->>SwiftUI: MTKView

    loop every frame
        MTKView->>MTRenderer: draw(in:)
    end

The tutorials use UIViewRepresentable to embed the MTKView (a UIKit class) into SwiftUI:

struct MyMetalView: UIViewRepresentable {
    typealias UIViewType = MTKView

    func makeUIView(context: Context) -> MTKView { … }
    func updateUIView(_ uiView: MTKView, context: Context) { }

    // the coordinator IS the renderer / MTKViewDelegate
    func makeCoordinator() -> MyRenderer { … }
}

The Coordinator pattern lets the renderer own the MTKView delegate without the view being recreated on every SwiftUI update.

Rendering fundamentals

The vocabulary you’ll see everywhere

Vertex — a single point in 3D space, bundled with extra attributes like a color, normal, or texture coordinate. A mesh is just a list of vertices (and usually an index list connecting them into triangles).

Triangle — the fundamental drawing primitive. Everything rendered is decomposed into triangles because they are always flat and cheap to rasterize.

Fragment — a candidate pixel produced during rasterization. Once a triangle is projected onto the screen, the GPU fills it with fragments — one per screen pixel covered — each carrying values interpolated from the three vertices.

Rasterization — the hardware step that converts a projected triangle into a grid of fragments. Metal handles this automatically between the vertex shader and the fragment shader; you don’t write rasterization code yourself.

Shader — a small program written in Metal Shading Language (MSL) that runs on the GPU. A vertex shader transforms each vertex’s position. A fragment shader decides the final color of each fragment.

Draw call — a CPU command that says “process this batch of vertices using this pipeline.” Every drawPrimitives or drawIndexedPrimitives call in the tutorials is one draw call.

Framebuffer / drawable — the image the GPU is currently writing into. When a frame is complete, Metal presents the drawable to the screen.

Coordinate spaces

Vertices travel through a chain of coordinate spaces before reaching the screen:

Model Space → World Space → View Space → Clip Space → NDC → Screen Space
              ↑              ↑             ↑
           model matrix   view matrix  projection matrix

The MVP matrix (Model × View × Projection) is combined on the CPU into one matrix. The vertex shader multiplies each vertex position by it once — collapsing three transforms into a single GPU multiply.

Metal object hierarchy

Every Metal object is created by something above it in this tree. The device represents the GPU and is the root of everything — nothing works without it.

MTLDevice                        ← represents the GPU
├── MTLLibrary                   ← compiled Metal shader library (.metallib)
│   └── MTLFunction              ← one vertex, fragment, or kernel function
├── MTLCommandQueue              ← persistent queue; submits frames to the GPU
│   └── MTLCommandBuffer         ← one frame's worth of recorded commands
│       ├── MTLRenderCommandEncoder    ← encodes draw calls for a render pass
│       ├── MTLComputeCommandEncoder   ← encodes GPU compute kernels
│       └── MTLBlitCommandEncoder      ← encodes copy/blit operations
├── MTLRenderPipelineState       ← compiled vertex + fragment pair (expensive)
├── MTLDepthStencilState         ← depth and stencil test configuration
├── MTLBuffer                    ← raw GPU memory (vertices, uniforms, indices…)
├── MTLTexture                   ← image data on the GPU
└── MTLHeap                      ← arena allocator for buffers and textures

Object lifetime and creation cost

Apple documentation reference

Every key Metal object used across these tutorials, with links to the official Apple docs.