From 61d52c3c5b39a1fc402f98a243431210e8eb5824 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Sat, 9 Oct 2021 11:21:37 +0200 Subject: [PATCH] Document thread-safe rendering caveats --- tutorials/performance/thread_safe_apis.rst | 11 ++++++++++- tutorials/performance/using_multiple_threads.rst | 5 +++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/tutorials/performance/thread_safe_apis.rst b/tutorials/performance/thread_safe_apis.rst index 0a3081d59..ecec63498 100644 --- a/tutorials/performance/thread_safe_apis.rst +++ b/tutorials/performance/thread_safe_apis.rst @@ -49,10 +49,19 @@ you are doing and you are sure that a single resource is not being used or set in multiple ones. Otherwise, you are safer just using the servers API (which is fully thread-safe) directly and not touching scene or resources. +Rendering +--------- + +Instancing nodes that render anything in 2D or 3D (such as Sprite) is *not* thread-safe by default. +To make rendering thread-safe, set the **Rendering > Threads > Thread Model** project setting to **Multi-Threaded**. + +Note that the Multi-Threaded thread model has several known bugs, so it may not be usable +in all scenarios. + GDScript arrays, dictionaries ----------------------------- -In GDScript, reading and writing elements from multiple threads is ok, but anything that changes the container size (resizing, adding or removing elements) requires locking a mutex. +In GDScript, reading and writing elements from multiple threads is OK, but anything that changes the container size (resizing, adding or removing elements) requires locking a mutex. Resources --------- diff --git a/tutorials/performance/using_multiple_threads.rst b/tutorials/performance/using_multiple_threads.rst index b0c3288ea..1c14995be 100644 --- a/tutorials/performance/using_multiple_threads.rst +++ b/tutorials/performance/using_multiple_threads.rst @@ -14,6 +14,11 @@ Godot supports threads and provides many handy functions to use them. .. note:: If using other languages (C#, C++), it may be easier to use the threading classes they support. +.. warning:: + + Before using a built-in class in a thread, read :ref:`doc_thread_safe_apis` + first to check whether it can be safely used in a thread. + Creating a Thread -----------------