diff --git a/contributing/development/compiling/compiling_for_android.rst b/contributing/development/compiling/compiling_for_android.rst index 5bcf3d87b..3f53093ba 100644 --- a/contributing/development/compiling/compiling_for_android.rst +++ b/contributing/development/compiling/compiling_for_android.rst @@ -120,11 +120,10 @@ The resulting APK will be located at ``bin/android_release.apk``. The resulting APK will be located at ``bin/android_debug.apk``. - .. seealso:: If you want to enable Vulkan validation layers, see - :ref:`Vulkan validation layers on Android`. + :ref:`Vulkan validation layers on Android `. Adding support for x86 devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/contributing/development/debugging/vulkan/vulkan_validation_layers.rst b/contributing/development/debugging/vulkan/vulkan_validation_layers.rst index 89ae6162a..ad9b49260 100644 --- a/contributing/development/debugging/vulkan/vulkan_validation_layers.rst +++ b/contributing/development/debugging/vulkan/vulkan_validation_layers.rst @@ -3,10 +3,133 @@ Validation layers ================= -Validation layers enable developers to verify their application's correct use -of the Vulkan API. +Validation layers enable developers to verify their application's correct use of +the Vulkan API. Validation layers can be enabled in both debug and release +builds, including in exported projects. -.. _doc_vulkan_validation_layers-android: +.. note:: + + Enabling validation layers has a performance impact, so only enable them + when you actually need the output to debug the application. + +Windows +------- + +Install the Vulkan SDK ``__, which contains +validation layers as part of its default installation. No need to enable any +optional features in the installer; installing the core Vulkan SDK suffices. You +don't need to reboot after installing the SDK, but you may need to close and +reopen your current terminal. + +After installing the Vulkan SDK, run Godot with the ``--gpu-validation`` +:ref:`command line argument `. You can also specify +``--gpu-abort`` which will make Godot quit as soon as a validation error happens. +This can prevent your system from freezing if a validation error occurs. + +macOS +----- + +.. warning:: + + Official Godot macOS builds do **not** support validation layers, as these + are statically linked against the Vulkan SDK. Dynamic linking must be used + instead. + + In practice, this means that using validation layers on macOS **requires** + you to use a Godot build compiled with the ``use_volk=yes`` SCons option. + :ref:`doc_compiling_for_macos`. If testing validation layers on an exported + project, you must recompile the export template and specify it as a custom + export template in your project's macOS export preset. + +Install the Vulkan SDK ``__, which contains +validation layers as part of its default installation. No need to enable any +optional features in the installer; installing the core Vulkan SDK suffices. You +don't need to reboot after installing the SDK, but you may need to close and +reopen your current terminal. + +After installing the Vulkan SDK, run a Godot binary that was compiled with +``use_volk=yes`` SCons option. Specify the ``--gpu-validation`` +:ref:`command line argument `. +You can also specify ``--gpu-abort`` which will make Godot quit as soon +as a validation error happens. This can prevent your system from freezing +if a validation error occurs. + +Linux, \*BSD +------------ + +Install Vulkan validation layers from your distribution's repositories: + +.. tabs:: + + .. tab:: Alpine Linux + + :: + + vulkan-validation-layers + + .. tab:: Arch Linux + + :: + + pacman -S vulkan-validation-layers + + .. tab:: Debian/Ubuntu + + :: + + apt install vulkan-validationlayers + + .. tab:: Fedora + + :: + + dnf install vulkan-validation-layers + + .. tab:: FreeBSD + + :: + + pkg install graphics/vulkan-validation-layers + + .. tab:: Gentoo + + :: + + emerge -an media-libs/vulkan-layers + + .. tab:: Mageia + + :: + + urpmi vulkan-validation-layers + + .. tab:: OpenBSD + + :: + + pkg_add graphics/vulkan-validation-layers + + .. tab:: openSUSE + + :: + + zypper install vulkan-validationlayers + + .. tab:: Solus + + :: + + eopkg install -c vulkan-validation-layers + +You don't need to reboot after installing the validation layers, but you may +need to close and reopen your current terminal. + +After installing the package, run Godot with the ``--gpu-validation`` +:ref:`command line argument `. You can also specify +``--gpu-abort`` which will make Godot quit as soon as a validation error happens. +This can prevent your system from freezing if a validation error occurs. + +.. _doc_vulkan_validation_layers_android: Android ------- @@ -14,6 +137,17 @@ Android After enabling validation layers on Android, a developer can see errors and warning messages in the ``adb logcat`` output. +iOS +--- + +Validation layers are currently **not** supported on iOS. + +Web +--- + +Validation layers are **not** supported on the web platform, as there is no support +for Vulkan there. + Enabling validation layers ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst index 2a7f6fa3c..dc7d9655c 100644 --- a/tutorials/editor/command_line_tutorial.rst +++ b/tutorials/editor/command_line_tutorial.rst @@ -138,7 +138,7 @@ Command line reference +------------------------------+---------------------------------------------------------------------------------------------------------+ | ``--gpu-profile`` | Show a GPU profile of the tasks that took the most time during frame rendering. | +------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--gpu-validation`` | Enable graphics API validation layers for debugging. | +| ``--gpu-validation`` | Enable graphics API :ref:`validation layers ` for debugging. | +------------------------------+---------------------------------------------------------------------------------------------------------+ | ``--gpu-abort`` | Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes. | +------------------------------+---------------------------------------------------------------------------------------------------------+