This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

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.

ValueDescription
0Off.
1Displays a line of information for each loaded canvas.
2Displays information only for canvases that are enabled.

The following example displays data for five loaded UI canvases.

Canvas data for five loaded UI canvases.

The following table describes each column.

ColumnDescription
NNThe index number of the canvas in the list. The canvases are listed in the order that they’re drawn in.
NameThe leaf canvas name.
EnWhether the canvas is enabled.
PoWhether the canvas accepts positional inputs (for example, mouse input).
NaWhether the canvas has navigation enabled.
DrawOrderThe draw order, which is used to sort the list of loaded canvases.
nElemThe number of UI elements in the canvas.
nEnabThe number of enabled UI elements in the canvas. If a parent isn’t enabled, the element isn’t counted.
nRendThe number of enabled renderable elements in the canvas (how many images, text and particle effects are being rendered).
nRCtlThe number of enabled “render control” elements in the canvas (masks and faders).
nImgThe number of enabled UI elements with UiImageComponents.
nTextThe number of enabled UI elements with UiTextComponents.
nMaskThe number of enabled UI elements with UiMaskComponents.
nFadrThe number of enabled UI elements with UiFaderComponents.
nIntrThe number of enabled UI elements with interactable components (Button, Slider, TextInput, and so on).
nUpdtNumber of enabled UI elements with components that listen for updates (that is, that potentially do something every frame).
ActiveIntThe name of the active interactable on this canvas (if any).
HoverIntThe 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.

ValueDescription
0Turns off the display.
1Turns on the display.

The following example data shows draw call information for four UI canvases.

Draw call information for four UI canvases.

The following table describes each column.

ColumnDescription
NNThe index number of the canvas in the list. The canvases are listed in the order that they’re drawn in.
Canvas nameThe leaf canvas name.
nDrawThe number of draw calls.
nPrimThe number of primitives (for example, images and text strings).
nTrisThe number of triangles rendered for the UI.
nMaskThe number of mask render nodes in the render graph.
nRTsThe number of render target render nodes in the render graph.
nUTexThe number of unique textures being rendered in the canvas in this frame.
XMaskThe number of draw calls caused by the use of masks. One mask can cause up to four extra draw calls.
XRTThe number of draw calls caused by render targets.
XBlndThe number of draw calls caused by a change in blend mode.
XSrgbThe number of draw calls caused by a change in Srgb write. This data point appears only for render targets (for example, playing video).
XMaxVThe 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.
XTexThe 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.

Rectangular bounds displayed for 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.

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.

Entering the ui_ReportDrawCalls command.

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.