Class

MTKView

A specialized view that creates, configures, and displays Metal objects.

Overview

The MTKView class simplifies the effort required to create a Metal drawing application by providing a default implementation of a Metal-aware view. A MTKView object provides a convenient way to manage a MTLRenderPassDescriptor object and its associated render target attachments on your application’s behalf. You simply draw into the view when its contents need to be updated.

The view requires a MTLDevice object so that it can create and manage Metal objects internally. Your app must set the device and, optionally, modify the view’s drawable properties before drawing. The MTKView class supports three drawing modes:

  1. The default mode automatically invokes a redraw based on an internal timer. In this case, both isPaused and enableSetNeedsDisplay are automatically set to false.

  2. The second mode invokes a redraw from a view notification, which is usually a call to setNeedsDisplay(). In this case, both isPaused and enableSetNeedsDisplay must be set to true.

  3. The third mode invokes a redraw when the draw() method is explicitly called. In this case, isPaused must be set to true and enableSetNeedsDisplay must be set to false.

For all of these drawing modes, when a redraw is requested, either draw(_:) from a subclassed instance of the view is called, or draw(in:) from the view’s delegate is called. You should either subclass MTKView or provide a delegate, but not both.

For each iteration of the draw loop, a new MTLRenderPassDescriptor object is made available when queried from currentRenderPassDescriptor. This object is created based on the configured render target properties and the currentDrawable object. The default store and load actions are used, and it is expected that the render pass descriptor be used when creating your onscreen MTLRenderCommandEncoder. Presentation is not handled by MTKView, it is your responsibility to call the MTLCommandBuffer object’s present(_:) method on the view’s current drawable.

For the best performance results, schedule your currentRenderPassDescriptor and currentDrawable calls as late as possible, relative to other per-frame CPU work.

Topics

Initialization

init(coder: NSCoder)

Initializes a view from data in a given unarchiver.

init(frame: CGRect, device: MTLDevice?)

Initializes a view with the specified frame rectangle and Metal device.

Delegate

var delegate: MTKViewDelegate?

The view’s delegate.

Device

var device: MTLDevice?

The device used to create Metal objects.

Configuring the Render Target Properties

var clearColor: MTLClearColor

The color clear value used to generate the currentRenderPassDescriptor object.

var clearDepth: Double

The depth clear value used to generate the currentRenderPassDescriptor object.

var clearStencil: UInt32

The stencil clear value used to generate the currentRenderPassDescriptor object.

var colorPixelFormat: MTLPixelFormat

The format for the currentDrawable object’s texture.

var sampleCount: Int

The sample count used to generate the multisampleColorTexture object.

Generated Render Target Objects

var currentRenderPassDescriptor: MTLRenderPassDescriptor?

A render pass descriptor generated from the drawable’s texture, the view’s buffers, and the view’s clear values.

var depthStencilTexture: MTLTexture?

A packed depth/stencil texture attached to the currentDrawable object’s texture.

var multisampleColorTexture: MTLTexture?

A multisample color sample texture resolved into the currentDrawable object’s texture.

Configuring and Querying the Frame Rate

var preferredFramesPerSecond: Int

The rate at which you want the view to redraw its contents.

Controlling Frame Updates

var isPaused: Bool

A Boolean value that indicates whether the draw loop is paused.

Drawing Your View’s Contents

var enableSetNeedsDisplay: Bool

A Boolean value that indicates whether the view responds to setNeedsDisplay().

func draw()

Redraws the view’s contents immediately.

Managing Your Render Target

var autoResizeDrawable: Bool

A Boolean value that controls whether to resize the drawable as the view changes size.

var currentDrawable: CAMetalDrawable?

The drawable to be used for the current frame.

var drawableSize: CGSize

The current size of drawable textures.

var framebufferOnly: Bool

A Boolean value that determines whether the drawable can be used for texture sampling or read/write operations.

var presentsWithTransaction: Bool

A Boolean value that determines whether the view presents its content using a Core Animation transaction.

See Also

View Management

protocol MTKViewDelegate

Methods for responding to a MetalKit view's drawing and resizing events.