Merge pull request #77202 from YuriSizov/4.0-cherrypicks

Cherry-picks for the 4.0 branch (future 4.0.3) - 5th batch

10 files changed, 65 insertions, 7 deletions

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index 8c84a55ba0..e98419ff8f 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -2436,10 +2436,10 @@
 			Enum value which doesn't correspond to any MIDI message. This is used to initialize [enum MIDIMessage] properties with a generic state.
 		</constant>
 		<constant name="MIDI_MESSAGE_NOTE_OFF" value="8" enum="MIDIMessage">
-			MIDI note OFF message. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs.
+			MIDI note OFF message. Not all MIDI devices send this event; some send [constant MIDI_MESSAGE_NOTE_ON] with zero velocity instead. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs.
 		</constant>
 		<constant name="MIDI_MESSAGE_NOTE_ON" value="9" enum="MIDIMessage">
-			MIDI note ON message. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs.
+			MIDI note ON message. Some MIDI devices send this event with velocity zero instead of [constant MIDI_MESSAGE_NOTE_OFF], but implementations vary. See the documentation of [InputEventMIDI] for information of how to use MIDI inputs.
 		</constant>
 		<constant name="MIDI_MESSAGE_AFTERTOUCH" value="10" enum="MIDIMessage">
 			MIDI aftertouch message. This message is most often sent by pressing down on the key after it "bottoms out".
@@ -2843,10 +2843,10 @@
 			The property is read-only in the [EditorInspector].
 		</constant>
 		<constant name="PROPERTY_USAGE_DEFAULT" value="6" enum="PropertyUsageFlags" is_bitfield="true">
-			Default usage (storage, editor and network).
+			Default usage (storage and editor).
 		</constant>
 		<constant name="PROPERTY_USAGE_NO_EDITOR" value="2" enum="PropertyUsageFlags" is_bitfield="true">
-			Default usage but without showing the property in the editor (storage, network).
+			Default usage but without showing the property in the editor (storage).
 		</constant>
 		<constant name="METHOD_FLAG_NORMAL" value="1" enum="MethodFlags" is_bitfield="true">
 			Flag for a normal method.
diff --git a/doc/classes/InputEventMIDI.xml b/doc/classes/InputEventMIDI.xml
index e4ba380741..513e56dc09 100644
--- a/doc/classes/InputEventMIDI.xml
+++ b/doc/classes/InputEventMIDI.xml
@@ -81,7 +81,8 @@
 			Returns a value indicating the type of message for this MIDI signal. This is a member of the [enum MIDIMessage] enum.
 			For MIDI messages between 0x80 and 0xEF, only the left half of the bits are returned as this value, as the other part is the channel (ex: 0x94 becomes 0x9). For MIDI messages from 0xF0 to 0xFF, the value is returned as-is.
 			Notes will return [constant MIDI_MESSAGE_NOTE_ON] when activated, but they might not always return [constant MIDI_MESSAGE_NOTE_OFF] when deactivated, therefore your code should treat the input as stopped if some period of time has passed.
-			For more information, see the MIDI message status byte list chart linked above.
+			Some MIDI devices may send [constant MIDI_MESSAGE_NOTE_ON] with zero velocity instead of [constant MIDI_MESSAGE_NOTE_OFF].
+			For more information, see the note in [member velocity] and the MIDI message status byte list chart linked above.
 		</member>
 		<member name="pitch" type="int" setter="set_pitch" getter="get_pitch" default="0">
 			The pitch index number of this MIDI signal. This value ranges from 0 to 127. On a piano, middle C is 60, and A440 is 69, see the "MIDI note" column of the piano key frequency chart on Wikipedia for more information.
@@ -90,7 +91,8 @@
 			The pressure of the MIDI signal. This value ranges from 0 to 127. For many devices, this value is always zero.
 		</member>
 		<member name="velocity" type="int" setter="set_velocity" getter="get_velocity" default="0">
