Metal Tutorial with Swift 3 Part 1: Getting Started

Andriy Kharchyshyn

Update: This tutorial has been updated for Xcode 8.2 and Swift 3.

Learn how to use Apple’s new API for GPU-accelerated 3D graphics: Metal!

In iOS 8, Apple released their own API for GPU-accelerated 3D graphics: Metal.

Metal is similar to OpenGL ES, in that it is a low-level API for interacting with 3D graphics hardware.

The difference is that Metal is not cross-platform. Instead, it is designed to be extremely efficient with Apple hardware, offering improved speed and low overhead compared to using OpenGL ES.

In this tutorial, you’ll get some hands-on experience using Metal and Swift to create a bare-bones app: drawing a simple triangle. In the process, you’ll learn about some of the most important classes in Metal, such as devices, command queues, and more.

This tutorial is designed so that anyone can go through it, regardless of your 3D graphics background — however, things will move along fairly quickly. If you do have some prior 3D programming or OpenGL experience, you will find things much easier, as many of the concepts you’re already familiar with apply to Metal.

This tutorial assumes you are familiar with Swift. If you are new to Swift, check out some of our Swift tutorials first.

Note: Metal apps do not run on the iOS simulator; they require a device with an Apple A7 chip or later. So to go through this tutorial, you will need an A7 device or newer.

Metal vs. Sprite Kit, Scene Kit, or Unity

1_Metal_vs_3

Before we get started, I wanted to discuss how Metal compares to higher-level frameworks like Sprite Kit, Scene Kit, or Unity.

Metal is a low-level 3D graphics API, similar to OpenGL ES, but with lower overhead. It is a very thin layer above the GPU, so doing just about anything, such as rendering a sprite or a 3D model to the screen, requires you to write all of the code to do this. The tradeoff is you have full power and control.

Higher level game frameworks like SpriteKit, SceneKit, or Unity are built on top of a lower-level 3D graphics API like Metal or OpenGL ES. They provide much of the boilerplate code you normally need to write in a game, such as rendering a sprite or 3D model to the screen.

2_Boxes

If all you’re trying to do is make a game, most of the time I’d recommend you use a higher level game framework like Sprite Kit, Scene Kit, or Unity because it will make your life much easier. If this sounds like you, we have tons of tutorials to help you get started with Apple Game Frameworks or Unity.

However, there are still two really good reasons to learn Metal:

  1. Push the hardware to its limits: Since Metal is at such a low level, it allows you to really push the hardware to its limits and have full control over how your game works.
  2. It’s a great learning experience: Learning Metal teaches you a lot about 3D graphics, writing your own game engine, and how higher level game frameworks work.

If either of these sound like good reasons to you, keep reading!

Metal vs OpenGL ES

3_Metal_vs_opengles

OpenGL ES has been designed to be cross-platform. That means you can write C++ OpenGL ES code, and most of the time (with some small modifications) you can run it on other platforms, such as Android.

Apple realized that although the cross-platform support of OpenGL ES was nice, it was missing something fundamental to how Apple designs its products: the famous Apple integration of the operating system, hardware, and software as a complete package.

So Apple took a clean-room approach to see what it would look like if they were to design a graphics API specifically for their hardware with the goal of being extremely low overhead and performant, and supporting the latest and greatest features.

The result was Metal, which can provide up to 10x the number of draw calls for your application compared to OpenGL ES. This can result in some amazing effects, like you may remember from the Zen Garden example in the WWDC 2014 keynote.

Let’s dig right in and see some Metal code!

Getting Started

Xcode’s iOS Game template comes with a Metal option, but you won’t be choosing that here. This is because I want to show you how to put together a Metal app from scratch, so you can understand every step of the process.

Open Xcode and make a new project with the iOS\Application\Single View Application template. Enter HelloMetal for the ProductName, set the Language to Swift, and set Devices to Universal. Click Next, choose a directory, and click Create.

There are seven steps required to set up Metal so you can begin rendering:

  1. Create a MTLDevice
  2. Create a CAMetalLayer
  3. Create a Vertex Buffer
  4. Create a Vertex Shader
  5. Create a Fragment Shader
  6. Create a Render Pipeline
  7. Create a Command Queue

Let’s go through them one at a time.

1) Create a MTLDevice

The first thing you need to do is get a reference to a MTLDevice.

You can think of a MTLDevice as your direct connection to the GPU. You will create all the other Metal objects you need (like command queues, buffers, and textures) using this MTLDevice.

To do this, open ViewController.swift and add this import to the top of the file:

import Metal

This imports the Metal framework so that you can use Metal classes such as MTLDevice inside this file.

