diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_activity_graphics_capture.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_activity_graphics_capture.webp new file mode 100644 index 00000000000..93e921730d5 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_activity_graphics_capture.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_details.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_details.webp new file mode 100644 index 00000000000..f48fa2563b6 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_details.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_results.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_results.webp new file mode 100644 index 00000000000..ef5426d8407 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_results.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_results_live_replay.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_results_live_replay.webp new file mode 100644 index 00000000000..037b6c32283 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_capture_results_live_replay.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_default_project.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_default_project.webp new file mode 100644 index 00000000000..52cee2dadbf Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_default_project.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_launch_options.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_launch_options.webp new file mode 100644 index 00000000000..1368e8c1709 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_launch_options.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_overlay_capture.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_overlay_capture.webp new file mode 100644 index 00000000000..904d11c0c9c Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_overlay_capture.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nsight_run_other_activity.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_run_other_activity.webp new file mode 100644 index 00000000000..5e1cbf528ff Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nsight_run_other_activity.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nvcp_enable_developer_settings.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nvcp_enable_developer_settings.webp new file mode 100644 index 00000000000..56f0f619cc5 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nvcp_enable_developer_settings.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_nvcp_performance_counters.webp b/engine_details/development/debugging/img/using_graphics_debuggers_nvcp_performance_counters.webp new file mode 100644 index 00000000000..f006431d854 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_nvcp_performance_counters.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_button.webp b/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_button.webp new file mode 100644 index 00000000000..542f64b9b40 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_button.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_results.webp b/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_results.webp new file mode 100644 index 00000000000..3d5f818433c Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_results.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_with_timings.webp b/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_with_timings.webp new file mode 100644 index 00000000000..36534623fdd Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_pix_capture_with_timings.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_pix_launch_options.webp b/engine_details/development/debugging/img/using_graphics_debuggers_pix_launch_options.webp new file mode 100644 index 00000000000..95167c9dc28 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_pix_launch_options.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_pix_welcome.webp b/engine_details/development/debugging/img/using_graphics_debuggers_pix_welcome.webp new file mode 100644 index 00000000000..da98f17be2f Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_pix_welcome.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_captures.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_captures.webp new file mode 100644 index 00000000000..7481166f2ed Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_captures.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_draw_calls_list.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_draw_calls_list.webp new file mode 100644 index 00000000000..015cf496be2 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_draw_calls_list.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_draw_calls_time.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_draw_calls_time.webp new file mode 100644 index 00000000000..e0b1023ce7e Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_draw_calls_time.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_launch.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_launch.webp new file mode 100644 index 00000000000..c544f64dc25 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_launch.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_launch_auto_capture.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_launch_auto_capture.webp new file mode 100644 index 00000000000..69dd6ff3219 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_launch_auto_capture.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_overlay.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_overlay.webp new file mode 100644 index 00000000000..834a3eb6a56 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_overlay.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_statistics.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_statistics.webp new file mode 100644 index 00000000000..d2de4bd4665 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_statistics.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_vulkan_setup.webp b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_vulkan_setup.webp new file mode 100644 index 00000000000..593aff1228b Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_debuggers_renderdoc_vulkan_setup.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_godot_run_project_directly.webp b/engine_details/development/debugging/img/using_graphics_profilers_godot_run_project_directly.webp new file mode 100644 index 00000000000..d6b7ed8c927 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_godot_run_project_directly.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_activity_gpu_trace.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_activity_gpu_trace.webp new file mode 100644 index 00000000000..b9d466901da Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_activity_gpu_trace.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_analysis.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_analysis.webp new file mode 100644 index 00000000000..70fd95f4b85 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_analysis.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_analysis_frame_gain.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_analysis_frame_gain.webp new file mode 100644 index 00000000000..d91b6b43d99 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_analysis_frame_gain.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_missing_debug_info.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_missing_debug_info.webp new file mode 100644 index 00000000000..f4d1ddd6477 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_missing_debug_info.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_popup.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_popup.webp new file mode 100644 index 00000000000..2697671a2a6 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_popup.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_results.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_results.webp new file mode 100644 index 00000000000..3c116c1bfd5 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_gpu_trace_results.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_nsight_overlay_gpu_trace.webp b/engine_details/development/debugging/img/using_graphics_profilers_nsight_overlay_gpu_trace.webp new file mode 100644 index 00000000000..301536ad544 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_nsight_overlay_gpu_trace.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rdp_create_connection.webp b/engine_details/development/debugging/img/using_graphics_profilers_rdp_create_connection.webp new file mode 100644 index 00000000000..6a04f688719 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rdp_create_connection.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rdp_profile_list.webp b/engine_details/development/debugging/img/using_graphics_profilers_rdp_profile_list.webp new file mode 100644 index 00000000000..720d8c30f9b Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rdp_profile_list.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rdp_profiling_feature.webp b/engine_details/development/debugging/img/using_graphics_profilers_rdp_profiling_feature.webp new file mode 100644 index 00000000000..fc7ceb9009f Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rdp_profiling_feature.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rdp_ready.webp b/engine_details/development/debugging/img/using_graphics_profilers_rdp_ready.webp new file mode 100644 index 00000000000..aba027358f1 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rdp_ready.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rdp_running_app_error.webp b/engine_details/development/debugging/img/using_graphics_profilers_rdp_running_app_error.webp new file mode 100644 index 00000000000..15db8305d71 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rdp_running_app_error.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rdp_sync_primitives_warning.webp b/engine_details/development/debugging/img/using_graphics_profilers_rdp_sync_primitives_warning.webp new file mode 100644 index 00000000000..441689e01a7 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rdp_sync_primitives_warning.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_event_timing.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_event_timing.webp new file mode 100644 index 00000000000..18498d6d23e Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_event_timing.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_event_timing_context_menu.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_event_timing_context_menu.webp new file mode 100644 index 00000000000..2c38928d0e9 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_event_timing_context_menu.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_pipeline_state.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_pipeline_state.webp new file mode 100644 index 00000000000..3e545bee9f6 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_pipeline_state.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_pipeline_state_2.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_pipeline_state_2.webp new file mode 100644 index 00000000000..05957dabeb7 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_pipeline_state_2.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_wavefront_occupancy.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_wavefront_occupancy.webp new file mode 100644 index 00000000000..5c6503bd4f2 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_events_wavefront_occupancy.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overlay.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overlay.webp new file mode 100644 index 00000000000..5a1ecf48d3b Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overlay.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_barriers.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_barriers.webp new file mode 100644 index 00000000000..58de08f0eda Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_barriers.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_context_rolls.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_context_rolls.webp new file mode 100644 index 00000000000..fc527445f8d Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_context_rolls.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_frame_summary.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_frame_summary.webp new file mode 100644 index 00000000000..7463122865e Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_frame_summary.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_most_expensive_events.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_most_expensive_events.webp new file mode 100644 index 00000000000..e92e765de58 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_most_expensive_events.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_pipelines.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_pipelines.webp new file mode 100644 index 00000000000..40fe4573646 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_pipelines.webp differ diff --git a/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_render_depth_targets.webp b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_render_depth_targets.webp new file mode 100644 index 00000000000..99f97e74c51 Binary files /dev/null and b/engine_details/development/debugging/img/using_graphics_profilers_rgp_overview_render_depth_targets.webp differ diff --git a/engine_details/development/debugging/index.rst b/engine_details/development/debugging/index.rst index 4a5e82fe541..bbaf89cebfa 100644 --- a/engine_details/development/debugging/index.rst +++ b/engine_details/development/debugging/index.rst @@ -11,8 +11,10 @@ engine code trying to find an underlying issue or an optimization possibility. :name: toc-devel-cpp-debug-profiling using_cpp_profilers - using_sanitizers macos_debug + using_sanitizers + using_graphics_debuggers + using_graphics_profilers vulkan/index Debugging the editor diff --git a/engine_details/development/debugging/using_graphics_debuggers.rst b/engine_details/development/debugging/using_graphics_debuggers.rst new file mode 100644 index 00000000000..217350523e7 --- /dev/null +++ b/engine_details/development/debugging/using_graphics_debuggers.rst @@ -0,0 +1,351 @@ +.. _doc_using_graphics_debuggers: + +Using graphics debuggers +======================== + +This page covers how to set up graphics debuggers for use with Godot. + +.. seealso:: + + To investigate GPU performance issues in the engine, you should use a + :ref:`graphics profiler ` instead, + as RenderDoc is not a profiler. + +Setting up Godot +---------------- + +Unlike :ref:`C++ profilers ` +it is not required to use an engine build that contains debugging symbols to get +useful graphics debugging information. However, using an editor or debug export +template build is strongly recommended, as release export templates strip most of the +debug information that GPU debuggers can make use of. + +Additionally, when running Godot through a graphics debugger, you should +always run it using the ``--generate-spirv-debug-info`` +:ref:`command line argument `. Otherwise, source-level +shader debugging won't work. + +In most situations, you want to run the project directly, rather than open the Godot editor +or project manager. In the instructions below, we'll always specify ``--path`` and the +path to the project directory in the command line arguments. To run a specific scene +instead of the main scene, you can also specify a path to a scene file afterwards: +``--path /path/to/project /path/to/project/scene.tscn``. +The path to the scene file can be absolute, or relative to the project folder +(i.e. ``--path /path/to/project scene.tscn`` would work here too). + +Recommended debuggers +--------------------- + +- `RenderDoc `__ (Windows/Linux, Vulkan/Direct3D 12/OpenGL) +- `PIX `__ + (Windows, Direct3D 12 only) +- `NVIDIA NSight Graphics `__ + (Windows/Linux, Vulkan/Direct3D 12) + + - Requires a NVIDIA GPU. + - Not to be confused with NVIDIA NSight *Systems*, which is designed to profile + compute workloads as opposed to gaming workloads. + +RenderDoc-specific instructions +------------------------------- + +- Open RenderDoc. Do not run Godot at this time, as RenderDoc will run it later. +- You may see a warning in the middle of the window about missing Vulkan setup. + Click the warning to install the Vulkan layer, which is required for profiling to work: + +.. figure:: img/using_graphics_debuggers_renderdoc_vulkan_setup.webp + :align: center + :alt: Missing Vulkan setup warning in RenderDoc. + + Missing Vulkan setup warning in RenderDoc. + +- Once this is done, fill in the :menu:`Launch Application` pane's fields as follows: + +.. figure:: img/using_graphics_debuggers_renderdoc_launch.webp + :align: center + :alt: Launch Application pane in RenderDoc (with filled options to run a specific project directly). + + Launch Application pane in RenderDoc (with filled options to run a specific project directly). + +You can also configure RenderDoc to automatically capture the *second* rendered frame (*Frame 1*), +then add ``--quit`` to the command line arguments. This speeds up the process of iterating on RenderDoc +captures by making capturing only require clicking a single button. Godot will then quit immediately after +the capture is done, so it doesn't linger in the background. + +.. note:: + + Certain processes like radiance map generation will be running on the first rendered frames, + so if you want to prevent those from showing up in the capture, you'll need to move the capture + to a later frame number (*Frame 30* is a good starting point). + +.. figure:: img/using_graphics_debuggers_renderdoc_launch_auto_capture.webp + :align: center + :alt: Automatically capture the second rendered frame (Frame 1, as Frame 0 is the splash screen) and quit Godot immediately after. + + Automatically capture the second rendered frame (Frame 1, as Frame 0 is the splash screen) and quit Godot immediately after. + +- Click :button:`Launch Application`. The project should start; if not, check that + the project path is correct and points to a folder, not a file. Once the project is running, + you'll see an overlay in the top-left corner of the window. Press :kbd:`F12` or :kbd:`Print Screen` + to capture a frame: + +.. figure:: img/using_graphics_debuggers_renderdoc_overlay.webp + :align: center + :alt: RenderDoc overlay in the running project. + + RenderDoc overlay in the running project. + +You can capture multiple frames in the same session if needed. Note that the capture +shortcut is global on Windows and Linux when using X11, so you can press it even if +the Godot window isn't focused. + +- After capturing some frames, you'll see a summary in the RenderDoc window. Double-click + any of the captures to open them in RenderDoc for inspection. You can also right-click + a capture to open it in a new RenderDoc instance, which allows you to inspect multiple + frames in parallel. + +.. note:: + + If only one frame is captured, RenderDoc will open it automatically + when the project is closed. + +.. figure:: img/using_graphics_debuggers_renderdoc_captures.webp + :align: center + :alt: List of captures performed in RenderDoc. Right-clicking allows for additional actions (opening in a new window, renaming, deleting, ...). + + List of captures performed in RenderDoc. Right-clicking allows for additional actions (opening in a new window, renaming, deleting, ...). + +RenderDoc usage +--------------- + +After a capture is opened for inspection, there are several things you can do: + +- Inspect the list of draw calls using the :menu:`Event Browser` and :menu:`API Inspector` panes at the left: + +.. figure:: img/using_graphics_debuggers_renderdoc_draw_calls_list.webp + :align: center + :alt: List of draw calls in RenderDoc. + + List of draw calls in RenderDoc. + +You can time the draw calls by clicking the clock icon at the top: + +.. figure:: img/using_graphics_debuggers_renderdoc_draw_calls_time.webp + :align: center + :alt: Measure time taken by each draw call in RenderDoc. + + Measure time taken by each draw call in RenderDoc. + +This will re-run the draw calls on the GPU to measure how much time they take. +The time is then displayed next to each draw call, which can be used to spot +the draw calls taking the most time. + + .. note:: + + This is *not* a profiling feature, as the timings may be inaccurate due to various factors + (e.g. the GPU downclocking as a power saving measure). Forcing the GPU to the highest + performance state in the graphics driver control panel before clicking the clock icon + can improve accuracy. + +- View capture statistics using :menu:`Window > Statistics` at the top of the RenderDoc + window. This opens a new pane: + +.. figure:: img/using_graphics_debuggers_renderdoc_statistics.webp + :align: center + :alt: Capture statistics in RenderDoc. + + Capture statistics in RenderDoc. + +.. tip:: + + It is possible to interoperate + `RenderDoc with Radeon GPU Profiler `__. + This can be used to profile the same capture as used in RenderDoc. + +PIX-specific instructions +------------------------- + +- Open PIX. Do not run Godot at this time, as PIX will run it later. + +- Click :button:`Launch Process` in the top-left corner: + +.. figure:: img/using_graphics_debuggers_pix_welcome.webp + :align: center + :alt: PIX interface on launch. + + PIX interface on launch. + +Fill in the launch options to run a project directly: + +.. figure:: img/using_graphics_debuggers_pix_launch_options.webp + :align: center + :alt: PIX launch options. + + PIX launch options. + +You can also configure PIX to automatically capture the *second* rendered frame (*Frame 1*), +then add ``--quit`` to the command line arguments. This speeds up the process of iterating on PIX +captures by making capturing only require clicking a single button. Godot will then quit immediately after +the capture is done, so it doesn't linger in the background. + +- Click :button:`Launch Application`. The project should start; if not, check that + the project path is correct and points to a folder, not a file. Once the project is running, + switch back to the PIX window and click :button:`Take Capture` in the top-left corner: + +.. figure:: img/using_graphics_debuggers_pix_capture_button.webp + :align: center + :alt: Take Capture button in the PIX window. + + Take Capture button in the PIX window. + +You can capture multiple frames in the same session if needed. + +- After capturing some frames, you'll see a summary in the PIX window. Double-click + any of the captures to open them in PIX for inspection. + +PIX usage +--------- + +After a capture is opened for inspection, there are several things you can do: + +- Inspect the list of draw calls using the pane at the left: + +.. figure:: img/using_graphics_debuggers_pix_capture_results.webp + :align: center + :alt: Capture results with draw call list in PIX. + + Capture results with draw call list in PIX. + +This will re-run the draw calls on the GPU to measure how much time they take. +The time is then displayed next to each draw call, which can be used to spot +the draw calls taking the most time. + + .. note:: + + This is *not* a profiling feature, as the timings may be inaccurate due to various factors + (e.g. the GPU downclocking as a power saving measure). Forcing the GPU to the highest + performance state in the graphics driver control panel before clicking the clock icon + can improve accuracy. + + On NVIDIA GPUs (Ampere and later), PIX will automatically use the highest power state while + collecting timing data by default. + +Once timing data is collected, you'll be able to see timing data on the draw call list +(in the :menu:`EOP to EOP duration` column of the table) and in the timeline at the bottom: + +.. figure:: img/using_graphics_debuggers_pix_capture_with_timings.webp + :align: center + :alt: PIX capture with timing data. + + PIX capture with timing data. + +The timeline can have its sections expanded to see more details. The data is based on the GPU's +performance counters, which allow seeing which parts of the GPU are being stressed the most. + +Troubleshooting +^^^^^^^^^^^^^^^ + +If collecting the timing data fails on NVIDIA GPUs, make sure performance counters are configured +to be accessible by all users in the NVIDIA Control Panel: + +.. figure:: img/using_graphics_debuggers_nvcp_enable_developer_settings.webp + :align: center + :alt: Enabling developer settings in NVIDIA Control Panel + + Enabling developer settings in NVIDIA Control Panel + +.. figure:: img/using_graphics_debuggers_nvcp_performance_counters.webp + :align: center + :alt: Configuring performance counters to be accessible by all users in NVIDIA Control Panel. + + Configuring performance counters to be accessible by all users in NVIDIA Control Panel. + +NSight-specific instructions +---------------------------- + +- Open NSight Graphics. Do not run Godot at this time, as NSight will run it later. + +- Double-click :menu:`Default Project` in the list at the left: + +.. figure:: img/using_graphics_debuggers_nsight_default_project.webp + :align: center + :alt: NSight default project. + + NSight default project. + +Fill in the launch options to run a project directly: + +.. figure:: img/using_graphics_debuggers_nsight_launch_options.webp + :align: center + :alt: NSight launch options. + + NSight launch options. + +In the Activity section below the launch options, choose :menu:`Graphics Capture` +and leave all options at their default values: + +.. figure:: img/using_graphics_debuggers_nsight_activity_graphics_capture.webp + :align: center + :alt: Creating a Graphics capture activity in NSight. + + Creating a Graphics capture activity in NSight. + +- Click :button:`Launch Application`. The project should start; if not, check that + the project path is correct and points to a folder, not a file. Once the project is running, + you'll see an overlay in the top-left corner of the window. Press :kbd:`F11` + to capture a frame: + +.. figure:: img/using_graphics_debuggers_nsight_overlay_capture.webp + :align: center + :alt: NSight capture overlay in the running project. + + NSight capture overlay in the running project. + +You can capture multiple frames in the same session if needed. + +- After capturing some frames, you'll see a summary in the NSight window. Select a capture + on the left, then click :button:`Start Graphics Debugger` to open the capture results + in a new window. + +.. figure:: img/using_graphics_debuggers_nsight_capture_details.webp + :align: center + :alt: List of captures performed in NSight. + + List of captures performed in NSight. + +NSight usage +------------ + +After a capture is opened for inspection, there are several things you can do: + +- Inspect the list of draw calls using the pane at the left: + +.. figure:: img/using_graphics_debuggers_nsight_capture_results.webp + :align: center + :alt: Capture results with draw call list in NSight. + + Capture results with draw call list in NSight. + +Some of the functionality isn't available until you enable live replay, which will re-run +the capture on the GPU. This allows features like viewing image data to work. +To enable live replay, click the :button:`start live replay` link in any of the notices +that appear on screen. + +.. figure:: img/using_graphics_debuggers_nsight_capture_results_live_replay.webp + :align: center + :alt: Capture results with live replay in NSight. + + Capture results with live replay in NSight. + +NSight is also a profiler, so you can choose to use the current session as the basis for +profiling using the Run section in the current capture details: + +.. figure:: img/using_graphics_debuggers_nsight_run_other_activity.webp + :align: center + :alt: Run another activity from the current activity in NSight + + Run another activity from the current activity in NSight + +.. seealso:: + + Using NSight's profiler is covered in :ref:`doc_using_graphics_profilers`. diff --git a/engine_details/development/debugging/using_graphics_profilers.rst b/engine_details/development/debugging/using_graphics_profilers.rst new file mode 100644 index 00000000000..6c189d7eac1 --- /dev/null +++ b/engine_details/development/debugging/using_graphics_profilers.rst @@ -0,0 +1,351 @@ +.. _doc_using_graphics_profilers: + +Using graphics profilers +======================== + +This page covers how to set up graphics profilers for use with Godot. + +.. seealso:: + + To investigate rendering issues in the engine, you should use a + :ref:`graphics debugger ` + such as RenderDoc instead. + +Setting up Godot +---------------- + +Unlike :ref:`C++ profilers ` +it is not required to use an engine build that contains debugging symbols to get +useful graphics profiling information. However, using an editor or debug export +template build is strongly recommended, as release export templates strip most of the +debug information that GPU profilers can make use of. + +Recommended profilers +--------------------- + +- `AMD Radeon GPU Profiler `__ (Windows/Linux, Vulkan/Direct3D 12) + + - Requires an AMD GPU. + - Installed as part of the `Radeon Developer Tool Suite `__, + which includes other tools like a GPU memory analyzer. + +- `NVIDIA NSight Graphics `__ + (Windows/Linux, Vulkan/Direct3D 12) + + - Requires a NVIDIA GPU. + - Not to be confused with NVIDIA NSight *Systems*, which is designed to profile + compute workloads as opposed to gaming workloads. + +- `PIX `__ + (Windows, Direct3D 12 only) +- `Xcode `__ + (macOS, Metal only) +- `Arm Performance Studio `__ + (Windows/macOS/Linux, Vulkan only, profile on mobile devices) + +AMD Radeon GPU Profiler-specific instructions +--------------------------------------------- + +.. tip:: + + It is possible to interoperate + `RenderDoc with Radeon GPU Profiler `__. + This can be used to profile the same capture as used in RenderDoc. + +- Open Radeon Developer Panel, which is part of the Radeon Developer Tool Suite. + Do not open Radeon GPU Profiler, as it will be opened later when needed. + +- Create a local connection by leaving the parameters unchanged, then click + :button:`Connect`: + +.. figure:: img/using_graphics_profilers_rdp_create_connection.webp + :align: center + :alt: Creating a local connection in Radeon Developer Panel + + Creating a local connection in Radeon Developer Panel + +- Add the **Profiling** feature on the panel at the left by clicking the + :button:`+` icon next to its name: + +.. figure:: img/using_graphics_profilers_rdp_profiling_feature.webp + :align: center + :alt: Adding the Profiling feature in Radeon Developer Panel + + Adding the Profiling feature in Radeon Developer Panel + +When adding the Profiling feature, you may see a warning message about +missing Primitive Sync support in DirectX 12 applications: + +.. figure:: img/using_graphics_profilers_rdp_sync_primitives_warning.webp + :align: center + :alt: Missing Primitive Sync support warning in Radeon Developer Panel + + Missing Primitive Sync support warning in Radeon Developer Panel + +In this case, answer :button:`Yes` to enable this feature and accept the UAC prompt. +This is not required when profiling projects using Vulkan. + +- Unlike other graphics debugging/profiling tools, you should run Godot yourself, + as Radeon Developer Panel won't run it for you. + Open the Project Manager, select your project and click :button:`Run` + to run the project directly without the editor running in the background: + +.. figure:: img/using_graphics_profilers_godot_run_project_directly.webp + :align: center + :alt: Running the project directly from Godot's project manager + + Running the project directly from Godot's project manager + +You can also run a project directly from the command line. The editor +must **not** be running at the same time, or capturing will fail +due to multiple Godot processes being open simultaneously: + +.. figure:: img/using_graphics_profilers_rdp_running_app_error.webp + :align: center + :alt: Error message when trying to capture with multiple Godot processes open + + Error message when trying to capture with multiple Godot processes open + +- Once the project is running, you will see Radeon Developer Panel detect it if + the project is using Vulkan or Direct3D 12. Projects using OpenGL (including the project + manager) won't be detected: + +.. figure:: img/using_graphics_profilers_rdp_ready.webp + :align: center + :alt: Ready state in Radeon Developer Panel + + Ready state in Radeon Developer Panel + +You will also see an overlay on the running project that confirms capturing is available: + +.. figure:: img/using_graphics_profilers_rgp_overlay.webp + :align: center + :alt: Overlay on running project + + Overlay on running project + +- Press :kbd:`Ctrl + Alt + C` or click :button:`Capture Profile` to capture a frame. + +- You can now close Godot, or keep it open to capture more frames later. + Select a frame in the list on the right, and double-click it to open it + in Radeon GPU Profiler (abbreviated "RGP" below): + +.. figure:: img/using_graphics_profilers_rdp_profile_list.webp + :align: center + :alt: Profile list after capturing a frame in Radeon Developer Panel + + Profile list after capturing a frame in Radeon Developer Panel + +- Once you open the profile in RGP, you will land on the overview page + in the :ui:`Frame summary` tab. This page presents a summary of what + was captured, and provides an indication of whether the profile was + CPU-bound or GPU-bound. Simple scenes with not much going on are often + be CPU-bound: + +.. figure:: img/using_graphics_profilers_rgp_overview_frame_summary.webp + :align: center + :alt: Frame summary in Radeon GPU Profiler + + Frame summary in Radeon GPU Profiler + +- The :ui:`Barriers` tab shows a list of all GPU memory barriers that were + hit during the frame. This can be used to see how well the GPU's + parallelism was made use of: + +.. figure:: img/using_graphics_profilers_rgp_overview_barriers.webp + :align: center + :alt: Barriers in Radeon GPU Profiler + + Barriers in Radeon GPU Profiler + +- The :ui:`Context Rolls` tab shows a timeline of the different contexts + (command queues) that were used during the frame. This can be used + to see how well the CPU was able to feed the GPU with work: + +.. figure:: img/using_graphics_profilers_rgp_overview_context_rolls.webp + :align: center + :alt: Context rolls in Radeon GPU Profiler + + Context rolls in Radeon GPU Profiler + +- The :ui:`Most Expensive Events` tab shows a list of the most expensive draw calls + in the capture, along with the usage share relative to the rest of the frame. + You can also see which stages of the selected draw calls were the most expensive + (graphics or asynchronous compute): + +.. figure:: img/using_graphics_profilers_rgp_overview_most_expensive_events.webp + :align: center + :alt: Most expensive events in Radeon GPU Profiler + + Most expensive events in Radeon GPU Profiler + +- The :ui:`Render/Depth targets` tab shows a list of all render and depth targets + that were used during the frame. This can be used to see how many + render targets were created and used, and their resolution and format. + You can also see the number of draw calls that make use of each render target: + +.. figure:: img/using_graphics_profilers_rgp_overview_render_depth_targets.webp + :align: center + :alt: Render depth targets in Radeon GPU Profiler + + Render depth targets in Radeon GPU Profiler + +- The :ui:`Pipelines` tab shows a list of all graphics pipelines that were used + during the frame. This can be used to see how many pipelines were created + and used, and their state. + +.. figure:: img/using_graphics_profilers_rgp_overview_pipelines.webp + :align: center + :alt: Pipelines in Radeon GPU Profiler + + Pipelines in Radeon GPU Profiler + +- In the :ui:`Events` page at the top, you have access to different views. + The first view is :ui:`Wavefront occupancy`, which shows how well the GPU's + wavefronts are utilized during the frame. The pane on the right gives + extra information, such as :abbr:`VGPR (Vector General Purpose Register)` + and :abbr:`SGPR (Scalar General Purpose Register)` usage in each shader + stage used in the draw call. These values should be as low as possible: + +.. figure:: img/using_graphics_profilers_rgp_events_wavefront_occupancy.webp + :align: center + :alt: Wavefront occupancy in Radeon GPU Profiler + + Wavefront occupancy in Radeon GPU Profiler + +- The second view is :menu:`Event Timing`, which shows a timeline of all + GPU events that were captured during the frame. This can be used to see + how well the GPU was kept busy, and if there are any gaps where the GPU + was idle: + +.. figure:: img/using_graphics_profilers_rgp_events_event_timing.webp + :align: center + :alt: Event timing in Radeon GPU Profiler + + Event timing in Radeon GPU Profiler + +You can right-click any of the draw calls in the timeline to view it +in another context: + +.. figure:: img/using_graphics_profilers_rgp_events_event_timing_context_menu.webp + :align: center + :alt: Context menu when right-clicking one of the lines in Event timing + + Context menu when right-clicking one of the lines in Event timing + +- The :ui:`Pipeline state` view gives details about how shaders were + run for each draw call, including low-level information on how the + GPU's resources were utilized: + +.. figure:: img/using_graphics_profilers_rgp_events_pipeline_state.webp + :align: center + :alt: Pipeline state in Radeon GPU Profiler + + Pipeline state in Radeon GPU Profiler + +The information displayed depends on the draw call selected. For instance, +draw calls that draw geometry will display the index and primitive (vertex) +count: + +.. figure:: img/using_graphics_profilers_rgp_events_pipeline_state_2.webp + :align: center + :alt: View of another pipeline state in Radeon GPU Profiler + + View of another pipeline state in Radeon GPU Profiler + +NSight Graphics-specific instructions +------------------------------------- + +- Open NSight Graphics. Do not run Godot at this time, as NSight will run it later. + +- Double-click :menu:`Default Project` in the list at the left: + +.. figure:: img/using_graphics_debuggers_nsight_default_project.webp + :align: center + :alt: NSight default project. + + NSight default project. + +Fill in the launch options to run a project directly: + +.. figure:: img/using_graphics_debuggers_nsight_launch_options.webp + :align: center + :alt: NSight launch options. + + NSight launch options. + +In the Activity section below the launch options, choose :menu:`GPU Trace` +and leave all options at their default values: + +.. figure:: img/using_graphics_profilers_nsight_activity_gpu_trace.webp + :align: center + :alt: Creating a GPU trace activity in NSight. + + Creating a GPU trace activity in NSight. + +- Click :button:`Launch Application`. The project should start; if not, check that + the project path is correct and points to a folder, not a file. + Once the project is running, you'll see an overlay in the top-left corner of the window. + Press :kbd:`F11` to capture a frame for profiling: + +.. figure:: img/using_graphics_profilers_nsight_overlay_gpu_trace.webp + :align: center + :alt: NSight trace overlay in the running project. + + NSight trace overlay in the running project. + +You can capture multiple frames in the same session if needed. + +- After capturing some frames, you'll see a popup appear on the NSight window. This confirms + that the capture was done. Click :button:`Open` in the popup to open the profiler + in a new window: + +.. figure:: img/using_graphics_profilers_nsight_gpu_trace_popup.webp + :align: center + :alt: GPU trace data transfer popup. + + GPU trace data transfer popup. + +- You will then see the GPU trace results in a new window, where you can analyze the + captured frames and their performance metrics: + +.. figure:: img/using_graphics_profilers_nsight_gpu_trace_results.webp + :align: center + :alt: GPU trace results window. + + GPU trace results window. + +Click :button:`Trace Analysis...` near the top to perform a detailed analysis of the currently profiled frame: + +.. figure:: img/using_graphics_profilers_nsight_gpu_trace_analysis.webp + :align: center + :alt: GPU trace analysis window. + + GPU trace analysis window. + +This opens a detailed analysis window, with a list of automatically detected problems +and suggestions. Each problem/suggestion is accompanied by a frame gain value, +indicating its potential impact on performance. The number in the circle represents +the maximum percentage of performance increase that could be achieved by fully addressing +the problem/suggestion, relative to the current framerate. This is a theoretical value +and should be taken with caution. + +.. figure:: img/using_graphics_profilers_nsight_gpu_trace_analysis_frame_gain.webp + :align: center + :alt: GPU trace analysis frame gain legend. + + GPU trace analysis frame gain legend. + +Troubleshooting +^^^^^^^^^^^^^^^ + +If you see a warning about missing shader debug information after opening the profile window, +it means the Godot process wasn't started with the correct command line arguments. + +.. figure:: img/using_graphics_profilers_nsight_gpu_trace_missing_debug_info.webp + :align: center + :alt: GPU trace missing debug information warning. + + GPU trace missing debug information warning. + +To resolve this, TODO diff --git a/engine_details/development/debugging/vulkan/vulkan_validation_layers.rst b/engine_details/development/debugging/vulkan/vulkan_validation_layers.rst index eced5343f02..e55c4ac902f 100644 --- a/engine_details/development/debugging/vulkan/vulkan_validation_layers.rst +++ b/engine_details/development/debugging/vulkan/vulkan_validation_layers.rst @@ -12,6 +12,10 @@ builds, including in exported projects. Enabling validation layers has a performance impact, so only enable them when you actually need the output to debug the application. +.. seealso:: + + See :ref:`doc_using_graphics_debuggers` more advanced graphics debugging. + Windows ------- diff --git a/tutorials/scripting/debug/debugger_panel.rst b/tutorials/scripting/debug/debugger_panel.rst index b8754848814..c20a04e606b 100644 --- a/tutorials/scripting/debug/debugger_panel.rst +++ b/tutorials/scripting/debug/debugger_panel.rst @@ -120,6 +120,8 @@ and how that effects performance. A detailed explanation of how to use the profiler can be found in the dedicated :ref:`doc_the_profiler` page. +.. _doc_debugger_panel_visual_profiler: + Visual Profiler ---------------