2017-09-12 22:42:36 +02:00
<?xml version="1.0" encoding="UTF-8" ?>
2020-02-01 02:03:48 +01:00
<class name= "Performance" inherits= "Object" version= "4.0" >
2017-09-12 22:42:36 +02:00
<brief_description >
2019-06-26 15:57:13 +02:00
Exposes performance-related data.
2017-09-12 22:42:36 +02:00
</brief_description>
<description >
2019-06-22 01:04:47 +02:00
This class provides access to a number of different monitors related to performance, such as memory usage, draw calls, and FPS. These are the same as the values displayed in the [b]Monitor[/b] tab in the editor's [b]Debugger[/b] panel. By using the [method get_monitor] method of this class, you can access this data from your code.
2020-06-04 15:18:57 +02:00
You can add custom monitors using the [method add_custom_monitor] method. Custom monitors are available in [b]Monitor[/b] tab in the editor's [b]Debugger[/b] panel together with built-in monitors.
2019-06-22 01:04:47 +02:00
[b]Note:[/b] A few of these monitors are only available in debug mode and will always return 0 when used in a release build.
[b]Note:[/b] Many of these monitors are not updated in real-time, so there may be a short delay between changes.
2020-06-04 15:18:57 +02:00
[b]Note:[/b] Custom monitors do not support negative values. Negative values are clamped to 0.
2017-09-12 22:42:36 +02:00
</description>
<tutorials >
</tutorials>
<methods >
2020-06-04 15:18:57 +02:00
<method name= "add_custom_monitor" >
<return type= "void" >
</return>
<argument index= "0" name= "id" type= "StringName" >
</argument>
<argument index= "1" name= "callable" type= "Callable" >
</argument>
2019-09-24 19:45:03 +02:00
<argument index= "2" name= "arguments" type= "Array" default= "[]" >
2020-06-04 15:18:57 +02:00
</argument>
<description >
Adds a custom monitor with name same as id. You can specify the category of monitor using '/' in id. If there are more than one '/' then default category is used. Default category is "Custom".
2020-10-31 18:54:17 +01:00
[codeblocks]
[gdscript]
func _ready():
var monitor_value = Callable(self, "get_monitor_value")
# Adds monitor with name "MyName" to category "MyCategory".
Performance.add_custom_monitor("MyCategory/MyMonitor", monitor_value)
# Adds monitor with name "MyName" to category "Custom".
# Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so the code is valid.
Performance.add_custom_monitor("MyMonitor", monitor_value)
# Adds monitor with name "MyName" to category "Custom".
# Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so the code is valid.
Performance.add_custom_monitor("Custom/MyMonitor", monitor_value)
# Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom".
Performance.add_custom_monitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitor_value)
func get_monitor_value():
return randi() % 25
[/gdscript]
[csharp]
public override void _Ready()
{
var monitorValue = new Callable(this, nameof(GetMonitorValue));
// Adds monitor with name "MyName" to category "MyCategory".
Performance.AddCustomMonitor("MyCategory/MyMonitor", monitorValue);
// Adds monitor with name "MyName" to category "Custom".
// Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so the code is valid.
Performance.AddCustomMonitor("MyMonitor", monitorValue);
// Adds monitor with name "MyName" to category "Custom".
// Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so the code is valid.
Performance.AddCustomMonitor("Custom/MyMonitor", monitorValue);
// Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom".
Performance.AddCustomMonitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitorValue);
}
public int GetMonitorValue()
{
return GD.Randi() % 25;
}
[/csharp]
[/codeblocks]
2020-06-04 15:18:57 +02:00
The debugger calls the callable to get the value of custom monitor. The callable must return a number.
Callables are called with arguments supplied in argument array.
[b]Note:[/b] It throws an error if given id is already present.
</description>
</method>
<method name= "get_custom_monitor" >
<return type= "Variant" >
</return>
<argument index= "0" name= "id" type= "StringName" >
</argument>
<description >
Returns the value of custom monitor with given id. The callable is called to get the value of custom monitor.
[b]Note:[/b] It throws an error if the given id is absent.
</description>
</method>
<method name= "get_custom_monitor_names" >
<return type= "Array" >
</return>
<description >
Returns the names of active custom monitors in an array.
</description>
</method>
2017-09-12 22:42:36 +02:00
<method name= "get_monitor" qualifiers= "const" >
<return type= "float" >
</return>
<argument index= "0" name= "monitor" type= "int" enum= "Performance.Monitor" >
</argument>
<description >
2019-06-26 15:57:13 +02:00
Returns the value of one of the available monitors. You should provide one of the [enum Monitor] constants as the argument, like this:
2020-10-31 18:54:17 +01:00
[codeblocks]
[gdscript]
print(Performance.get_monitor(Performance.TIME_FPS)) # Prints the FPS to the console.
[/gdscript]
[csharp]
GD.Print(Performance.GetMonitor(Performance.Monitor.TimeFps)); // Prints the FPS to the console.
[/csharp]
[/codeblocks]
2017-09-12 22:42:36 +02:00
</description>
</method>
2020-06-04 15:18:57 +02:00
<method name= "get_monitor_modification_time" >
<return type= "int" >
</return>
<description >
Returns the last tick in which custom monitor was added/removed.
</description>
</method>
<method name= "has_custom_monitor" >
<return type= "bool" >
</return>
<argument index= "0" name= "id" type= "StringName" >
</argument>
<description >
Returns true if custom monitor with the given id is present otherwise returns false.
</description>
</method>
<method name= "remove_custom_monitor" >
<return type= "void" >
</return>
<argument index= "0" name= "id" type= "StringName" >
</argument>
<description >
Removes the custom monitor with given id.
[b]Note:[/b] It throws an error if the given id is already absent.
</description>
</method>
2017-09-12 22:42:36 +02:00
</methods>
<constants >
2017-11-24 23:16:30 +01:00
<constant name= "TIME_FPS" value= "0" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
Number of frames per second.
2017-09-12 22:42:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "TIME_PROCESS" value= "1" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
Time it took to complete one frame, in seconds.
2017-09-12 22:42:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "TIME_PHYSICS_PROCESS" value= "2" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
Time it took to complete one physics frame, in seconds.
2017-09-12 22:42:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "MEMORY_STATIC" value= "3" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Static memory currently used, in bytes. Not available in release builds.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "MEMORY_STATIC_MAX" value= "4" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Available static memory. Not available in release builds.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "MEMORY_MESSAGE_BUFFER_MAX" value= "5" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Largest amount of memory the message queue buffer has used, in bytes. The message queue is used for deferred functions calls and notifications.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "OBJECT_COUNT" value= "6" enum= "Monitor" >
2021-06-18 00:03:09 +02:00
Number of objects currently instantiated (including nodes).
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "OBJECT_RESOURCE_COUNT" value= "7" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Number of resources currently used.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "OBJECT_NODE_COUNT" value= "8" enum= "Monitor" >
2021-06-18 00:03:09 +02:00
Number of nodes currently instantiated in the scene tree. This also includes the root node.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "OBJECT_ORPHAN_NODE_COUNT" value= "9" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
Number of orphan nodes, i.e. nodes which are not parented to a node of the scene tree.
2019-04-17 22:46:21 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_OBJECTS_IN_FRAME" value= "10" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
3D objects drawn per frame.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_VERTICES_IN_FRAME" value= "11" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Vertices drawn per frame. 3D only.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_MATERIAL_CHANGES_IN_FRAME" value= "12" enum= "Monitor" >
2019-06-22 01:04:47 +02:00
Material changes per frame. 3D only.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_SHADER_CHANGES_IN_FRAME" value= "13" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Shader changes per frame. 3D only.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_SURFACE_CHANGES_IN_FRAME" value= "14" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Render surface changes per frame. 3D only.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_DRAW_CALLS_IN_FRAME" value= "15" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Draw calls per frame. 3D only.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_VIDEO_MEM_USED" value= "16" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
The amount of video memory used, i.e. texture and vertex memory combined.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_TEXTURE_MEM_USED" value= "17" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
The amount of texture memory used.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_VERTEX_MEM_USED" value= "18" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
The amount of vertex memory used.
2017-10-08 18:31:56 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "RENDER_USAGE_VIDEO_MEM_TOTAL" value= "19" enum= "Monitor" >
2020-02-13 10:08:52 +01:00
Unimplemented in the GLES2 rendering backend, always returns 0.
2017-10-22 12:56:11 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "PHYSICS_2D_ACTIVE_OBJECTS" value= "20" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Number of active [RigidBody2D] nodes in the game.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "PHYSICS_2D_COLLISION_PAIRS" value= "21" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Number of collision pairs in the 2D physics engine.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "PHYSICS_2D_ISLAND_COUNT" value= "22" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Number of islands in the 2D physics engine.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "PHYSICS_3D_ACTIVE_OBJECTS" value= "23" enum= "Monitor" >
2020-03-30 18:22:57 +02:00
Number of active [RigidBody3D] and [VehicleBody3D] nodes in the game.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "PHYSICS_3D_COLLISION_PAIRS" value= "24" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Number of collision pairs in the 3D physics engine.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "PHYSICS_3D_ISLAND_COUNT" value= "25" enum= "Monitor" >
2017-10-08 18:31:56 +02:00
Number of islands in the 3D physics engine.
2017-09-12 22:42:36 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "AUDIO_OUTPUT_LATENCY" value= "26" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
Output latency of the [AudioServer].
2018-07-26 11:56:21 +02:00
</constant>
2020-02-18 13:59:24 +01:00
<constant name= "MONITOR_MAX" value= "27" enum= "Monitor" >
2019-06-26 15:57:13 +02:00
Represents the size of the [enum Monitor] enum.
2017-09-12 22:42:36 +02:00
</constant>
</constants>
</class>