Note: If you get a compiler error at this point, make sure you set the app to target your Metal-compatible iOS device. As mentioned earlier, Metal is not supported on the iOS Simulator at the time of writing this tutorial.

Next, add this property to the ViewController class:

var device: MTLDevice!

You are going to initialize this property in viewDidLoad() rather than in an initializer, so it has to be an optional. Since you know you’re definitely going to initialize it before you use it, you mark it as an implicitly unwrapped optional for convenience purposes.

Finally, add this line to the end of viewDidLoad():

device = MTLCreateSystemDefaultDevice()

This function returns a references to the default MTLDevice your code should use.

2) Create a CAMetalLayer

In iOS, everything you see on screen is backed by a CALayer. There are subclasses of CALayers for different effects, such as gradient layers, shape layers, replicator layers, and more.

If you want to draw something on the screen with Metal, you need to use a special subclass of CALayer called CAMetalLayer. You’ll add one of these to your view controller.

First add this new property to the class:

var metalLayer: CAMetalLayer!

This will store a handy reference to your new layer.

Next, add this code to the end of viewDidLoad():

metalLayer = CAMetalLayer()          // 1
metalLayer.device = device           // 2
metalLayer.pixelFormat = .bgra8Unorm // 3
metalLayer.framebufferOnly = true    // 4
metalLayer.frame = view.layer.frame  // 5
view.layer.addSublayer(metalLayer)   // 6

Going over this line-by-line:

  1. You first create a new CAMetalLayer.
  2. You must specify the MTLDevice that the layer should use. You simply set this to the device you obtained earlier.
  3. You set the pixel format to bgra8Unorm, which is a fancy way of saying “8 bytes for Blue, Green, Red, and Alpha, in that order — with normalized values between 0 and 1.” This is one of only two possible formats to use for a CAMetalLayer, so normally you’d just leave this as-is.
  4. Apple encourages you to set framebufferOnly to true for performance reasons unless you need to sample from the textures generated for this layer, or if you need to enable compute kernels on the layer drawable texture. Most of the time, you don’t need to do this.
  5. You set the frame of the layer to match the frame of the view.
  6. Finally, you add the layer as a sublayer of the view’s main layer.

3) Create a Vertex Buffer

Everything in Metal is a triangle. In this app, you’re just going to draw one triangle, but even complex 3D shapes can be decomposed into a series of triangles.

In Metal, the default coordinate system is the normalized coordinate system, which means that by default you are looking at a 2x2x1 cube centered at (0, 0, 0.5).

If you consider the Z=0 plain, then (-1, -1, 0) is the lower left, (0, 0, 0) is the center, and (1, 1, 0) is the upper right. In this tutorial, you want to draw a triangle with these three points:

4_vertices

You’ll have to create a buffer for this. Add the following constant property to your class:

let vertexData:[Float] = [
  0.0, 1.0, 0.0,
  -1.0, -1.0, 0.0,
  1.0, -1.0, 0.0]

This creates an array of floats on the CPU. You need to send this data to the GPU by moving it to something called a MTLBuffer.

Add another new property for this:

var vertexBuffer: MTLBuffer!

Then add this code to the end of viewDidLoad():

let dataSize = vertexData.count * MemoryLayout.size(ofValue: vertexData[0]) // 1
vertexBuffer = device.makeBuffer(bytes: vertexData, length: dataSize, options: []) // 2

Taking it comment by comment:

  1. You need to get the size of the vertex data in bytes. You do this by multiplying the size of the first element by the count of elements in the array.
  2. You call makeBuffer(bytes:length:options:) on the MTLDevice you created earlier to create a new buffer on the GPU, passing in the data from the CPU. You pass empty array for default configuration.

4) Create a Vertex Shader

The vertices you created in the previous section will become the input to a little program you will write called a vertex shader.

A vertex shader is simply a tiny program that runs on the GPU, written in a C++-like language called the Metal Shading Language.

A vertex shader is called once per vertex, and its job is to take that vertex’s information, such as position and possibly other information such as color or texture coordinate, and return a potentially modified position and possibly other data.

To keep things simple, your simple vertex shader will return the same position as the position passed in.

5_matrix

The easiest way to understand vertex shaders is to see it yourself. Go to File\New\File, choose iOS\Source\Metal File, and click Next. Enter Shaders.metal for the filename and click Create.

Note: In Metal, you can include multiple shaders in a single Metal file. You can also split your shaders across multiple Metal files if you would like, as Metal will load shaders from any Metal file included in your project.

Add the following code to the bottom of Shaders.metal:

vertex float4 basic_vertex(                           // 1
  const device packed_float3* vertex_array [[ buffer(0) ]], // 2
  unsigned int vid [[ vertex_id ]]) {                 // 3
  return float4(vertex_array[vid], 1.0);              // 4
}

