Bläddra i källkod

Document thread-safe rendering caveats

Hugo Locurcio 3 år sedan
förälder
incheckning
d162f8aaec

+ 10 - 1
tutorials/threads/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
 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.
 (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
 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
 Resources
 ---------
 ---------

+ 5 - 0
tutorials/threads/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
 .. note:: If using other languages (C#, C++), it may be easier to use the
           threading classes they support.
           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
 Creating a Thread
 -----------------
 -----------------