Merge pull request #137 from jss2a98aj/cherry-pick-4.4-docs

[4.4 backport] Assorted documentation improvements

core/io/pck_packer.cpp

@@ -47,12 +47,12 @@ static int _get_pad(int p_alignment, int p_n) {
 }
 
 void PCKPacker::_bind_methods() {
-	ClassDB::bind_method(D_METHOD("pck_start", "pck_name", "alignment", "key", "encrypt_directory"), &PCKPacker::pck_start, DEFVAL(32), DEFVAL("0000000000000000000000000000000000000000000000000000000000000000"), DEFVAL(false));
+	ClassDB::bind_method(D_METHOD("pck_start", "pck_path", "alignment", "key", "encrypt_directory"), &PCKPacker::pck_start, DEFVAL(32), DEFVAL("0000000000000000000000000000000000000000000000000000000000000000"), DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("add_file", "pck_path", "source_path", "encrypt"), &PCKPacker::add_file, DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("flush", "verbose"), &PCKPacker::flush, DEFVAL(false));
 }
 
-Error PCKPacker::pck_start(const String &p_file, int p_alignment, const String &p_key, bool p_encrypt_directory) {
+Error PCKPacker::pck_start(const String &p_pck_path, int p_alignment, const String &p_key, bool p_encrypt_directory) {
 	ERR_FAIL_COND_V_MSG((p_key.is_empty() || !p_key.is_valid_hex_number(false) || p_key.length() != 64), ERR_CANT_CREATE, "Invalid Encryption Key (must be 64 characters long).");
 	ERR_FAIL_COND_V_MSG(p_alignment <= 0, ERR_CANT_CREATE, "Invalid alignment, must be greater then 0.");
 
@@ -83,8 +83,8 @@ Error PCKPacker::pck_start(const String &p_file, int p_alignment, const String &
 	}
 	enc_dir = p_encrypt_directory;
 
-	file = FileAccess::open(p_file, FileAccess::WRITE);
-	ERR_FAIL_COND_V_MSG(file.is_null(), ERR_CANT_CREATE, "Can't open file to write: " + String(p_file) + ".");
+	file = FileAccess::open(p_pck_path, FileAccess::WRITE);
+	ERR_FAIL_COND_V_MSG(file.is_null(), ERR_CANT_CREATE, "Can't open file to write: " + String(p_pck_path) + ".");
 
 	alignment = p_alignment;
 
@@ -106,7 +106,7 @@ Error PCKPacker::pck_start(const String &p_file, int p_alignment, const String &
 	return OK;
 }
 
-Error PCKPacker::add_file(const String &p_file, const String &p_src, bool p_encrypt) {
+Error PCKPacker::add_file(const String &p_pck_path, const String &p_src, bool p_encrypt) {
 	ERR_FAIL_COND_V_MSG(file.is_null(), ERR_INVALID_PARAMETER, "File must be opened before use.");
 
 	Ref<FileAccess> f = FileAccess::open(p_src, FileAccess::READ);
@@ -117,7 +117,7 @@ Error PCKPacker::add_file(const String &p_file, const String &p_src, bool p_encr
 	File pf;
 	// Simplify path here and on every 'files' access so that paths that have extra '/'
 	// symbols in them still match to the MD5 hash for the saved path.
-	pf.path = p_file.simplify_path();
+	pf.path = p_pck_path.simplify_path();
 	pf.src_path = p_src;
 	pf.ofs = ofs;
 	pf.size = f->get_length();

core/io/pck_packer.h

@@ -58,8 +58,8 @@ class PCKPacker : public RefCounted {
 	Vector<File> files;
 
 public:
-	Error pck_start(const String &p_file, int p_alignment = 32, const String &p_key = "0000000000000000000000000000000000000000000000000000000000000000", bool p_encrypt_directory = false);
-	Error add_file(const String &p_file, const String &p_src, bool p_encrypt = false);
+	Error pck_start(const String &p_pck_path, int p_alignment = 32, const String &p_key = "0000000000000000000000000000000000000000000000000000000000000000", bool p_encrypt_directory = false);
+	Error add_file(const String &p_pck_path, const String &p_src, bool p_encrypt = false);
 	Error flush(bool p_verbose = false);
 
 	PCKPacker() {}

doc/classes/AStar2D.xml

@@ -276,7 +276,7 @@
 			<return type="void" />
 			<param index="0" name="num_nodes" type="int" />
 			<description>
-				Reserves space internally for [param num_nodes] points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity.
+				Reserves space internally for [param num_nodes] points. Useful if you're adding a known large number of points at once, such as points on a grid. The new capacity must be greater or equal to the old capacity.
 			</description>
 		</method>
 		<method name="set_point_disabled">

doc/classes/BackBufferCopy.xml

@@ -8,6 +8,7 @@
 		[b]Note:[/b] Since this node inherits from [Node2D] (and not [Control]), anchors and margins won't apply to child [Control]-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control]-derived nodes as [i]siblings[/i] to the [BackBufferCopy] node instead of adding them as children.
 	</description>
 	<tutorials>
+		<link title="Screen-reading shaders">$DOCS_URL/tutorials/shaders/screen-reading_shaders.html</link>
 	</tutorials>
 	<members>
 		<member name="copy_mode" type="int" setter="set_copy_mode" getter="get_copy_mode" enum="BackBufferCopy.CopyMode" default="1">

doc/classes/BaseButton.xml

@@ -57,7 +57,7 @@
 		</member>
 		<member name="button_pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false">
 			If [code]true[/code], the button's state is pressed. Means the button is pressed down or toggled (if [member toggle_mode] is active). Only works if [member toggle_mode] is [code]true[/code].
-			[b]Note:[/b] Setting [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal].
+			[b]Note:[/b] Changing the value of [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal].
 		</member>
 		<member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled">
 			If [code]true[/code], the button is in disabled state and can't be clicked or toggled.

doc/classes/CPUParticles2D.xml

@@ -43,7 +43,7 @@
 			<return type="bool" />
 			<param index="0" name="particle_flag" type="int" enum="CPUParticles2D.ParticleFlags" />
 			<description>
-				Returns the enabled state of the given flag (see [enum ParticleFlags] for options).
+				Returns the enabled state of the given particle flag (see [enum ParticleFlags] for options).
 			</description>
 		</method>
 		<method name="restart">

doc/classes/Callable.xml

@@ -203,7 +203,8 @@
 		<method name="is_null" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if this [Callable] has no target to call the method on.
+				Returns [code]true[/code] if this [Callable] has no target to call the method on. Equivalent to [code]callable == Callable()[/code].
+				[b]Note:[/b] This is [i]not[/i] the same as [code]not is_valid()[/code] and using [code]not is_null()[/code] will [i]not[/i] guarantee that this callable can be called. Use [method is_valid] instead.
 			</description>
 		</method>
 		<method name="is_standard" qualifiers="const">

doc/classes/CameraAttributes.xml

@@ -25,7 +25,9 @@
 			Multiplier for the exposure amount. A higher value results in a brighter image.
 		</member>
 		<member name="exposure_sensitivity" type="float" setter="set_exposure_sensitivity" getter="get_exposure_sensitivity" default="100.0">
-			Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. When [member auto_exposure_enabled] this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop.
+			Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image.
+			If [member auto_exposure_enabled] is [code]true[/code], this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop.
+			[b]Note:[/b] Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled.
 		</member>
 	</members>
 </class>

doc/classes/CanvasItem.xml

@@ -587,6 +587,7 @@
 	<members>
 		<member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0">
 			Allows the current node to clip child nodes, essentially acting as a mask.
+			[b]Note:[/b] Clipping nodes cannot be nested or placed within [CanvasGroup]s. If an ancestor of this node clips its children or is a [CanvasGroup], then this node's clip mode should be set to [constant CLIP_CHILDREN_DISABLED] to avoid unexpected behavior.
 		</member>
 		<member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1">
 			The rendering layers in which this [CanvasItem] responds to [Light2D] nodes.

doc/classes/CharFXTransform.xml

@@ -8,7 +8,6 @@
 	</description>
 	<tutorials>
 		<link title="BBCode in RichTextLabel">$DOCS_URL/tutorials/ui/bbcode_in_richtextlabel.html</link>
-		<link title="RichTextEffect test project (third-party)">https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link>
 	</tutorials>
 	<members>
 		<member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)" keywords="colour">

doc/classes/Compositor.xml

@@ -7,6 +7,7 @@
 		The compositor resource stores attributes used to customize how a [Viewport] is rendered.
 	</description>
 	<tutorials>
+		<link title="The Compositor">$DOCS_URL/tutorials/rendering/compositor.html</link>
 	</tutorials>
 	<members>
 		<member name="compositor_effects" type="CompositorEffect[]" setter="set_compositor_effects" getter="get_compositor_effects" default="[]">

doc/classes/CompositorEffect.xml

@@ -7,6 +7,7 @@
 		This resource defines a custom rendering effect that can be applied to [Viewport]s through the viewports' [Environment]. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic.
 	</description>
 	<tutorials>
+		<link title="The Compositor">$DOCS_URL/tutorials/rendering/compositor.html</link>
 	</tutorials>
 	<methods>
 		<method name="_render_callback" qualifiers="virtual">
@@ -56,6 +57,17 @@
 			var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
 			var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness")
 			[/codeblock]
+			The raw normal and roughness buffer is stored in an optimized format, different than the one available in Spatial shaders. When sampling the buffer, a conversion function must be applied. Use this function, copied from [url=https://github.com/godotengine/godot/blob/da5f39889f155658cef7f7ec3cc1abb94e17d815/servers/rendering/renderer_rd/shaders/forward_clustered/scene_forward_clustered_inc.glsl#L334-L341]here[/url]:
+			[codeblock]
+			vec4 normal_roughness_compatibility(vec4 p_normal_roughness) {
+			    float roughness = p_normal_roughness.w;
+			    if (roughness &gt; 0.5) {
+			        roughness = 1.0 - roughness;
+			    }
+			    roughness /= (127.0 / 255.0);
+			    return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness);
+			}
+			[/codeblock]
 		</member>
 		<member name="needs_separate_specular" type="bool" setter="set_needs_separate_specular" getter="get_needs_separate_specular">
 			If [code]true[/code] this triggers specular data being rendered to a separate buffer and combined after effects have been applied, only applicable for the Forward+ renderer.

doc/classes/Control.xml

@@ -65,7 +65,7 @@
 				[csharp]
 				public override bool _CanDropData(Vector2 atPosition, Variant data)
 				{
-				    return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().ContainsKey("color");
+				    return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("color");
 				}
 
 				public override void _DropData(Vector2 atPosition, Variant data)
@@ -809,9 +809,11 @@
 			<param index="1" name="can_drop_func" type="Callable" />
 			<param index="2" name="drop_func" type="Callable" />
 			<description>
-				Forwards the handling of this control's [method _get_drag_data],  [method _can_drop_data] and [method _drop_data] virtual functions to delegate callables.
-				For each argument, if not empty, the delegate callable is used, otherwise the local (virtual) function is used.
-				The function format for each callable should be exactly the same as the virtual functions described above.
+				Sets the given callables to be used instead of the control's own drag-and-drop virtual methods. If a callable is empty, its respective virtual method is used as normal.
+				The arguments for each callable should be exactly the same as their respective virtual methods, which would be:
+				- [param drag_func] corresponds to [method _get_drag_data] and requires a [Vector2];
+				- [param can_drop_func] corresponds to [method _can_drop_data] and requires both a [Vector2] and a [Variant];
+				- [param drop_func] corresponds to [method _drop_data] and requires both a [Vector2] and a [Variant].
 			</description>
 		</method>
 		<method name="set_drag_preview">

doc/classes/Cubemap.xml

@@ -6,8 +6,27 @@
 	<description>
 		A cubemap is made of 6 textures organized in layers. They are typically used for faking reflections in 3D rendering (see [ReflectionProbe]). It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods.
 		This resource is typically used as a uniform in custom shaders. Few core Godot methods make use of [Cubemap] resources.
-		To create such a texture file yourself, reimport your image files using the Godot Editor import presets.
-		[b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map.
+		To create such a texture file yourself, reimport your image files using the Godot Editor import presets. The expected image order is X+, X-, Y+, Y-, Z+, Z- (in Godot's coordinate system, so Y+ is "up" and Z- is "forward"). You can use one of the following templates as a base:
+		- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_2x3.webp]2×3 cubemap template (default layout option)[/url]
+		- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_3x2.webp]3×2 cubemap template[/url]
+		- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_1x6.webp]1×6 cubemap template[/url]
+		- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_6x1.webp]6×1 cubemap template[/url]
+		[b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. To use a cubemap as a skybox, convert the default [PanoramaSkyMaterial] to a [ShaderMaterial] using the [b]Convert to ShaderMaterial[/b] resource dropdown option, then replace its code with the following:
+		[codeblock lang=text]
+		shader_type sky;
+
+		uniform samplerCube source_panorama : filter_linear, source_color, hint_default_black;
+		uniform float exposure : hint_range(0, 128) = 1.0;
+
+		void sky() {
+		    // If importing a cubemap from another engine, you may need to flip one of the `EYEDIR` components below
+		    // by replacing it with `-EYEDIR`.
+		    vec3 eyedir = vec3(EYEDIR.x, EYEDIR.y, EYEDIR.z);
+		    COLOR = texture(source_panorama, eyedir).rgb * exposure;
+		}
+		[/codeblock]
+		After replacing the shader code and saving, specify the imported Cubemap resource in the Shader Parameters section of the ShaderMaterial in the inspector.
+		Alternatively, you can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map and use [PanoramaSkyMaterial] as usual.
 	</description>
 	<tutorials>
 	</tutorials>

doc/classes/EditorDebuggerPlugin.xml

@@ -15,18 +15,20 @@
 
 		class ExampleEditorDebugger extends EditorDebuggerPlugin:
 
-		    func _has_capture(prefix):
-		        # Return true if you wish to handle message with this prefix.
-		        return prefix == "my_plugin"
+		    func _has_capture(capture):
+		        # Return true if you wish to handle messages with the prefix "my_plugin:".
+		        return capture == "my_plugin"
 
 		    func _capture(message, data, session_id):
 		        if message == "my_plugin:ping":
 		            get_session(session_id).send_message("my_plugin:echo", data)
+		            return true
+		        return false
 
 		    func _setup_session(session_id):
 		        # Add a new tab in the debugger session UI containing a label.
 		        var label = Label.new()
-		        label.name = "Example plugin"
+		        label.name = "Example plugin" # Will be used as the tab title.
 		        label.text = "Example plugin"
 		        var session = get_session(session_id)
 		        # Listens to the session started and stopped signals.
@@ -43,6 +45,24 @@
 		    remove_debugger_plugin(debugger)
 		[/gdscript]
 		[/codeblocks]
+		To connect on the running game side, use the [EngineDebugger] singleton:
+		[codeblocks]
+		[gdscript]
+		extends Node
+
+		func _ready():
+		    EngineDebugger.register_message_capture("my_plugin", _capture)
+		    EngineDebugger.send_message("my_plugin:ping", ["test"])
+
+		func _capture(message, data):
+		    # Note that the "my_plugin:" prefix is not used here.
+		    if message == "echo":
+		        prints("Echo received:", data)
+		        return true
+		    return false
+		[/gdscript]
+		[/codeblocks]
+		[b]Note:[/b] While the game is running, [method @GlobalScope.print] and similar functions [i]called in the editor[/i] do not print anything, the Output Log prints only game messages.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -68,7 +88,7 @@
 			<param index="1" name="data" type="Array" />
 			<param index="2" name="session_id" type="int" />
 			<description>
-				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]).
+				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the [param message]. Use [method get_session] to retrieve the session. This method should return [code]true[/code] if the message is recognized.
 			</description>
 		</method>
 		<method name="_goto_script_line" qualifiers="virtual">
@@ -90,7 +110,7 @@
 			<return type="void" />
 			<param index="0" name="session_id" type="int" />
 			<description>
-				Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage).
+				Override this method to be notified whenever a new [EditorDebuggerSession] is created. Note that the session may be inactive during this stage.
 			</description>
 		</method>
 		<method name="get_session">

doc/classes/EditorDebuggerSession.xml

@@ -14,7 +14,7 @@
 			<return type="void" />
 			<param index="0" name="control" type="Control" />
 			<description>
-				Adds the given [param control] to the debug session UI in the debugger bottom panel.
+				Adds the given [param control] to the debug session UI in the debugger bottom panel. The [param control]'s node name will be used as the tab title.
 			</description>
 		</method>
 		<method name="is_active">

doc/classes/EditorResourcePreviewGenerator.xml

@@ -4,7 +4,7 @@
 		Custom generator of previews.
 	</brief_description>
 	<description>
-		Custom code to generate previews. Please check [code]file_dialog/thumbnail_size[/code] in [EditorSettings] to find out the right size to do previews at.
+		Custom code to generate previews. Check [member EditorSettings.filesystem/file_dialog/thumbnail_size] to find a proper size to generate previews at.
 	</description>
 	<tutorials>
 	</tutorials>