Here’s what’s going on in the code above:

  1. All vertex shaders must begin with the keyword vertex. The function must return (at least) the final position of the vertex – you do so here by indicating float4 (a vector of 4 floats). You then give the name of the vertex shader; you will look up the shader later using this name.
  2. The first parameter a pointer to an an array of packed_float3 (a packed vector of 3 floats) – i.e. the position of each vertex.

    The [[ ... ]] syntax is used to declare attributes which can be used to specify additional information such as resource locations, shader inputs, and built-in variables. Here you mark this parameter with [[ buffer(0) ]], to indicate that this parameter will be populated by the first buffer of data that you send to your vertex shader from your Metal code.

  3. The vertex shader will also take a special parameter with the vertex_id attribute, which means it will be filled in with the index of this particular vertex inside the vertex array.
  4. Here you look up the position inside the vertex array based on the vertex id and return that. You also convert the vector to a float4, where the final value is 1.0 (long story short, this is required for 3D math purposes).

5) Create a Fragment Shader

After the vertex shader completes, another shader is called for each fragment (think pixel) on the screen: the fragment shader.

The fragment shader gets its input values by interpolating the output values from the vertex shader. For example, consider the fragment between the bottom two vertices of the triangle:

6_points

The input value for this fragment will be a 50/50 blend of the output value of the bottom two vertices.

The job of a fragment shader is to return the final color for each fragment. To keep things simple, you will make each fragment white.

Add the following code to the bottom of Shaders.metal:

fragment half4 basic_fragment() { // 1
  return half4(1.0);              // 2
}

Line-by-line:

  1. All fragment shaders must begin with the keyword fragment. The function must return (at least) the final color of the fragment. You do so here by indicating half4 (a 4-component color value RGBA). Note that half4 is more memory efficient than float4 because you are writing to less GPU memory.
  2. Here you return (1, 1, 1, 1) for the color (which is white).

6) Create a Render Pipeline

Now that you’ve created a vertex and fragment shader, you need to combine them (along with some other configuration data) into a special object called the render pipeline.

One of the cool things about Metal is that the shaders are precompiled, and the render pipeline configuration is compiled after you first set it up. This makes everything extremely efficient.

First add a new property to ViewController.swift:

var pipelineState: MTLRenderPipelineState!

This will keep track of the compiled render pipeline you are about to create.

Next, add the following code to the end of viewDidLoad():

// 1
let defaultLibrary = device.newDefaultLibrary()!
let fragmentProgram = defaultLibrary.makeFunction(name: "basic_fragment")
let vertexProgram = defaultLibrary.makeFunction(name: "basic_vertex")
    
// 2
let pipelineStateDescriptor = MTLRenderPipelineDescriptor()
pipelineStateDescriptor.vertexFunction = vertexProgram
pipelineStateDescriptor.fragmentFunction = fragmentProgram
pipelineStateDescriptor.colorAttachments[0].pixelFormat = .bgra8Unorm
    
// 3
pipelineState = try! device.makeRenderPipelineState(descriptor: pipelineStateDescriptor)

Taking it section by section:

  1. You can access any of the precompiled shaders included in your project through the MTLLibrary object you get by calling device.newDefaultLibrary()!. Then you can look up each shader by name.
  2. You set up your render pipeline configuration here. It contains the shaders you want to use, and the pixel format for the color attachment — i.e. the output buffer you are rendering to, which is the CAMetalLayer itself.
  3. Finally you compile the pipeline configuration into a pipeline state that is efficient to use here on out.

7) Create a Command Queue

The final one-time-setup step you need to do is to create a MTLCommandQueue.

Think of this as an ordered list of commands that you tell the GPU to execute, one at a time.

To create a command queue, simply add a new property:

var commandQueue: MTLCommandQueue!

Then add this line at the end of viewDidLoad():

commandQueue = device.makeCommandQueue()

Congrats – your one-time setup code is done!

Rendering the Triangle

Now it’s time to move on to the code that executes each frame, to render the triangle!

This is done in five steps:

  1. Create a Display Link
  2. Create a Render Pass Descriptor
  3. Create a Command Buffer
  4. Create a Render Command Encoder
  5. Commit your Command Buffer
Note: In theory, this app doesn’t actually need to render things once per frame, because the triangle doesn’t move after it’s drawn. However, most apps do have moving pieces, so you’ll do things this way to learn the process. This also gives a nice starting point for future tutorials.

1) Create a Display Link

You need a function to be called every time the device screen refreshes so you can redraw the screen.

On iOS, you do this with the handy CADisplayLink class. To use this, add a new property to the class:

var timer: CADisplayLink!

Initialize it at the end of viewDidLoad() as follows:

