“This is the 16th day of my participation in the Gwen Challenge in November. Check out the details: The Last Gwen Challenge in 2021.”
An overview of the
To understand how your computer is running your App or debugging problems, you usually use a debugger. Traditional debuggers work by suspending a thread, but don’t work well with Metal-based apps. Xcode provides a debugger specifically for Metal through a frame capture workflow.
To use the Metal debugger to debug the Metal App, you need to capture a single animation frame and examine the App’s command to generate that frame.
In this article, you’ll run the Sample Metal Framework’s Rendering Pipeline Rendering primitives through Xcode’s Metal debugger to see how to check Metal App at runtime.
Enable the Metal debugger in the Xcode project
To debug the shader source code, you need to change the Metal compiler option in the build Settings. Set Debug under Produce debugging information to Yes, include source code, and set Release to NO.
Capture a frame
The Metal Debugger needs to be used in conjunction with Xcode’s Metal frame capture function. To use the Metal Debugger, first use the following steps to capture frames.
Build and run “Metal Framework’s Rendering Pipeline Renderer”, App displays a triangle.
With the App running, click the camera icon on the Xcode Debug toolbar:
View drawing call
The Metal frame of the rendering pipeline rendering primitives in the App called drawPrimitives (type: vertexStart: vertexCount:) to draw a triangle. During debugging, Xcode captures this draw call and other function calls and displays them in the Debug navigator, as shown below:
If the wrong location or color value is rendered, more information can be obtained from the captured frames to determine the cause.
The call under the MyRenderEncoder group is the command executed by Metal to create a triangle. Xcode logs calls, such as commands to set viewports, render pipeline states, vertex function parameters, and draw triangles. The command invocation is selected by clicking an item under the group.
In the main view, the details of the draw call are divided into several categories :Vertex, Fragment, and Attachment.
Each represents a phase of the draw call that can be analyzed in more detail to find out the cause of the problem.
Check vertices in geometry viewer
The vertex stage displays a set of vertices that correspond to primitives in App, also known as grids or geometries. To visually check for any problems with this data, double-click on the geometry.
Xcode renders the wireframes of the vertex phase output in the Geometry viewer. Below it, Xcode lists the same data in a table. Click on a vertex in the wireframes, and Xcode selects its row in the table.
By checking vertex information in this way, you can visually and digitally verify that the vertex output is correct.
If there are misplaced vertices on the screen, the error may be in the data provided to the vertex function. Bound Resources also lists inputs for the vertex phase, checking for any differences by using the left navigation in the palette.
See the input for the vertex functions listed at the top of Xcode.
Double-click the first vertex buffer, and Xcode displays the contents of the buffer in a table.
Each line identifies a vertex, including its position and color. Xcode renders a color preview to the right of the vertex number color data. If the table reflects undesired values, code or other resources for the vertex data in the App need to be adjusted to resolve the problem.
View vertex functions in the shader debugger
If one or more vertices in your App are incorrectly positioned or colored, the vertex shader code may be wrong. To determine the cause, turn on the vertex function in the shader debugger using the following steps: Select a vertex (marked by annotation 1 in the figure below) and click the Debug button (marked by annotation 2).
After that, Xcode displays the source code for the vertex function in the shader debugger.
Make sure the desired shader code is open; if not, it indicates that the wrong render pipe was used or configured incorrectly.
Next to each line of code, the shader debugger displays the values calculated and stored by the GPU as it executes the line.
By doing this, you can compare the results of all vertex function calls in the same frame. If an inconsistency is found, it indicates an error in the shader code or input data.
View the chip functions in the shader debugger
You can also see how the slice function handles a particular fragment. By looking at the attachments displayed in the Xcode auxiliary editor, you can see how each line of code in the slice shader determines the output color of the pixel.
Click and hold the mouse until Xcode displays the target crosshair, then move the mouse to select a pixel.
Click the “Debug” button.
Xcode opens the chip function in the shader debugger and displays the computed pixel value after the line of code.
Make sure you open the desired shader code. If not, you may have used the wrong render pipe or configured the render pipe incorrectly.
Click the dot to the right of the calculated value, marked with a 1 in the figure below. Xcode displays the pixel color, as indicated by label 2 in the figure below.
If the function has more than one line of code, you can examine other lines in a similar way to see how each line affects the output pixel color.
Metal provides many other great tools that you can use to debug and optimize your App’s performance and power consumption.
conclusion
This article introduces the use of Xcode’s Metal Debugger tool to step through the various states of App execution on the GPU. From Xcode configuration, to how to single step debugging have done a detailed explanation, and in the key links with graphic description, convenient to help you quickly start.
Download the sample code for this article