-			The velocity of the MIDI signal. This value ranges from 0 to 127. For a piano, this corresponds to how quickly the key was pressed, and is rarely above about 110 in practice. Note that some MIDI devices may send a [constant MIDI_MESSAGE_NOTE_ON] message with zero velocity and expect this to be treated the same as a [constant MIDI_MESSAGE_NOTE_OFF] message, but device implementations vary so Godot reports event data exactly as received.
+			The velocity of the MIDI signal. This value ranges from 0 to 127. For a piano, this corresponds to how quickly the key was pressed, and is rarely above about 110 in practice.
+			[b]Note:[/b] Some MIDI devices may send a [constant MIDI_MESSAGE_NOTE_ON] message with zero velocity and expect this to be treated the same as a [constant MIDI_MESSAGE_NOTE_OFF] message, but device implementations vary so Godot reports event data exactly as received. Depending on the hardware and the needs of the game/app, this MIDI quirk can be handled robustly with a couple lines of script (check for [constant MIDI_MESSAGE_NOTE_ON] with velocity zero).
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/PlaceholderCubemap.xml b/doc/classes/PlaceholderCubemap.xml
index 0892b023a2..a44799489c 100644
--- a/doc/classes/PlaceholderCubemap.xml
+++ b/doc/classes/PlaceholderCubemap.xml
@@ -7,6 +7,7 @@
 		This class is used when loading a project that uses a [Cubemap] subclass in 2 conditions:
 		- When running the project exported in dedicated server mode, only the texture's dimensions are kept (as they may be relied upon for gameplay purposes or positioning of other elements). This allows reducing the exported PCK's size significantly.
 		- When this subclass is missing due to using a different engine version or build (e.g. modules disabled).
+		[b]Note:[/b] This is not intended to be used as an actual texture for rendering. It is not guaranteed to work like one in shaders or materials (for example when calculating UV).
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/PlaceholderCubemapArray.xml b/doc/classes/PlaceholderCubemapArray.xml
index c7a7e9154c..ff9f172476 100644
--- a/doc/classes/PlaceholderCubemapArray.xml
+++ b/doc/classes/PlaceholderCubemapArray.xml
@@ -7,6 +7,7 @@
 		This class is used when loading a project that uses a [CubemapArray] subclass in 2 conditions:
 		- When running the project exported in dedicated server mode, only the texture's dimensions are kept (as they may be relied upon for gameplay purposes or positioning of other elements). This allows reducing the exported PCK's size significantly.
 		- When this subclass is missing due to using a different engine version or build (e.g. modules disabled).
+		[b]Note:[/b] This is not intended to be used as an actual texture for rendering. It is not guaranteed to work like one in shaders or materials (for example when calculating UV).
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/PlaceholderTexture2D.xml b/doc/classes/PlaceholderTexture2D.xml
index c889055e4d..f6a1e4bc25 100644
--- a/doc/classes/PlaceholderTexture2D.xml
+++ b/doc/classes/PlaceholderTexture2D.xml
@@ -7,6 +7,7 @@
 		This class is used when loading a project that uses a [Texture2D] subclass in 2 conditions:
 		- When running the project exported in dedicated server mode, only the texture's dimensions are kept (as they may be relied upon for gameplay purposes or positioning of other elements). This allows reducing the exported PCK's size significantly.
 		- When this subclass is missing due to using a different engine version or build (e.g. modules disabled).
+		[b]Note:[/b] This is not intended to be used as an actual texture for rendering. It is not guaranteed to work like one in shaders or materials (for example when calculating UV).
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/PlaceholderTexture2DArray.xml b/doc/classes/PlaceholderTexture2DArray.xml
index a749e8c039..e5a699c7c5 100644
--- a/doc/classes/PlaceholderTexture2DArray.xml
+++ b/doc/classes/PlaceholderTexture2DArray.xml
@@ -7,6 +7,7 @@
 		This class is used when loading a project that uses a [Texture2D] subclass in 2 conditions:
 		- When running the project exported in dedicated server mode, only the texture's dimensions are kept (as they may be relied upon for gameplay purposes or positioning of other elements). This allows reducing the exported PCK's size significantly.
 		- When this subclass is missing due to using a different engine version or build (e.g. modules disabled).
