Article

Viewing Your Meshes with the Geometry Viewer

Find problems in your app's vertex function by pausing your app at any time, and viewing the current geometry from an angle you choose.

Overview

Use the geometry viewer to see a wireframe of the geometry that your app rendered in the captured frame. Using the mouse and touch gestures, you can view the geometry at different angles to check for issues. When you click individual primitives to select them, Xcode shows you the values of its vertices in a tabular view. In addition, you can open the selected primitive in the shader debugger to make changes to your vertex function and see the results live.

Capture a Frame

The geometry viewer works in conjunction with Xcode's Metal frame capture. Build and run your project, then click the camera button on Xcode's debugging toolbar.

Screenshot of the camera button marked by a callout on Xcode's debug bar.

For more information about frame capture, see Frame Capture Debugging Tools.

Select a Draw Call

When Xcode finishes capturing, it halts your app and displays the frame's call history in the Debug navigator. From the call list, expand your render command encoder and select a draw call.

Screenshot showing the open disclosure triangle next to a render command encoder in the API call list, with a draw call selected and marked by a callout further down in the call hierarchy.

Open the Geometry Viewer

When you select a draw call, Xcode shows the draw's bound resources in center pane. In Vertex resources, Xcode exposes the geometry that resulted from this draw call. To view it, double-click Geometry.

Screenshot showing the Geometry option in the Bound Resources list.

Xcode shows the draw call's geometry in the center pane.

Screenshot showing the geometry of the example draw call displayed in the center pane.

View Your Geometry From Different Angles

Attain a new perspective in the geometry wireframe using the mouse and trackpad gestures. This enables you to zoom in to a specific area to check for erroneous geometry, or extraneous geometry that may initially be out of sight.

Screenshot showing the draw's geometry from a new angle after attaining a new viewing perspective using trackpad gestures.

Inspect Vertex Values

When a primitive is misplaced or misshaped, it's possible the issue lies in the data you're passing to the vertex function. Look to the variables view to ensure the input and output to your vertex function is correct.

  1. Select a primitive in Xcode's center pane.

  2. Xcode fills the variables view below the primitive with the primitive's vertex positions.

Screenshot showing the variables view which is positioned just under the displayed geometry in the center pane.

If your vertex function has multiple outputs, refer to the additional columns to the right of position.

Inspect Your Vertex Function in the Shader Debugger

Some of the geometry may be misplaced or have values that are obviously incorrect. To consider whether the issue is mistaken shader code, debug your vertex function using the shader debugger. In the wireframe view, select a primitive that's misplaced or misshaped and click Debug.

Screenshot of the Debug button marked by a callout out in geometry viewer.

The vertex shader that calculated the unexpected value shows in Xcode's center pane. To discover the cause of the problem, step through each line of code and inspect its values on the right pane until the anomaly is visible.

Screenshot of the app's vertex function with the calculated values marked by a callout in the right sidebar.

Update Your Vertex Shader Live

If you discover a problem in your vertex function, you can adjust the code and update the captured frame live to ensure you solved the issue. When you change a line of code, Xcode enables the Refresh button.

Screenshot of the shader debugger bar with the Refresh button marked by a callout.

Click Refresh to update the frame with the new vertex shader, and Xcode refreshes its geometry view according to your change.

See Also

Vertex Data

class MTLVertexDescriptor

An object that describes how vertex data is organized and mapped to a vertex function.

class MTLVertexAttribute

An object that represents an attribute of a vertex function.

class MTLVertexAttributeDescriptor

An object that determines how attribute data is stored in memory and how it is mapped to the arguments of a vertex function.

class MTLVertexBufferLayoutDescriptor

An object that configures how vertex data and attributes are fetched by a vertex function.