瀏覽代碼

Document thread-safe rendering caveats

Hugo Locurcio 3 年之前
父節點
當前提交
d162f8aaec
共有 2 個文件被更改,包括 15 次插入1 次删除
  1. 10 1
      tutorials/threads/thread_safe_apis.rst
  2. 5 0
      tutorials/threads/using_multiple_threads.rst

+ 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
 -----------------
 -----------------