+		[b]Note:[/b] This is not intended to be used as an actual texture for rendering. It is not guaranteed to work like one in shaders or materials (for example when calculating UV).
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/PlaceholderTexture3D.xml b/doc/classes/PlaceholderTexture3D.xml
index ccd3c94fc2..81a1743f5b 100644
--- a/doc/classes/PlaceholderTexture3D.xml
+++ b/doc/classes/PlaceholderTexture3D.xml
@@ -7,6 +7,7 @@
 		This class is used when loading a project that uses a [Texture3D] subclass in 2 conditions:
 		- When running the project exported in dedicated server mode, only the texture's dimensions are kept (as they may be relied upon for gameplay purposes or positioning of other elements). This allows reducing the exported PCK's size significantly.
 		- When this subclass is missing due to using a different engine version or build (e.g. modules disabled).
+		[b]Note:[/b] This is not intended to be used as an actual texture for rendering. It is not guaranteed to work like one in shaders or materials (for example when calculating UV).
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/PlaceholderTextureLayered.xml b/doc/classes/PlaceholderTextureLayered.xml
index 8cc6dd606a..36013159d3 100644
--- a/doc/classes/PlaceholderTextureLayered.xml
+++ b/doc/classes/PlaceholderTextureLayered.xml
@@ -7,6 +7,7 @@
 		This class is used when loading a project that uses a [TextureLayered] subclass in 2 conditions:
 		- When running the project exported in dedicated server mode, only the texture's dimensions are kept (as they may be relied upon for gameplay purposes or positioning of other elements). This allows reducing the exported PCK's size significantly.
 		- When this subclass is missing due to using a different engine version or build (e.g. modules disabled).
+		[b]Note:[/b] This is not intended to be used as an actual texture for rendering. It is not guaranteed to work like one in shaders or materials (for example when calculating UV).
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/ViewportTexture.xml b/doc/classes/ViewportTexture.xml
index 36390863cf..8ecda45bd6 100644
--- a/doc/classes/ViewportTexture.xml
+++ b/doc/classes/ViewportTexture.xml
@@ -17,7 +17,6 @@
 	<members>
 		<member name="viewport_path" type="NodePath" setter="set_viewport_path_in_scene" getter="get_viewport_path_in_scene" default="NodePath(&quot;&quot;)">
 			The path to the [Viewport] node to display. This is relative to the scene root, not to the node which uses the texture.
-			[b]Note:[/b] In the editor, it is automatically updated when the target viewport's node path changes due to renaming or moving the viewport or its ancestors. At runtime, it may not be able to automatically update due to the inability to determine the scene root.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/WorkerThreadPool.xml b/doc/classes/WorkerThreadPool.xml
index fced54ae7f..887dfbdcc0 100644
--- a/doc/classes/WorkerThreadPool.xml
+++ b/doc/classes/WorkerThreadPool.xml
@@ -1,10 +1,50 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="WorkerThreadPool" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		A singleton that allocates some [Thread]s on startup, used to offload tasks to these threads.
 	</brief_description>
 	<description>
