IN THIS ARTICLE
Debugging UI Canvases
You can use the following console commands and console variables to display debug information for the UI when your game is running.
ui_DisplayCanvasData
Displays canvas data for enabled or loaded canvases.
| Value | Description |
|---|---|
| 0 | Off. |
| 1 | Displays a line of information for each loaded canvas. |
| 2 | Displays information only for canvases that are enabled. |
The following example displays data for five loaded UI canvases.
The following table describes each column.
| Column | Description |
|---|---|
| NN | The index number of the canvas in the list. The canvases are listed in the order that they’re drawn in. |
| Name | The leaf canvas name. |
| En | Whether the canvas is enabled. |
| Po | Whether the canvas accepts positional inputs (for example, mouse input). |
| Na | Whether the canvas has navigation enabled. |
| DrawOrder | The draw order, which is used to sort the list of loaded canvases. |
| nElem | The number of UI elements in the canvas. |
| nEnab | The number of enabled UI elements in the canvas. If a parent isn’t enabled, the element isn’t counted. |
| nRend | The number of enabled renderable elements in the canvas (how many images, text and particle effects are being rendered). |
| nRCtl | The number of enabled “render control” elements in the canvas (masks and faders). |
| nImg | The number of enabled UI elements with UiImageComponents. |
| nText | The number of enabled UI elements with UiTextComponents. |
| nMask | The number of enabled UI elements with UiMaskComponents. |
| nFadr | The number of enabled UI elements with UiFaderComponents. |
| nIntr | The number of enabled UI elements with interactable components (Button, Slider, TextInput, and so on). |
| nUpdt | Number of enabled UI elements with components that listen for updates (that is, that potentially do something every frame). |
| ActiveInt | The name of the active interactable on this canvas (if any). |
| HoverInt | The name of the current hover interactable on this canvas (if any). |
ui_DisplayDrawCallData
Displays the number of draw calls used to render UI canvases. This variable is useful for performance tuning and debugging.
| Value | Description |
|---|---|
| 0 | Turns off the display. |
| 1 | Turns on the display. |
The following example data shows draw call information for four UI canvases.
The following table describes each column.
| Column | Description |
|---|---|
| NN | The index number of the canvas in the list. The canvases are listed in the order that they’re drawn in. |
| Canvas name | The leaf canvas name. |
| nDraw | The number of draw calls. |
| nPrim | The number of primitives (for example, images and text strings). |
| nTris | The number of triangles rendered for the UI. |
| nMask | The number of mask render nodes in the render graph. |
| nRTs | The number of render target render nodes in the render graph. |
| nUTex | The number of unique textures being rendered in the canvas in this frame. |
| XMask | The number of draw calls caused by the use of masks. One mask can cause up to four extra draw calls. |
| XRT | The number of draw calls caused by render targets. |
| XBlnd | The number of draw calls caused by a change in blend mode. |
| XSrgb | The number of draw calls caused by a change in Srgb write. This data point appears only for render targets (for example, playing video). |
| XMaxV | The number of draw calls caused by a render node that requires more than 65536 vertices or 16384 quads. This case is uncommon. For example, more than 16000 characters of text would be required for a value to appear. |
| XTex | The number of draw calls that occur when the shader supported maximum of 16 textures is reached. To reduce the number of these calls, you can use a texture atlas. For more information, see Using Texture Atlases. |
ui_DisplayElemBounds
This console command displays an overlay on the screen that shows the rectangles of elements. By default, it shows the rectangular bounds of every UI element for each enabled UI canvas.
If you have several enabled UI canvases and want to see the rectangular bounds for only one canvas, use the ui_DisplayElemBoundsCanvasIndex console variable. To use the ui_DisplayElemBoundsCanvasIndex console variable, specify the index of the canvas whose bounds you want to display. To find the index for an enabled canvas, use the ui_DisplayCanvasData 2 setting.
The following example shows the rectangular bounds of nested scrollboxes.
ui_DisplayTextureData
Displays the textures that the UI is using.
The display shows the dimensions, data size, texture format, and pathname of each texture that the UI system is using in the current frame. The textures are sorted in descending order by the amount of memory that they use.
The following example shows data for 13 unique textures in the current frame.
ui_ReportDrawCalls
Writes a report of draw calls to a log file.
The command output displays the location of the log file, as in the following example.
The log file is written to drawcallreport.txt in the log directory.
The log file lists all of the draw calls for each enabled canvas. The report can be useful for determining how to reduce the number of draw calls.
For more information, see Using Texture Atlases to Reduce UI Draw Calls.