diff --git a/development/cpp/img/cpp_profiler_hotspot_flame_graph.png b/development/cpp/img/cpp_profiler_hotspot_flame_graph.png new file mode 100644 index 000000000..a297374fb Binary files /dev/null and b/development/cpp/img/cpp_profiler_hotspot_flame_graph.png differ diff --git a/development/cpp/img/cpp_profiler_hotspot_record.png b/development/cpp/img/cpp_profiler_hotspot_record.png new file mode 100644 index 000000000..29993f48d Binary files /dev/null and b/development/cpp/img/cpp_profiler_hotspot_record.png differ diff --git a/development/cpp/img/cpp_profiler_hotspot_view_results.png b/development/cpp/img/cpp_profiler_hotspot_view_results.png new file mode 100644 index 000000000..47f68ff64 Binary files /dev/null and b/development/cpp/img/cpp_profiler_hotspot_view_results.png differ diff --git a/development/cpp/img/cpp_profiler_hotspot_welcome.png b/development/cpp/img/cpp_profiler_hotspot_welcome.png new file mode 100644 index 000000000..ba52e98eb Binary files /dev/null and b/development/cpp/img/cpp_profiler_hotspot_welcome.png differ diff --git a/development/cpp/img/cpp_profiler_verysleepy_results_filtered.png b/development/cpp/img/cpp_profiler_verysleepy_results_filtered.png new file mode 100644 index 000000000..f178a2878 Binary files /dev/null and b/development/cpp/img/cpp_profiler_verysleepy_results_filtered.png differ diff --git a/development/cpp/img/cpp_profiler_verysleepy_select_process.png b/development/cpp/img/cpp_profiler_verysleepy_select_process.png new file mode 100644 index 000000000..41e5f926f Binary files /dev/null and b/development/cpp/img/cpp_profiler_verysleepy_select_process.png differ diff --git a/development/cpp/index.rst b/development/cpp/index.rst index b87cc4109..fb8e87ea9 100644 --- a/development/cpp/index.rst +++ b/development/cpp/index.rst @@ -1,21 +1,57 @@ Engine development ================== +Setting up a development environment +------------------------------------ + +To modify Godot's source code, you need to set up a development environment. Start here. + .. toctree:: :maxdepth: 1 - :name: toc-devel-cpp + :name: toc-devel-cpp-dev-env + + configuring_an_ide/index + +Getting started with Godot's source code +---------------------------------------- + +This section covers the basics that you will encounter in (almost) every source file. + +.. toctree:: + :maxdepth: 1 + :name: toc-devel-cpp-source-beginner introduction_to_godot_development - configuring_an_ide/index common_engine_methods_and_macros core_types variant_class object_class inheritance_class_tree - unit_testing + +Extending Godot by modifying its source code +--------------------------------------------- + +This section covers what you can do by modifying Godot's C++ source code. + +.. toctree:: + :maxdepth: 1 + :name: toc-devel-cpp-source-advanced + custom_modules_in_cpp binding_to_external_libraries + custom_godot_servers custom_resource_format_loaders custom_audiostreams - custom_godot_servers + unit_testing + +Debugging and profiling +----------------------- + +This section is about finding spots to optimize in the engine code when you need it in your project. + +.. toctree:: + :maxdepth: 1 + :name: toc-devel-cpp-debug-profiling + + using_cpp_profilers vulkan/index diff --git a/development/cpp/using_cpp_profilers.rst b/development/cpp/using_cpp_profilers.rst new file mode 100644 index 000000000..a87028414 --- /dev/null +++ b/development/cpp/using_cpp_profilers.rst @@ -0,0 +1,130 @@ +Using C++ profilers +=================== + +To optimize Godot's performance, you need to know what to optimize first. +To this end, profilers are useful tools. + +.. note:: + + There is a :ref:`built-in GDScript profiler ` in the editor, + but using C++ profiler may be useful in cases where the GDScript profiler + is not accurate enough or is missing information due to bugs in the profiler. + +Recommended profilers +--------------------- + +- `VerySleepy `__ (Windows only) +- `HotSpot `__ (Linux only) + +These profilers may not be the most powerful or flexible options, but their +standalone operation and limited feature set tends to make them easier to use. + +Setting up Godot +---------------- + +To get useful profiling information, it is **absolutely required** to use a Godot +build that includes debugging symbols. Official binaries do not include debugging +symbols, since these would make the download size significantly larger. + +To get profiling data that best matches the production environment, you should +compile binaries with the following SCons options: + +- For editor binaries: ``target=release_debug use_lto=yes`` +- For debug export templates: ``target=release_debug use_lto=yes`` +- For release export templates: ``tools=no target=release debug_symbols=yes`` + - ``debug_symbols=yes`` is required as export templates are stripped from debugging symbols by default. + +It is possible to run a profiler on less optimized builds (e.g. ``target=debug`` without LTO), +but results will naturally be less representative of real world conditions. + +.. warning:: + + Do *not* strip debugging symbols on the binaries using the ``strip`` command + after compiling the binaries. Otherwise, you will no longer get useful + profiling information when running a profiler. + +Benchmarking startup/shutdown times +----------------------------------- + +If you're looking into optimizing Godot's startup/shutdown performance, +you can tell the profiler to use the ``--quit`` command line option on the Godot binary. +This will exit Godot just after it finished starting. +The ``--quit`` option works with ``--editor``, ``--project-manager`` or +``--path `` (which runs a project directly). + +.. seealso:: + + See :ref:`doc_command_line_tutorial` for more command line arguments + supported by Godot. + +Profiler-specific instructions +------------------------------ + +VerySleepy +^^^^^^^^^^ + +- Start the Godot editor or your project first. + If you start the project manager, make sure to edit or run a project first. + Otherwise, the profiler will not track the child process since the project manager + will spawn a child process for every project edited or run. +- Open VerySleepy and select the Godot executable in the list of processes on the left: + +.. image:: img/cpp_profiler_verysleepy_select_process.png + +- Click the **Profile All** button on the right to start profiling. +- Perform the actions you wish to profile in the editor or project. When you're done, click **Stop** (*not* Abort). +- Wait for the results window to appear. +- Once the results window appears, filter the view to remove external modules (such as the graphics driver). + You can filter by module by finding a line whose **Module** matches the Godot + executable name, right-clicking that line then choosing + **Filter Module to ** in the dropdown that appears. +- Your results window should now look something like this: + +.. image:: img/cpp_profiler_verysleepy_results_filtered.png + +HotSpot +^^^^^^^ + +- Open HotSpot. Click **Record Data**: + +.. image:: img/cpp_profiler_hotspot_welcome.png + +- In the next window, specify the path to the Godot binary that includes debug symbols. +- Specify command line arguments to run a specific project, with or without the editor. +- The path to the working directory can be anything if an absolute path is used + for the ``--path`` command line argument. Otherwise, it must be set to that + the relative path to the project is valid. +- Make sure **Elevate Privileges** is checked if you have administrative privileges. + While not essential for profiling Godot, this will ensure all events can be captured. + Otherwise, some events may be missing in the capture. + Your settings should now look something like this: + +.. image:: img/cpp_profiler_hotspot_record.png + +- Click **Start Recording** and perform the actions you wish to profile in the editor/project. +- Quit the editor/project normally or use the **Stop Profiling** button in HotSpot + to stop profiling early. Stopping profiling early can result in cleaner profiles + if you're not interested in the engine's quit procedure. +- Click **View Results** and wait for the profiling visualization to be generated: + +.. image:: img/cpp_profiler_hotspot_view_results.png + +- Use the tabs at the top to navigate between the different views. These views + show the same data, but in different ways. The **Flame Graph** tab is a good + way to see which functions take up the most time at a glance. These functions + are therefore the most important ones to optimize, since optimizing them will + improve performance the most. +- At the bottom of all tabs except **Summary**, you will also see a list of CPU threads + started by the engine among with the CPU utilization for each thread. + This lets you see threads that can be a bottleneck at a given point in time. + +.. image:: img/cpp_profiler_hotspot_flame_graph.png + +.. note:: + + If you don't want the startup procedure to be included in the profile, you + can also attach HotSpot to a running process by clicking **Record Data** + then setting the **Launch Application** dropdown option to **Attach To + Process(es)**. + + This process attachment-based workflow is similar to the one used by VerySleepy.