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 paused and enableSetNeedsDisplay are automatically set to NO.

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

  3. The third mode invokes a redraw when the draw method is explicitly called. In this case, paused must be set to YES and enableSetNeedsDisplay must be set to NO.

For all of these drawing modes, when a redraw is requested, either drawRect: from a subclassed instance of the view is called, or drawInMTKView: 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 presentDrawable: 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

initWithCoder:

Initializes a view from data in a given unarchiver.

initWithFrame:device:

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

Delegate

delegate

The view’s delegate.

Device

device

The device used to create Metal objects.

Configuring the Render Target Properties

clearColor

The color clear value used to generate the currentRenderPassDescriptor object.

clearDepth

The depth clear value used to generate the currentRenderPassDescriptor object.

clearStencil

The stencil clear value used to generate the currentRenderPassDescriptor object.

colorPixelFormat

The color pixel format for the current drawable's texture.

depthStencilPixelFormat

The format used to generate the depthStencilTexture object.

sampleCount

The sample count used to generate the multisampleColorTexture object.

colorspace

The color space of the rendered content.

Generated Render Target Objects

currentRenderPassDescriptor

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

depthStencilTexture

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

multisampleColorTexture

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

Configuring and Querying the Frame Rate

preferredFramesPerSecond

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

Controlling Frame Updates

paused

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

Drawing Your View’s Contents

enableSetNeedsDisplay

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

draw

Redraws the view’s contents immediately.

Managing Your Render Target

autoResizeDrawable

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

currentDrawable

The drawable to be used for the current frame.

drawableSize

The current size of drawable textures.

framebufferOnly

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

presentsWithTransaction

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

Relationships

Inherits From

See Also

View Management

MTKViewDelegate

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