MTKView
A specialized view that creates, configures, and displays Metal objects.
Declaration
@MainActor class MTKViewOverview
The MTKView class provides a default implementation of a Metal-aware view that you can use to render graphics using Metal and display them onscreen. When asked, the view provides a MTLRenderPassDescriptor object that points at a texture for you to render new contents into. Optionally, an MTKView can create depth and stencil textures for you and any intermediate textures needed for antialiasing. The view uses a CAMetalLayer to manage the Metal drawable objects.
The view requires a MTLDevice object to manage the Metal objects it creates for you. You must set the device property and, optionally, modify the view’s drawable properties before drawing.
Configuring the Drawing Behavior
The MTKView class supports three drawing modes:
Timed updates: The view redraws its contents based on an internal timer. In this case, which is the default behavior, both isPaused and enableSetNeedsDisplay are set to false. Use this mode for games and other animated content that’s regularly updated.
Draw notifications: The view redraws itself when something invalidates its contents, usually because of a call to setNeedsDisplay() or some other view-related behavior. In this case, set isPaused and enableSetNeedsDisplay to true. Use this mode for apps with a more traditional workflow, where updates happen when data changes, but not on a regular timed interval.
Explicit drawing: The view redraws its contents only when you explicitly call the draw() method. In this case, set isPaused to true and enableSetNeedsDisplay to false. Use this mode to create your own custom workflow.
Drawing the View’s Contents
Regardless of drawing mode, when the view needs to update its contents, it calls the draw(_:) method when that method has been overridden by a subclass, or draw(in:) on the view’s delegate if the subclass doesn’t override it. You should either subclass MTKView or provide a delegate, but not both.
In your drawing method, you obtain a render pass descriptor from the view, render into it, and then present the associated drawable.
Obtaining a Drawable from a MetalKit View
Each MTKView is backed by a CAMetalLayer. In your renderer, implement the MTKViewDelegate protocol to interact with a MetalKit view. Call the MetalKit view’s currentRenderPassDescriptor property to obtain a render pass descriptor configured for the current frame:
When you read this property, Core Animation implicitly obtains a drawable for the current frame and stores it in the currentDrawable property. It then configures a render pass descriptor to draw into that drawable, including any depth, stencil, and antialiasing textures as necessary. The view configures this render pass using the default store and load actions. You can adjust the descriptor further before using it to create a MTLRenderCommandEncoder.
Obtain drawables as late as possible; preferably, immediately before encoding your onscreen render pass.
Registering the Drawable’s Presentation
After rendering the contents, you must present the drawable to update the view’s contents. The most convenient way to present the content is to call the present(_:) method on the command buffer. Then, call the commit() method to submit the command buffer to a GPU:
When a command queue schedules a command buffer for execution, the drawable tracks all render or write requests on itself in that command buffer. The operating system doesn’t present the drawable onscreen until the commands have finished executing. By asking the command buffer to present the drawable, you guarantee that presentation happens after the command queue has scheduled this command buffer. Don’t wait for the command buffer to finish executing before registering the drawable’s presentation.
Topics
Creating a View
Configuring the Delegate
Configuring the Metal Device
Configuring the Color Render Target
colorPixelFormatcolorspaceframebufferOnlydrawableSizepreferredDrawableSizeautoResizeDrawableclearColor
Configuring the Render Target Properties
Configuring Multisampling
Retrieving Render Target Information
currentRenderPassDescriptorcurrentDrawabledepthStencilTexturedepthStencilStorageModemultisampleColorTexture