+		The [WorkerThreadPool] singleton allocates a set of [Thread]s (called worker threads) on project startup and provides methods for offloading tasks to them. This can be used for simple multithreading without having to create [Thread]s.
+		Tasks hold the [Callable] to be run by the threads. [WorkerThreadPool] can be used to create regular tasks, which will be taken by one worker thread, or group tasks, which can be distributed between multiple worker threads. Group tasks execute the [Callable] multiple times, which makes them useful for iterating over a lot of elements, such as the enemies in an arena.
+		Here's a sample on how to offload an expensive function to worker threads:
+		[codeblocks]
+		[gdscript]
+		var enemies = [] # An array to be filled with enemies.
+
+		func process_enemy_ai(enemy_index):
+		    var processed_enemy = enemies[enemy_index]
+		    # Expensive logic...
+
+		func _process(delta):
+		    var task_id = WorkerThreadPool.add_group_task(process_enemy_ai, enemies.size())
+		    # Other code...
+		    WorkerThreadPool.wait_for_group_task_completion(task_id)
+		    # Other code that depends on the enemy AI already being processed.
+		[/gdscript]
+		[csharp]
+		private List&lt;Node&gt; _enemies = new List&lt;Node&gt;(); // A list to be filled with enemies.
+
+		private void ProcessEnemyAI(int enemyIndex)
+		{
+		    Node processedEnemy = _enemies[enemyIndex];
+		    // Expensive logic here.
+		}
+
+		public override void _Process(double delta)
+		{
+		    long taskId = WorkerThreadPool.AddGroupTask(Callable.From&lt;int&gt;(ProcessEnemyAI), _enemies.Count);
+		    // Other code...
+		    WorkerThreadPool.WaitForGroupTaskCompletion(taskId);
+		    // Other code that depends on the enemy AI already being processed.
+		}
+		[/csharp]
+		[/codeblocks]
+		The above code relies on the number of elements in the [code]enemies[/code] array remaining constant during the multithreaded part.
+		[b]Note:[/b] Using this singleton could affect performance negatively if the task being distributed between threads is not computationally expensive.
 	</description>
 	<tutorials>
+		<link title="Using multiple threads">$DOCS_URL/tutorials/performance/using_multiple_threads.html</link>
+		<link title="Thread-safe APIs">$DOCS_URL/tutorials/performance/thread_safe_apis.html</link>
 	</tutorials>
 	<methods>
 		<method name="add_group_task">
@@ -15,6 +55,9 @@
 			<param index="3" name="high_priority" type="bool" default="false" />
 			<param index="4" name="description" type="String" default="&quot;&quot;" />
 			<description>
+				Adds [param action] as a group task to be executed by the worker threads. The [Callable] will be called a number of times based on [param elements], with the first thread calling it with the value [code]0[/code] as a parameter, and each consecutive execution incrementing this value by 1 until it reaches [code]element - 1[/code].
+				The number of threads the task is distributed to is defined by [param tasks_needed], where the default value [code]-1[/code] means it is distributed to all worker threads. [param high_priority] determines if the task has a high priority or a low priority (default). You can optionally provide a [param description] to help with debugging.
+				Returns a group task ID that can be used by other methods.
 			</description>
 		</method>
 		<method name="add_task">
@@ -23,36 +66,44 @@
 			<param index="1" name="high_priority" type="bool" default="false" />
 			<param index="2" name="description" type="String" default="&quot;&quot;" />
 			<description>
+				Adds [param action] as a task to be executed by a worker thread. [param high_priority] determines if the task has a high priority or a low priority (default). You can optionally provide a [param description] to help with debugging.
+				Returns a task ID that can be used by other methods.
 			</description>
 		</method>
 		<method name="get_group_processed_element_count" qualifiers="const">
 			<return type="int" />
 			<param index="0" name="group_id" type="int" />
 			<description>
+				Returns how many times the [Callable] of the group task with the given ID has already been executed by the worker threads.
+				[b]Note:[/b] If a thread has started executing the [Callable] but is yet to finish, it won't be counted.
 			</description>
 		</method>
 		<method name="is_group_task_completed" qualifiers="const">
 			<return type="bool" />
 			<param index="0" name="group_id" type="int" />
 			<description>
+				Returns [code]true[/code] if the group task with the given ID is completed.
 			</description>
 		</method>
 		<method name="is_task_completed" qualifiers="const">
 			<return type="bool" />
 			<param index="0" name="task_id" type="int" />
 			<description>
+				Returns [code]true[/code] if the task with the given ID is completed.
 			</description>
 		</method>
 		<method name="wait_for_group_task_completion">
 			<return type="void" />
 			<param index="0" name="group_id" type="int" />
 			<description>
+				Pauses the thread that calls this method until the group task with the given ID is completed.
 			</description>
 		</method>
 		<method name="wait_for_task_completion">
 			<return type="void" />
 			<param index="0" name="task_id" type="int" />
 			<description>
+				Pauses the thread that calls this method until the task with the given ID is completed.
 			</description>
 		</method>
 	</methods>