timer = CADisplayLink(target: self, selector: #selector(ViewController.gameloop))
timer.add(to: RunLoop.main, forMode: RunLoopMode.defaultRunLoopMode)

This sets up your code to call a method named gameloop() every time the screen refreshes.

Finally, add these stub methods to the class:

func render() {
  // TODO
}

func gameloop() {
  autoreleasepool {
    self.render()
  }
}

Here gameloop() simply calls render() each frame, which right now just has an empty implementation. Time to flesh this out.

2) Create a Render Pass Descriptor

The next step is to create a MTLRenderPassDescriptor, which is an object that configures which texture is being rendered to, what the clear color is, and a bit of other configuration.

Simply add these lines inside render():

guard let drawable = metalLayer?.nextDrawable() else { return }
let renderPassDescriptor = MTLRenderPassDescriptor()
renderPassDescriptor.colorAttachments[0].texture = drawable.texture
renderPassDescriptor.colorAttachments[0].loadAction = .clear
renderPassDescriptor.colorAttachments[0].clearColor = MTLClearColor(red: 0.0, green: 104.0/255.0, blue: 5.0/255.0, alpha: 1.0)

First you call nextDrawable() on the Metal layer you created earlier, which returns the texture you need to draw into in order for something to appear on the screen.

Next you configure the render pass descriptor to use that texture. You set the load action to Clear, which means “set the texture to the clear color before doing any drawing”, and you set the clear color to the green color we use on the site.

3) Create a Command Buffer

The next step is to create a command buffer. Think of this as the list of render commands that you wish to execute for this frame. The cool thing is nothing actually happens until you commit the command buffer, giving you fine-grained control over when things occur.

Creating a command buffer is easy. Simply add this line to the end of render():

let commandBuffer = commandQueue.makeCommandBuffer()

A command buffer contains one or more render commands. You’ll create one of these next.

4) Create a Render Command Encoder

To create a render command, you use a helper object called a render command encoder. To try this out, add these lines to the end of render():

let renderEncoder = commandBuffer.makeRenderCommandEncoder(descriptor: renderPassDescriptor)
renderEncoder.setRenderPipelineState(pipelineState)
renderEncoder.setVertexBuffer(vertexBuffer, offset: 0, at: 0)
renderEncoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3, instanceCount: 1)
renderEncoder.endEncoding()

Here you create a command encoder and specify the pipeline and vertex buffer you created earlier.

The most important part is the call to drawPrimitives(type:vertexStart:vertexCount:instanceCount:). Here you are telling the GPU to draw a set of triangles, based on the vertex buffer. Each triangle consists of three vertices, starting at index 0 inside the vertex buffer, and there is 1 triangle total.

When you’re done, you simply call endEncoding().

5) Commit your Command Buffer

The final step is to commit the command buffer. Add these lines to the end of render():

commandBuffer.present(drawable)
commandBuffer.commit()

The first line is needed to make sure the new texture is presented as soon as the drawing completes. Then you commit the transaction to send the task to the GPU.

Phew! That was a ton of code, but at long last you are done! Build and run the app and bask in your triangular glory:

The most beautiful triangle I've ever seen!

The most beautiful triangle I’ve ever seen!

Note: If your app crashes, make sure that you are running on an actual device (not the simulator) that has an A7 or better chip (an iPhone 5S, iPhone 6, iPhone 6 Plus, iPad Air, or iPad mini (2nd generation) at the time of writing).

Where to Go From Here?

Here is the final example project from this part of this Metal tutorial series.

You have learned a ton about the new Metal API! You now have an understanding of some of the most important concepts in Metal, such as shaders, devices, command buffers, pipelines, and more.

Next, check out part 2 of this series on moving to 3D.

Also, be sure to check out some great resources from Apple:

You also might enjoy the Beginning Metal course on our site, where we explain these same concepts in video form, but with even more detail.

I hope you enjoyed this tutorial, and if you have any comments or questions, please join the forum discussion below!

Andrew Kharchyshyn

I am an iOS developer. Mostly focused on OpenGL ES and SpriteKit. When not doing games, I'm most likely playing them or watching anime.

Other Items of Interest

Save time.
Learn more with our video courses.

raywenderlich.com Weekly

Sign up to receive the latest tutorials from raywenderlich.com each week, and receive a free epic-length tutorial as a bonus!

Advertise with Us!

PragmaConf 2016 Come check out Alt U

Our Books

Our Team

Video Team

... 20 total!

Swift Team

... 15 total!

iOS Team

... 44 total!

Android Team

... 14 total!

macOS Team

... 11 total!

Unity Team

... 11 total!

Articles Team

... 12 total!

Resident Authors Team

... 16 total!