Framework

Metal

Render advanced 3D graphics and perform data-parallel computations using graphics processors.

Overview

Graphics processors (GPUs) are designed to quickly render graphics and perform data-parallel calculations. Use the Metal framework when you need to communicate directly with the GPUs available on a device. Apps that render complex scenes or that perform advanced scientific calculations can use this power to achieve maximum performance. Such apps include:

  • Games that render sophisticated 3D environments

  • Video processing apps, like Final Cut Pro

  • Data-crunching apps, such as those used to perform scientific research

Metal works hand-in-hand with other frameworks that supplement its capability. Use MetalKit to simplify the task of getting your Metal content onscreen. Use Metal Performance Shaders to implement custom rendering functions or to take advantage of a large library of existing functions.

Many high level Apple frameworks are built on top of Metal to take advantage of its performance, including Core Image, SpriteKit, and SceneKit. Using one of these high-level frameworks shields you from the details of GPU programming, but writing custom Metal code enables you to achieve the highest level of performance.

Topics

Essentials

Basic Tasks and Concepts

Get familiar with Metal through a series of sample code projects.

Migrating OpenGL Code to Metal

Replace your app’s deprecated OpenGL code with Metal.

GPUs

Access GPU device(s) at runtime. GPUs form the basis of Metal development.

Getting the Default GPU

Select the system's default GPU device on which to run your Metal code.

GPU Selection in macOS

Select one or more GPUs on which to run your Metal code by considering GPU capabilities, power, or performance characteristics.

protocol MTLDevice

The Metal interface to a GPU that you use to draw graphics or do parallel computation.

GPU Features

Find feature information for specific GPU families.

Command Setup

Set up infrastructure to execute your custom code on the GPU.

Setting Up a Command Structure

Discover how Metal executes commands on a GPU.

Preparing Your Metal App to Run in the Background

Prepare your app to move into the background by pausing future GPU use and ensuring previous work is scheduled.

protocol MTLCommandQueue

A queue that organizes command buffers to be executed by a GPU.

protocol MTLCommandBuffer

A container that stores encoded commands for the GPU to execute.

protocol MTLCommandEncoder

An encoder that writes GPU commands into a command buffer.

Counter Sampling

Retrieve information about how the GPU executed your commands.

Rendering

Render graphics by issuing draw calls, and choose a presentation object if you're drawing to the screen.

Creating and Sampling Textures

Load image data into a texture and apply it to a quadrangle.

Calculating Primitive Visibility Using Depth Testing

Determine which pixels are visible in a scene by using a depth texture.

Customizing Render Pass Setup

Render into an offscreen texture by creating a custom render pass.

Generating Multiple Output Vertex Streams from One Input Stream

Render efficiently to multiple layers or viewports.

Render Pipelines

Specify how graphics primitives should be rendered.

class MTLRenderPassDescriptor

A group of render targets that hold the results of a render pass.

protocol MTLRenderCommandEncoder

The object to use for encoding commands for a render pass.

protocol MTLParallelRenderCommandEncoder

An object that splits up a single render pass so that it can be simultaneously encoded from multiple threads.

Model I/O

Specify precise locations within the textures associated with graphics processing.

Parallel Computation

Process arbitrary calculations in parallel on the GPU.

Processing a Texture in a Compute Function

Perform data-parallel computations on texture data.

Creating Threads and Threadgroups

Learn how Metal organizes compute-processing workloads.

Calculating Threadgroup and Grid Sizes

Calculate the optimum sizes for threadgroups and grids when dispatching compute-processing workloads.

class MTLComputePipelineDescriptor

An object used to customize how a new compute pipeline state object is compiled.

protocol MTLComputePipelineState

An object that contains a compiled compute pipeline.

protocol MTLComputeCommandEncoder

An object used to encode commands in a compute pass.

Presentation

Display Metal textures onscreen.

Drawable Objects

Obtain textures to draw into from drawable objects.

Shaders

Libraries

Organize your shaders into libraries.

Functions

Retrieve information about rendering and compute functions.

Resources

Create objects to hold GPU data.

Setting Resource Storage Modes

Set a storage mode that defines the memory location and access permissions of a resource.

Copying Data to a Private Resource

Use a blit command encoder to copy buffer or texture data to a private resource.

Synchronizing a Managed Resource

Synchronize the contents of a managed resource for the CPU or GPU.

Transferring Data Between Connected GPUs

Use high-speed connections between GPUs to transfer data quickly.

Reducing the Memory Footprint of Metal Apps

Learn best practices for using memory efficiently in iOS and tvOS.

protocol MTLResource

An allocation of memory that is accessible to a GPU.

protocol MTLBlitCommandEncoder

An encoder that encodes memory copying, filtering, and fill commands.

protocol MTLResourceStateCommandEncoder

An encoder that encodes commands that modify resource configurations.

Buffers

Create and manipulate unstructured GPU resources.

Textures

Create and manipulate structured GPU resources.

Indirect Command Buffers

Recoup encoding time by reusing commands, or create a GPU-driven rendering pipeline by generating commands on the GPU.

Heaps

Create a single allocation of memory from which you can suballocate resources.

Synchronization

Manage access to resources in your app to avoid data hazards.

Object Sizing and Positioning

Set the sizes and positions of many Metal objects.

struct MTLOrigin

The coordinates for the front upper-left corner of a region.

struct MTLRegion

The bounds for a subset of an object's elements.

struct MTLSize

The dimensions of an object.

typealias MTLCoordinate2D

A coordinate in the viewport.

func MTLCoordinate2DMake(Float, Float) -> MTLCoordinate2D

Returns a new 2D point with the specified coordinates.

Tools

Developing Metal Apps that Run in Simulator

Prototype and test your Metal apps in Simulator.

Supporting Simulator in a Metal App

Modify Metal Apps to Run in Simulator.

Frame Capture Debugging Tools

Analyze and optimize your app performance at runtime.

Using Metal System Trace in Instruments to Profile Your App

Smooth out your frame rate by checking for issues in your app's CPU and GPU utilization.

Optimizing Performance with the GPU Counters Instrument

Examine your app's use of GPU resources in Instruments, and tune your app as needed.

GPU Programming Techniques

Learn a variety of strategies for executing code efficiently on GPUs, and experiment with their companion sample code.

Rendering a Scene with Forward Plus Lighting Using Tile Shaders

Implement a forward plus renderer using the latest features on Apple GPUs.

Rendering a Scene with Deferred Lighting

Implement a deferred lighting renderer that takes advantage of unique Metal features.

Rendering Reflections with Fewer Render Passes

Use layer selection to reduce the number of render passes needed to generate an environment map.

Using Function Specialization to Build Pipeline Variants

Create pipelines for different levels of detail from a common shader source.

Rendering Terrain Dynamically with Argument Buffers

Use argument buffers to render terrain in real time with a GPU-driven pipeline.

Mixing Metal and OpenGL Rendering in a View

Draw with Metal and OpenGL in the same view using an interoperable texture.

Modern Rendering with Metal

Use advanced Metal features such as Indirect Command Buffers, Sparse Textures, and Variable Rate Rasterization to implement modern rendering algorithms.

See Also