diff options
Diffstat (limited to 'doc')
44 files changed, 275 insertions, 80 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 4c0f89f14d..93439b82f9 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -221,6 +221,17 @@ [/codeblock] </description> </method> + <method name="cubic_interpolate"> + <return type="float" /> + <argument index="0" name="from" type="float" /> + <argument index="1" name="to" type="float" /> + <argument index="2" name="pre" type="float" /> + <argument index="3" name="post" type="float" /> + <argument index="4" name="weight" type="float" /> + <description> + Cubic interpolates between two values by the factor defined in [code]weight[/code] with pre and post values. + </description> + </method> <method name="db2linear"> <return type="float" /> <argument index="0" name="db" type="float" /> diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 57f51c7ccf..a7de570a5e 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -299,8 +299,8 @@ <method name="hash" qualifiers="const"> <return type="int" /> <description> - Returns a hashed integer value representing the array and its contents. - [b]Note:[/b] Arrays with equal contents can still produce different hashes. Only the exact same arrays will produce the same hashed integer value. + Returns a hashed 32-bit integer value representing the array and its contents. + [b]Note:[/b] [Array]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the arrays are equal, because different arrays can have identical hash values due to hash collisions. </description> </method> <method name="insert"> diff --git a/doc/classes/ArrayOccluder3D.xml b/doc/classes/ArrayOccluder3D.xml index 993393cf50..cb682a7e62 100644 --- a/doc/classes/ArrayOccluder3D.xml +++ b/doc/classes/ArrayOccluder3D.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="ArrayOccluder3D" inherits="Occluder3D" version="4.0"> <brief_description> + 3D polygon shape for use with occlusion culling in [OccluderInstance3D]. </brief_description> <description> + [ArrayOccluder3D] stores an arbitrary 3D polygon shape that can be used by the engine's occlusion culling system. This is analogous to [ArrayMesh], but for occluders. + See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling. </description> <tutorials> </tutorials> diff --git a/doc/classes/AudioStreamPlayer2D.xml b/doc/classes/AudioStreamPlayer2D.xml index 0ad161a6fe..30e23820cf 100644 --- a/doc/classes/AudioStreamPlayer2D.xml +++ b/doc/classes/AudioStreamPlayer2D.xml @@ -47,7 +47,7 @@ </methods> <members> <member name="area_mask" type="int" setter="set_area_mask" getter="get_area_mask" default="1"> - Areas in which this sound plays. + Determines which [Area2D] layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream]s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater. </member> <member name="attenuation" type="float" setter="set_attenuation" getter="get_attenuation" default="1.0"> Dampens audio over distance with this as an exponent. diff --git a/doc/classes/AudioStreamPlayer3D.xml b/doc/classes/AudioStreamPlayer3D.xml index ce8a6693db..52f9e23d98 100644 --- a/doc/classes/AudioStreamPlayer3D.xml +++ b/doc/classes/AudioStreamPlayer3D.xml @@ -48,7 +48,7 @@ </methods> <members> <member name="area_mask" type="int" setter="set_area_mask" getter="get_area_mask" default="1"> - Areas in which this sound plays. + Determines which [Area3D] layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream]s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater. </member> <member name="attenuation_filter_cutoff_hz" type="float" setter="set_attenuation_filter_cutoff_hz" getter="get_attenuation_filter_cutoff_hz" default="5000.0"> Dampens audio using a low-pass filter above this frequency, in Hz. To disable the dampening effect entirely, set this to [code]20500[/code] as this frequency is above the human hearing limit. diff --git a/doc/classes/BoxOccluder3D.xml b/doc/classes/BoxOccluder3D.xml index 8c3b597193..d16cf55098 100644 --- a/doc/classes/BoxOccluder3D.xml +++ b/doc/classes/BoxOccluder3D.xml @@ -1,13 +1,17 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="BoxOccluder3D" inherits="Occluder3D" version="4.0"> <brief_description> + Cuboid shape for use with occlusion culling in [OccluderInstance3D]. </brief_description> <description> + [BoxOccluder3D] stores a cuboid shape that can be used by the engine's occlusion culling system. + See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling. </description> <tutorials> </tutorials> <members> <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(1, 1, 1)"> + The box's size in 3D units. </member> </members> </class> diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml index 2d3571e36c..f319f338ed 100644 --- a/doc/classes/Callable.xml +++ b/doc/classes/Callable.xml @@ -98,7 +98,8 @@ <method name="hash" qualifiers="const"> <return type="int" /> <description> - Returns the hash value of this [Callable]'s object. + Returns the 32-bit hash value of this [Callable]'s object. + [b]Note:[/b] [Callable]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for [method hash]. </description> </method> <method name="is_custom" qualifiers="const"> diff --git a/doc/classes/CodeEdit.xml b/doc/classes/CodeEdit.xml index 09696d4d2a..0e4e6ed258 100644 --- a/doc/classes/CodeEdit.xml +++ b/doc/classes/CodeEdit.xml @@ -589,7 +589,7 @@ <theme_item name="completion_font_color" data_type="color" type="Color" default="Color(0.67, 0.67, 0.67, 1)"> Font [Color] for the code completion popup. </theme_item> - <theme_item name="completion_scroll_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + <theme_item name="completion_scroll_color" data_type="color" type="Color" default="Color(1, 1, 1, 0.29)"> [Color] of the scrollbar in the code completion popup. </theme_item> <theme_item name="completion_selected_color" data_type="color" type="Color" default="Color(0.26, 0.26, 0.27, 1)"> @@ -640,7 +640,7 @@ <theme_item name="completion_max_width" data_type="constant" type="int" default="50"> Max width of options in the code completion popup. Options longer then this will be cut off. </theme_item> - <theme_item name="completion_scroll_width" data_type="constant" type="int" default="3"> + <theme_item name="completion_scroll_width" data_type="constant" type="int" default="6"> Width of the scrollbar in the code completion popup. </theme_item> <theme_item name="line_spacing" data_type="constant" type="int" default="4"> diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index 4e73d4d9d8..8fd01509ec 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -221,14 +221,15 @@ Returns a new color from [code]rgba[/code], an HTML hexadecimal color string. [code]rgba[/code] is not case sensitive, and may be prefixed with a '#' character. [code]rgba[/code] must be a valid three-digit or six-digit hexadecimal color string, and may contain an alpha channel value. If [code]rgba[/code] does not contain an alpha channel value, an alpha channel value of 1.0 is applied. If [code]rgba[/code] is invalid a Color(0.0, 0.0, 0.0, 1.0) is returned. + [b]Note:[/b] This method is not implemented in C#, but the same functionality is provided in the class constructor. [codeblocks] [gdscript] var green = Color.html("#00FF00FF") # set green to Color(0.0, 1.0, 0.0, 1.0) var blue = Color.html("#0000FF") # set blue to Color(0.0, 0.0, 1.0, 1.0) [/gdscript] [csharp] - var green = Color.Html("#00FF00FF"); // set green to Color(0.0, 1.0, 0.0, 1.0) - var blue = Color.Html("#0000FF"); // set blue to Color(0.0, 0.0, 1.0, 1.0) + var green = new Color("#00FF00FF"); // set green to Color(0.0, 1.0, 0.0, 1.0) + var blue = new Color("#0000FF"); // set blue to Color(0.0, 0.0, 1.0, 1.0) [/csharp] [/codeblocks] </description> diff --git a/doc/classes/ColorPicker.xml b/doc/classes/ColorPicker.xml index cb543afaba..245791cdc7 100644 --- a/doc/classes/ColorPicker.xml +++ b/doc/classes/ColorPicker.xml @@ -116,8 +116,6 @@ <theme_item name="color_hue" data_type="icon" type="Texture2D"> Custom texture for the hue selection slider on the right. </theme_item> - <theme_item name="color_sample" data_type="icon" type="Texture2D"> - </theme_item> <theme_item name="overbright_indicator" data_type="icon" type="Texture2D"> The indicator used to signalize that the color value is outside the 0-1 range. </theme_item> diff --git a/doc/classes/Container.xml b/doc/classes/Container.xml index 83655425fc..076a800e29 100644 --- a/doc/classes/Container.xml +++ b/doc/classes/Container.xml @@ -10,6 +10,20 @@ <tutorials> </tutorials> <methods> + <method name="_get_allowed_size_flags_horizontal" qualifiers="virtual const"> + <return type="PackedInt32Array" /> + <description> + Implement to return a list of allowed horizontal [enum Control.SizeFlags] for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the inspector dock. + [b]Note:[/b] Having no size flags is equal to having [constant Control.SIZE_SHRINK_BEGIN]. As such, this value is always implicitly allowed. + </description> + </method> + <method name="_get_allowed_size_flags_vertical" qualifiers="virtual const"> + <return type="PackedInt32Array" /> + <description> + Implement to return a list of allowed vertical [enum Control.SizeFlags] for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the inspector dock. + [b]Note:[/b] Having no size flags is equal to having [constant Control.SIZE_SHRINK_BEGIN]. As such, this value is always implicitly allowed. + </description> + </method> <method name="fit_child_in_rect"> <return type="void" /> <argument index="0" name="child" type="Control" /> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index b6c2dac33c..f2d727bb51 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -1278,20 +1278,24 @@ <constant name="PRESET_MODE_KEEP_SIZE" value="3" enum="LayoutPresetMode"> The control's size will not change. </constant> + <constant name="SIZE_SHRINK_BEGIN" value="0" enum="SizeFlags"> + Tells the parent [Container] to align the node with its start, either the top or the left edge. It is mutually exclusive with [constant SIZE_FILL] and other shrink size flags, but can be used with [constant SIZE_EXPAND] in some containers. Use with [member size_flags_horizontal] and [member size_flags_vertical]. + [b]Note:[/b] Setting this flag is equal to not having any size flags. + </constant> <constant name="SIZE_FILL" value="1" enum="SizeFlags"> - Tells the parent [Container] to expand the bounds of this node to fill all the available space without pushing any other node. Use with [member size_flags_horizontal] and [member size_flags_vertical]. + Tells the parent [Container] to expand the bounds of this node to fill all the available space without pushing any other node. It is mutually exclusive with shrink size flags. Use with [member size_flags_horizontal] and [member size_flags_vertical]. </constant> <constant name="SIZE_EXPAND" value="2" enum="SizeFlags"> Tells the parent [Container] to let this node take all the available space on the axis you flag. If multiple neighboring nodes are set to expand, they'll share the space based on their stretch ratio. See [member size_flags_stretch_ratio]. Use with [member size_flags_horizontal] and [member size_flags_vertical]. </constant> <constant name="SIZE_EXPAND_FILL" value="3" enum="SizeFlags"> - Sets the node's size flags to both fill and expand. See the 2 constants above for more information. + Sets the node's size flags to both fill and expand. See [constant SIZE_FILL] and [constant SIZE_EXPAND] for more information. </constant> <constant name="SIZE_SHRINK_CENTER" value="4" enum="SizeFlags"> - Tells the parent [Container] to center the node in itself. It centers the control based on its bounding box, so it doesn't work with the fill or expand size flags. Use with [member size_flags_horizontal] and [member size_flags_vertical]. + Tells the parent [Container] to center the node in the available space. It is mutually exclusive with [constant SIZE_FILL] and other shrink size flags, but can be used with [constant SIZE_EXPAND] in some containers. Use with [member size_flags_horizontal] and [member size_flags_vertical]. </constant> <constant name="SIZE_SHRINK_END" value="8" enum="SizeFlags"> - Tells the parent [Container] to align the node with its end, either the bottom or the right edge. It doesn't work with the fill or expand size flags. Use with [member size_flags_horizontal] and [member size_flags_vertical]. + Tells the parent [Container] to align the node with its end, either the bottom or the right edge. It is mutually exclusive with [constant SIZE_FILL] and other shrink size flags, but can be used with [constant SIZE_EXPAND] in some containers. Use with [member size_flags_horizontal] and [member size_flags_vertical]. </constant> <constant name="MOUSE_FILTER_STOP" value="0" enum="MouseFilter"> The control will receive mouse button input events through [method _gui_input] if clicked on. And the control will receive the [signal mouse_entered] and [signal mouse_exited] signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index 7218e3bcb0..74942dc829 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -259,7 +259,7 @@ <method name="hash" qualifiers="const"> <return type="int" /> <description> - Returns a hashed integer value representing the dictionary contents. This can be used to compare dictionaries by value: + Returns a hashed 32-bit integer value representing the dictionary contents. This can be used to compare dictionaries by value: [codeblocks] [gdscript] var dict1 = {0: 10} @@ -276,6 +276,7 @@ [/csharp] [/codeblocks] [b]Note:[/b] Dictionaries with the same keys/values but in a different order will have a different hash. + [b]Note:[/b] Dictionaries with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the dictionaries are equal, because different dictionaries can have identical hash values due to hash collisions. </description> </method> <method name="is_empty" qualifiers="const"> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 281c218d0d..a6b854e36a 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -403,8 +403,14 @@ <return type="float" /> <argument index="0" name="screen" type="int" default="-1" /> <description> - Returns the current refresh rate of the specified screen. If [code]screen[/code] is [code]SCREEN_OF_MAIN_WINDOW[/code] (the default value), a screen with the main window will be used. - [b]Note:[/b] Returns [code]60.0[/code] if the DisplayServer fails to find the refresh rate for the specified screen. On HTML5, [method screen_get_refresh_rate] will always return [code]60.0[/code] as there is no way to retrieve the refresh rate on that platform. + Returns the current refresh rate of the specified screen. If [code]screen[/code] is [constant SCREEN_OF_MAIN_WINDOW] (the default value), a screen with the main window will be used. + [b]Note:[/b] Returns [code]-1.0[/code] if the DisplayServer fails to find the refresh rate for the specified screen. On HTML5, [method screen_get_refresh_rate] will always return [code]-1.0[/code] as there is no way to retrieve the refresh rate on that platform. + To fallback to a default refresh rate if the method fails, try: + [codeblock] + var refresh_rate = DisplayServer.screen_get_refresh_rate() + if refresh_rate < 0: + refresh_rate = 60.0 + [/codeblock] </description> </method> <method name="screen_get_scale" qualifiers="const"> @@ -638,6 +644,16 @@ <description> </description> </method> + <method name="window_set_exclusive"> + <return type="void" /> + <argument index="0" name="window_id" type="int" /> + <argument index="1" name="exclusive" type="bool" /> + <description> + If set to [code]true[/code], this window will always stay on top of its parent window, parent window will ignore input while this window is opened. + [b]Note:[/b] On macOS, exclusive windows are confined to the same space (virtual desktop or screen) as the parent window. + [b]Note:[/b] This method is implemented on macOS and Windows. + </description> + </method> <method name="window_set_flag"> <return type="void" /> <argument index="0" name="flag" type="int" enum="DisplayServer.WindowFlags" /> diff --git a/doc/classes/EngineDebugger.xml b/doc/classes/EngineDebugger.xml index 861053b1c9..3c2f735e72 100644 --- a/doc/classes/EngineDebugger.xml +++ b/doc/classes/EngineDebugger.xml @@ -65,14 +65,9 @@ <method name="register_profiler"> <return type="void" /> <argument index="0" name="name" type="StringName" /> - <argument index="1" name="toggle" type="Callable" /> - <argument index="2" name="add" type="Callable" /> - <argument index="3" name="tick" type="Callable" /> + <argument index="1" name="profiler" type="EngineProfiler" /> <description> - Registers a profiler with the given [code]name[/code]. - [code]toggle[/code] callable is called when the profiler is enabled/disabled. It must take an argument array as an argument. - [code]add[/code] callable is called when data is added to profiler using [method EngineDebugger.profiler_add_frame_data]. It must take a data array as argument. - [code]tick[/code] callable is called at every active profiler iteration. It must take frame time, idle time, physics time, and physics idle time as arguments. + Registers a profiler with the given [code]name[/code]. See [EngineProfiler] for more information. </description> </method> <method name="send_message"> diff --git a/doc/classes/EngineProfiler.xml b/doc/classes/EngineProfiler.xml new file mode 100644 index 0000000000..60817338b8 --- /dev/null +++ b/doc/classes/EngineProfiler.xml @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="EngineProfiler" inherits="RefCounted" version="4.0"> + <brief_description> + Base class for creating custom profilers. + </brief_description> + <description> + This class can be used to implement custom profilers that are able to interact with the engine and editor debugger. + See [EngineDebugger] and [EditorDebuggerPlugin] for more information. + </description> + <tutorials> + </tutorials> + <methods> + <method name="_add_frame" qualifiers="virtual"> + <return type="void" /> + <argument index="0" name="data" type="Array" /> + <description> + Called when data is added to profiler using [method EngineDebugger.profiler_add_frame_data]. + </description> + </method> + <method name="_tick" qualifiers="virtual"> + <return type="void" /> + <argument index="0" name="frame_time" type="float" /> + <argument index="1" name="idle_time" type="float" /> + <argument index="2" name="physics_time" type="float" /> + <argument index="3" name="physics_frame_time" type="float" /> + <description> + Called once every engine iteration when the profiler is active with information about the current frame. + </description> + </method> + <method name="_toggle" qualifiers="virtual"> + <return type="void" /> + <argument index="0" name="enable" type="bool" /> + <argument index="1" name="options" type="Array" /> + <description> + Called when the profiler is enabled/disabled, along with a set of [code]options[/code]. + </description> + </method> + </methods> +</class> diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index c8c0494378..619ff06c02 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -57,7 +57,8 @@ The ambient light's energy. The higher the value, the stronger the light. </member> <member name="ambient_light_sky_contribution" type="float" setter="set_ambient_light_sky_contribution" getter="get_ambient_light_sky_contribution" default="1.0"> - Defines the amount of light that the sky brings on the scene. A value of 0 means that the sky's light emission has no effect on the scene illumination, thus all ambient illumination is provided by the ambient light. On the contrary, a value of 1 means that all the light that affects the scene is provided by the sky, thus the ambient light parameter has no effect on the scene. + Defines the amount of light that the sky brings on the scene. A value of [code]0.0[/code] means that the sky's light emission has no effect on the scene illumination, thus all ambient illumination is provided by the ambient light. On the contrary, a value of [code]1.0[/code] means that [i]all[/i] the light that affects the scene is provided by the sky, thus the ambient light parameter has no effect on the scene. + [b]Note:[/b] [member ambient_light_sky_contribution] is internally clamped between [code]0.0[/code] and [code]1.0[/code] (inclusive). </member> <member name="ambient_light_source" type="int" setter="set_ambient_source" getter="get_ambient_source" enum="Environment.AmbientSource" default="0"> </member> @@ -171,11 +172,11 @@ </member> <member name="reflected_light_source" type="int" setter="set_reflection_source" getter="get_reflection_source" enum="Environment.ReflectionSource" default="0"> </member> - <member name="sdfgi_bounce_feedback" type="float" setter="set_sdfgi_bounce_feedback" getter="get_sdfgi_bounce_feedback" default="0.0"> + <member name="sdfgi_bounce_feedback" type="float" setter="set_sdfgi_bounce_feedback" getter="get_sdfgi_bounce_feedback" default="0.5"> </member> <member name="sdfgi_cascade0_distance" type="float" setter="set_sdfgi_cascade0_distance" getter="get_sdfgi_cascade0_distance" default="12.8"> </member> - <member name="sdfgi_cascades" type="int" setter="set_sdfgi_cascades" getter="get_sdfgi_cascades" default="6"> + <member name="sdfgi_cascades" type="int" setter="set_sdfgi_cascades" getter="get_sdfgi_cascades" default="4"> The number of cascades to use for SDFGI (between 1 and 8). A higher number of cascades allows displaying SDFGI further away while preserving detail up close, at the cost of performance. When using SDFGI on small-scale levels, [member sdfgi_cascades] can often be decreased between [code]1[/code] and [code]4[/code] to improve performance. </member> <member name="sdfgi_enabled" type="bool" setter="set_sdfgi_enabled" getter="is_sdfgi_enabled" default="false"> @@ -185,7 +186,7 @@ </member> <member name="sdfgi_energy" type="float" setter="set_sdfgi_energy" getter="get_sdfgi_energy" default="1.0"> </member> - <member name="sdfgi_max_distance" type="float" setter="set_sdfgi_max_distance" getter="get_sdfgi_max_distance" default="819.2"> + <member name="sdfgi_max_distance" type="float" setter="set_sdfgi_max_distance" getter="get_sdfgi_max_distance" default="204.8"> </member> <member name="sdfgi_min_cell_size" type="float" setter="set_sdfgi_min_cell_size" getter="get_sdfgi_min_cell_size" default="0.2"> </member> @@ -193,11 +194,11 @@ </member> <member name="sdfgi_probe_bias" type="float" setter="set_sdfgi_probe_bias" getter="get_sdfgi_probe_bias" default="1.1"> </member> - <member name="sdfgi_read_sky_light" type="bool" setter="set_sdfgi_read_sky_light" getter="is_sdfgi_reading_sky_light" default="false"> + <member name="sdfgi_read_sky_light" type="bool" setter="set_sdfgi_read_sky_light" getter="is_sdfgi_reading_sky_light" default="true"> </member> <member name="sdfgi_use_occlusion" type="bool" setter="set_sdfgi_use_occlusion" getter="is_sdfgi_using_occlusion" default="false"> </member> - <member name="sdfgi_y_scale" type="int" setter="set_sdfgi_y_scale" getter="get_sdfgi_y_scale" enum="Environment.SDFGIYScale" default="0"> + <member name="sdfgi_y_scale" type="int" setter="set_sdfgi_y_scale" getter="get_sdfgi_y_scale" enum="Environment.SDFGIYScale" default="1"> </member> <member name="sky" type="Sky" setter="set_sky" getter="get_sky"> The [Sky] resource used for this [Environment]. @@ -379,11 +380,11 @@ <constant name="GLOW_BLEND_MODE_MIX" value="4" enum="GlowBlendMode"> Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect. </constant> - <constant name="SDFGI_Y_SCALE_DISABLED" value="0" enum="SDFGIYScale"> + <constant name="SDFGI_Y_SCALE_50_PERCENT" value="0" enum="SDFGIYScale"> </constant> <constant name="SDFGI_Y_SCALE_75_PERCENT" value="1" enum="SDFGIYScale"> </constant> - <constant name="SDFGI_Y_SCALE_50_PERCENT" value="2" enum="SDFGIYScale"> + <constant name="SDFGI_Y_SCALE_100_PERCENT" value="2" enum="SDFGIYScale"> </constant> </constants> </class> diff --git a/doc/classes/FontData.xml b/doc/classes/FontData.xml index 55b715c3fc..658f7dd34d 100644 --- a/doc/classes/FontData.xml +++ b/doc/classes/FontData.xml @@ -577,7 +577,7 @@ Font style flags, see [enum TextServer.FontStyle]. </member> <member name="force_autohinter" type="bool" setter="set_force_autohinter" getter="is_force_autohinter" default="false"> - If set to [code]true[/code], auto-hinting is supported and preffered over font built-in hinting. Used by dynamic fonts only. + If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only. </member> <member name="hinting" type="int" setter="set_hinting" getter="get_hinting" enum="TextServer.Hinting" default="1"> Font hinting mode. Used by dynamic fonts only. diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml index f97198658e..1fde3c8463 100644 --- a/doc/classes/GPUParticles2D.xml +++ b/doc/classes/GPUParticles2D.xml @@ -119,7 +119,7 @@ Particle starts with specified color. </constant> <constant name="EMIT_FLAG_CUSTOM" value="16" enum="EmitFlags"> - Particle starts with specificed [code]CUSTOM[/code] data. + Particle starts with specified [code]CUSTOM[/code] data. </constant> </constants> </class> diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index 62ac846077..fc490eac96 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -150,7 +150,7 @@ Particle starts with specified color. </constant> <constant name="EMIT_FLAG_CUSTOM" value="16" enum="EmitFlags"> - Particle starts with specificed [code]CUSTOM[/code] data. + Particle starts with specified [code]CUSTOM[/code] data. </constant> <constant name="MAX_DRAW_PASSES" value="4"> Maximum number of draw passes supported. diff --git a/doc/classes/GeometryInstance3D.xml b/doc/classes/GeometryInstance3D.xml index c03a2b8b7c..1029533e94 100644 --- a/doc/classes/GeometryInstance3D.xml +++ b/doc/classes/GeometryInstance3D.xml @@ -57,7 +57,9 @@ If a material is assigned to this property, it will be used instead of any material set in any material slot of the mesh. </member> <member name="transparency" type="float" setter="set_transparency" getter="get_transparency" default="0.0"> - Transparency applied to the whole geometry. In spatial shaders, transparency is set as the default value of the [code]ALPHA[/code] built-in. + The transparency applied to the whole geometry (as a multiplier of the materials' existing transparency). [code]0.0[/code] is fully opaque, while [code]1.0[/code] is fully transparent. Values greater than [code]0.0[/code] (exclusive) will force the geometry's materials to go through the transparent pipeline, which is slower to render and can exhibit rendering issues due to incorrect transparency sorting. However, unlike using a transparent material, setting [member transparency] to a value greater than [code]0.0[/code] (exclusive) will [i]not[/i] disable shadow rendering. + In spatial shaders, [code]1.0 - transparency[/code] is set as the default value of the [code]ALPHA[/code] built-in. + [b]Note:[/b] [member transparency] is clamped between [code]0.0[/code] and [code]1.0[/code], so this property cannot be used to make transparent materials more opaque than they originally are. </member> <member name="visibility_range_begin" type="float" setter="set_visibility_range_begin" getter="get_visibility_range_begin" default="0.0"> Starting distance from which the GeometryInstance3D will be visible, taking [member visibility_range_begin_margin] into account as well. The default value of 0 is used to disable the range check. diff --git a/doc/classes/Occluder3D.xml b/doc/classes/Occluder3D.xml index 6c6c410bc3..01f009abdb 100644 --- a/doc/classes/Occluder3D.xml +++ b/doc/classes/Occluder3D.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Occluder3D" inherits="Resource" version="4.0"> <brief_description> + Occluder shape resource for use with occlusion culling in [OccluderInstance3D]. </brief_description> <description> + [Occluder3D] stores an occluder shape that can be used by the engine's occlusion culling system. + See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling. </description> <tutorials> </tutorials> @@ -10,11 +13,13 @@ <method name="get_indices" qualifiers="const"> <return type="PackedInt32Array" /> <description> + Returns the occluder shape's vertex indices. </description> </method> <method name="get_vertices" qualifiers="const"> <return type="PackedVector3Array" /> <description> + Returns the occluder shape's vertex positions. </description> </method> </methods> diff --git a/doc/classes/OccluderInstance3D.xml b/doc/classes/OccluderInstance3D.xml index 32e48f9a70..0b5fc0fd26 100644 --- a/doc/classes/OccluderInstance3D.xml +++ b/doc/classes/OccluderInstance3D.xml @@ -1,8 +1,14 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="OccluderInstance3D" inherits="Node3D" version="4.0"> <brief_description> + Provides occlusion culling for 3D nodes, which improves performance in closed areas. </brief_description> <description> + Occlusion culling can improve rendering performance in closed/semi-open areas by hiding geometry that is occluded by other objects. + The occlusion culling system is mostly static. [OccluderInstance3D]s can be moved or hidden at run-time, but doing so will trigger a background recomputation that can take several frames. It is recommended to only move [OccluderInstance3D]s sporadically (e.g. for procedural generation purposes), rather than doing so every frame. + The occlusion culling system works by rendering the occluders on the CPU in parallel using [url=https://www.embree.org/]Embree[/url], drawing the result to a low-resolution buffer then using this to cull 3D nodes individually. In the 3D editor, you can preview the occlusion culling buffer by choosing [b]Perspective > Debug Advanced... > Occlusion Culling Buffer[/b] in the top-left corner of the 3D viewport. The occlusion culling buffer quality can be adjusted in the Project Settings. + [b]Baking:[/b] Select an [OccluderInstance3D] node, then use the [b]Bake Occluders[/b] button at the top of the 3D editor. Only opaque materials will be taken into account; transparent materials (alpha-blended or alpha-tested) will be ignored by the occluder generation. + [b]Note:[/b] Occlusion culling is only effective if [member ProjectSettings.rendering/occlusion_culling/use_occlusion_culling] is [code]true[/code]. Enabling occlusion culling has a cost on the CPU. Only enable occlusion culling if you actually plan to use it. Large open scenes with few or no objects blocking the view will generally not benefit much from occlusion culling. Large open scenes generally benefit more from mesh LOD and visibility ranges ([member GeometryInstance3D.visibility_range_begin] and [member GeometryInstance3D.visibility_range_end]) compared to occlusion culling. </description> <tutorials> </tutorials> @@ -11,7 +17,7 @@ <return type="bool" /> <argument index="0" name="layer_number" type="int" /> <description> - Returns whether or not the specified layer of the [member bake_mask] is enabled, given a [code]layer_number[/code] between 1 and 20. + Returns whether or not the specified layer of the [member bake_mask] is enabled, given a [code]layer_number[/code] between 1 and 32. </description> </method> <method name="set_bake_mask_value"> @@ -19,16 +25,25 @@ <argument index="0" name="layer_number" type="int" /> <argument index="1" name="value" type="bool" /> <description> - Based on [code]value[/code], enables or disables the specified layer in the [member bake_mask], given a [code]layer_number[/code] between 1 and 20. + Based on [code]value[/code], enables or disables the specified layer in the [member bake_mask], given a [code]layer_number[/code] between 1 and 32. </description> </method> </methods> <members> <member name="bake_mask" type="int" setter="set_bake_mask" getter="get_bake_mask" default="4294967295"> + The visual layers to account for when baking for occluders. Only [MeshInstance3D]s whose [member VisualInstance3D.layers] match with this [member bake_mask] will be included in the generated occluder mesh. By default, all objects are taken into account for the occluder baking. + To improve performance and avoid artifacts, it is recommended to exclude dynamic objects, small objects and fixtures from the baking process by moving them to a separate visual layer and excluding this layer in [member bake_mask]. </member> <member name="bake_simplification_distance" type="float" setter="set_bake_simplification_distance" getter="get_bake_simplification_distance" default="0.1"> + The simplification distance to use for simplifying the generated occluder polygon (in 3D units). Higher values result in a less detailed occluder mesh, which improves performance but reduces culling accuracy. + The occluder geometry is rendered on the CPU, so it is important to keep its geometry as simple as possible. Since the buffer is rendered at a low resolution, less detailed occluder meshes generally still work well. The default value is fairly aggressive, so you may have to decrase it if you run into false negatives (objects being occluded even though they are visible by the camera). A value of [code]0.01[/code] will act conservatively, and will keep geometry [i]perceptually[/i] unaffected in the occlusion culling buffer. Depending on the scene, a value of [code]0.01[/code] may still simplify the mesh noticeably compared to disabling simplification entirely. + Setting this to [code]0.0[/code] disables simplification entirely, but vertices in the exact same position will still be merged. The mesh will also be re-indexed to reduce both the number of vertices and indices. + [b]Note:[/b] This uses the [url=https://meshoptimizer.org/]meshoptimizer[/url] library under the hood, similar to LOD generation. </member> <member name="occluder" type="Occluder3D" setter="set_occluder" getter="get_occluder"> + The occluder resource for this [OccluderInstance3D]. You can generate an occluder resource by selecting an [OccluderInstance3D] node then using the [b]Bake Occluders[/b] button at the top of the editor. + You can also draw your own 2D occluder polygon by adding a new [PolygonOccluder3D] resource to the [member occluder] property in the inspector. + Alternatively, you can select a primitive occluder to use: [QuadOccluder3D], [BoxOccluder3D] or [SphereOccluder3D]. </member> </members> </class> diff --git a/doc/classes/PhysicalSkyMaterial.xml b/doc/classes/PhysicalSkyMaterial.xml index e1e50a2b51..5f10cb3c82 100644 --- a/doc/classes/PhysicalSkyMaterial.xml +++ b/doc/classes/PhysicalSkyMaterial.xml @@ -17,14 +17,14 @@ <member name="exposure" type="float" setter="set_exposure" getter="get_exposure" default="0.1"> Sets the exposure of the sky. Higher exposure values make the entire sky brighter. </member> - <member name="ground_color" type="Color" setter="set_ground_color" getter="get_ground_color" default="Color(1, 1, 1, 1)"> + <member name="ground_color" type="Color" setter="set_ground_color" getter="get_ground_color" default="Color(0.1, 0.07, 0.034, 1)"> Modulates the [Color] on the bottom half of the sky to represent the ground. </member> <member name="mie_coefficient" type="float" setter="set_mie_coefficient" getter="get_mie_coefficient" default="0.005"> Controls the strength of mie scattering for the sky. Mie scattering results from light colliding with larger particles (like water). On earth, mie scattering results in a whitish color around the sun and horizon. </member> - <member name="mie_color" type="Color" setter="set_mie_color" getter="get_mie_color" default="Color(0.63, 0.77, 0.92, 1)"> - Controls the [Color] of the mie scattering effect. While not physically accurate, this allows for the creation of alien looking planets. + <member name="mie_color" type="Color" setter="set_mie_color" getter="get_mie_color" default="Color(0.69, 0.729, 0.812, 1)"> + Controls the [Color] of the mie scattering effect. While not physically accurate, this allows for the creation of alien-looking planets. </member> <member name="mie_eccentricity" type="float" setter="set_mie_eccentricity" getter="get_mie_eccentricity" default="0.8"> Controls the direction of the mie scattering. A value of [code]1[/code] means that when light hits a particle it's passing through straight forward. A value of [code]-1[/code] means that all light is scatter backwards. @@ -35,14 +35,14 @@ <member name="rayleigh_coefficient" type="float" setter="set_rayleigh_coefficient" getter="get_rayleigh_coefficient" default="2.0"> Controls the strength of the Rayleigh scattering. Rayleigh scattering results from light colliding with small particles. It is responsible for the blue color of the sky. </member> - <member name="rayleigh_color" type="Color" setter="set_rayleigh_color" getter="get_rayleigh_color" default="Color(0.26, 0.41, 0.58, 1)"> - Controls the [Color] of the Rayleigh scattering. While not physically accurate, this allows for the creation of alien looking planets. For example, setting this to a red [Color] results in a Mars looking atmosphere with a corresponding blue sunset. + <member name="rayleigh_color" type="Color" setter="set_rayleigh_color" getter="get_rayleigh_color" default="Color(0.3, 0.405, 0.6, 1)"> + Controls the [Color] of the Rayleigh scattering. While not physically accurate, this allows for the creation of alien-looking planets. For example, setting this to a red [Color] results in a Mars-looking atmosphere with a corresponding blue sunset. </member> <member name="sun_disk_scale" type="float" setter="set_sun_disk_scale" getter="get_sun_disk_scale" default="1.0"> Sets the size of the sun disk. Default value is based on Sol's perceived size from Earth. </member> <member name="turbidity" type="float" setter="set_turbidity" getter="get_turbidity" default="10.0"> - Sets the thickness of the atmosphere. High turbidity creates a foggy looking atmosphere, while a low turbidity results in a clearer atmosphere. + Sets the thickness of the atmosphere. High turbidity creates a foggy-looking atmosphere, while a low turbidity results in a clearer atmosphere. </member> </members> </class> diff --git a/doc/classes/PolygonOccluder3D.xml b/doc/classes/PolygonOccluder3D.xml index a4d910c983..e4bd84beac 100644 --- a/doc/classes/PolygonOccluder3D.xml +++ b/doc/classes/PolygonOccluder3D.xml @@ -1,13 +1,18 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="PolygonOccluder3D" inherits="Occluder3D" version="4.0"> <brief_description> + Flat 2D polygon shape for use with occlusion culling in [OccluderInstance3D]. </brief_description> <description> + [PolygonOccluder3D] stores a polygon shape that can be used by the engine's occlusion culling system. When an [OccluderInstance3D] with a [PolygonOccluder3D] is selected in the editor, an editor will appear at the top of the 3D viewport so you can add/remove points. All points must be placed on the same 2D plane, which means it is not possible to create arbitrary 3D shapes with a single [PolygonOccluder3D]. To use arbitrary 3D shapes as occluders, use [ArrayOccluder3D] or [OccluderInstance3D]'s baking feature instead. + See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling. </description> <tutorials> </tutorials> <members> <member name="polygon" type="PackedVector2Array" setter="set_polygon" getter="get_polygon" default="PackedVector2Array()"> + The polygon to use for occlusion culling. The polygon can be convex or concave, but it should have as few points as possible to maximize performance. + The polygon must [i]not[/i] have intersecting lines. Otherwise, triangulation will fail (with an error message printed). </member> </members> </class> diff --git a/doc/classes/Popup.xml b/doc/classes/Popup.xml index dc5dd47287..36bdd6e6e4 100644 --- a/doc/classes/Popup.xml +++ b/doc/classes/Popup.xml @@ -1,17 +1,17 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Popup" inherits="Window" version="4.0"> <brief_description> - Base container control for popups and dialogs. + Popup is a base window container for popup-like subwindows. </brief_description> <description> - Popup is a base [Control] used to show dialogs and popups. It's a subwindow and modal by default (see [Control]) and has helpers for custom popup behavior. + Popup is a base window container for popup-like subwindows. It's a modal by default (see [member close_on_parent_focus]) and has helpers for custom popup behavior. </description> <tutorials> </tutorials> <members> <member name="borderless" type="bool" setter="set_flag" getter="get_flag" overrides="Window" default="true" /> <member name="close_on_parent_focus" type="bool" setter="set_close_on_parent_focus" getter="get_close_on_parent_focus" default="true"> - If [code]true[/code], the [Popup] will close when its parent is focused. + If true, the [Popup] will close when its parent [Window] is focused. </member> <member name="transient" type="bool" setter="set_transient" getter="is_transient" overrides="Window" default="true" /> <member name="unresizable" type="bool" setter="set_flag" getter="get_flag" overrides="Window" default="true" /> @@ -21,7 +21,7 @@ <signals> <signal name="popup_hide"> <description> - Emitted when a popup is hidden. + Emitted when the popup is hidden. </description> </signal> </signals> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index b316f822f0..29a4cfcd46 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -4,7 +4,7 @@ PopupMenu displays a list of options. </brief_description> <description> - [PopupMenu] is a [Control] that displays a list of options. They are popular in toolbars or context menus. + [PopupMenu] is a modal window used to display a list of options. They are popular in toolbars or context menus. The size of a [PopupMenu] can be limited by using [member Window.max_size]. If the height of the list of items is larger than the maximum height of the [PopupMenu], a [ScrollContainer] within the popup will allow the user to scroll the contents. If no maximum size is set, or if it is set to 0, the [PopupMenu] height will be limited by its parent rect. </description> diff --git a/doc/classes/ProceduralSkyMaterial.xml b/doc/classes/ProceduralSkyMaterial.xml index e3db74894b..dc6ead1b01 100644 --- a/doc/classes/ProceduralSkyMaterial.xml +++ b/doc/classes/ProceduralSkyMaterial.xml @@ -11,7 +11,7 @@ <tutorials> </tutorials> <members> - <member name="ground_bottom_color" type="Color" setter="set_ground_bottom_color" getter="get_ground_bottom_color" default="Color(0.12, 0.12, 0.13, 1)"> + <member name="ground_bottom_color" type="Color" setter="set_ground_bottom_color" getter="get_ground_bottom_color" default="Color(0.2, 0.169, 0.133, 1)"> Color of the ground at the bottom. Blends with [member ground_horizon_color]. </member> <member name="ground_curve" type="float" setter="set_ground_curve" getter="get_ground_curve" default="0.02"> @@ -20,25 +20,25 @@ <member name="ground_energy" type="float" setter="set_ground_energy" getter="get_ground_energy" default="1.0"> Amount of energy contribution from the ground. </member> - <member name="ground_horizon_color" type="Color" setter="set_ground_horizon_color" getter="get_ground_horizon_color" default="Color(0.37, 0.33, 0.31, 1)"> + <member name="ground_horizon_color" type="Color" setter="set_ground_horizon_color" getter="get_ground_horizon_color" default="Color(0.6463, 0.6558, 0.6708, 1)"> Color of the ground at the horizon. Blends with [member ground_bottom_color]. </member> - <member name="sky_curve" type="float" setter="set_sky_curve" getter="get_sky_curve" default="0.09"> + <member name="sky_curve" type="float" setter="set_sky_curve" getter="get_sky_curve" default="0.15"> How quickly the [member sky_horizon_color] fades into the [member sky_top_color]. </member> <member name="sky_energy" type="float" setter="set_sky_energy" getter="get_sky_energy" default="1.0"> Amount of energy contribution from the sky. </member> - <member name="sky_horizon_color" type="Color" setter="set_sky_horizon_color" getter="get_sky_horizon_color" default="Color(0.55, 0.69, 0.81, 1)"> + <member name="sky_horizon_color" type="Color" setter="set_sky_horizon_color" getter="get_sky_horizon_color" default="Color(0.6463, 0.6558, 0.6708, 1)"> Color of the sky at the horizon. Blends with [member sky_top_color]. </member> - <member name="sky_top_color" type="Color" setter="set_sky_top_color" getter="get_sky_top_color" default="Color(0.35, 0.46, 0.71, 1)"> + <member name="sky_top_color" type="Color" setter="set_sky_top_color" getter="get_sky_top_color" default="Color(0.385, 0.454, 0.55, 1)"> Color of the sky at the top. Blends with [member sky_horizon_color]. </member> - <member name="sun_angle_max" type="float" setter="set_sun_angle_max" getter="get_sun_angle_max" default="100.0"> + <member name="sun_angle_max" type="float" setter="set_sun_angle_max" getter="get_sun_angle_max" default="30.0"> Distance from center of sun where it fades out completely. </member> - <member name="sun_curve" type="float" setter="set_sun_curve" getter="get_sun_curve" default="0.05"> + <member name="sun_curve" type="float" setter="set_sun_curve" getter="get_sun_curve" default="0.15"> How quickly the sun fades away between the edge of the sun disk and [member sun_angle_max]. </member> </members> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index ed124d1d15..4b5f7b2091 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -1696,13 +1696,13 @@ If [code]true[/code], renders [VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) buffers at halved resolution (e.g. 960×540 when the viewport size is 1920×1080). This improves performance significantly when VoxelGI or SDFGI is enabled, at the cost of artifacts that may be visible on polygon edges. The loss in quality becomes less noticeable as the viewport resolution increases. [LightmapGI] rendering is not affected by this setting. [b]Note:[/b] This property is only read when the project starts. To set half-resolution GI at run-time, call [method RenderingServer.gi_set_use_half_resolution] instead. </member> - <member name="rendering/global_illumination/sdfgi/frames_to_converge" type="int" setter="" getter="" default="4"> + <member name="rendering/global_illumination/sdfgi/frames_to_converge" type="int" setter="" getter="" default="5"> </member> <member name="rendering/global_illumination/sdfgi/frames_to_update_lights" type="int" setter="" getter="" default="2"> </member> <member name="rendering/global_illumination/sdfgi/probe_ray_count" type="int" setter="" getter="" default="1"> </member> - <member name="rendering/global_illumination/voxel_gi/quality" type="int" setter="" getter="" default="1"> + <member name="rendering/global_illumination/voxel_gi/quality" type="int" setter="" getter="" default="0"> </member> <member name="rendering/lightmapping/bake_performance/max_rays_per_pass" type="int" setter="" getter="" default="32"> </member> @@ -1746,10 +1746,14 @@ [b]Note:[/b] This property is only read when the project starts. To adjust the automatic LOD threshold at runtime, set [member Viewport.mesh_lod_threshold] on the root [Viewport]. </member> <member name="rendering/occlusion_culling/bvh_build_quality" type="int" setter="" getter="" default="2"> + The [url=https://en.wikipedia.org/wiki/Bounding_volume_hierarchy]BVH[/url] quality to use when rendering the occlusion culling buffer. Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. </member> <member name="rendering/occlusion_culling/occlusion_rays_per_thread" type="int" setter="" getter="" default="512"> + Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. The occlusion culling buffer's pixel count is roughly equal to [code]occlusion_rays_per_thread * number_of_logical_cpu_cores[/code], so it will depend on the system's CPU. Therefore, CPUs with fewer cores will use a lower resolution to attempt keeping performance costs even across devices. </member> <member name="rendering/occlusion_culling/use_occlusion_culling" type="bool" setter="" getter="" default="false"> + If [code]true[/code], [OccluderInstance3D] nodes will be usable for occlusion culling in 3D in the root viewport. In custom viewports, [member Viewport.use_occlusion_culling] must be set to [code]true[/code] instead. + [b]Note:[/b] Enabling occlusion culling has a cost on the CPU. Only enable occlusion culling if you actually plan to use it. Large open scenes with few or no objects blocking the view will generally not benefit much from occlusion culling. Large open scenes generally benefit more from mesh LOD and visibility ranges ([member GeometryInstance3D.visibility_range_begin] and [member GeometryInstance3D.visibility_range_end]) compared to occlusion culling. </member> <member name="rendering/reflections/reflection_atlas/reflection_count" type="int" setter="" getter="" default="64"> Number of cubemaps to store in the reflection atlas. The number of [ReflectionProbe]s in a scene will be limited by this amount. A higher number requires more VRAM. @@ -1826,7 +1830,7 @@ <member name="rendering/shadows/directional_shadow/size.mobile" type="int" setter="" getter="" default="2048"> Lower-end override for [member rendering/shadows/directional_shadow/size] on mobile devices, due to performance concerns or driver support. </member> - <member name="rendering/shadows/directional_shadow/soft_shadow_quality" type="int" setter="" getter="" default="3"> + <member name="rendering/shadows/directional_shadow/soft_shadow_quality" type="int" setter="" getter="" default="2"> Quality setting for shadows cast by [DirectionalLight3D]s. Higher quality settings use more samples when reading from shadow maps and are thus slower. Low quality settings may result in shadows looking grainy. [b]Note:[/b] The Soft Very Low setting will automatically multiply [i]constant[/i] shadow blur by 0.75x to reduce the amount of noise visible. This automatic blur change only affects the constant blur factor defined in [member Light3D.shadow_blur], not the variable blur performed by [DirectionalLight3D]s' [member Light3D.light_angular_distance]. [b]Note:[/b] The Soft High and Soft Ultra settings will automatically multiply [i]constant[/i] shadow blur by 1.5× and 2× respectively to make better use of the increased sample count. This increased blur also improves stability of dynamic object shadows. @@ -1854,7 +1858,7 @@ <member name="rendering/shadows/shadow_atlas/size.mobile" type="int" setter="" getter="" default="2048"> Lower-end override for [member rendering/shadows/shadow_atlas/size] on mobile devices, due to performance concerns or driver support. </member> - <member name="rendering/shadows/shadows/soft_shadow_quality" type="int" setter="" getter="" default="3"> + <member name="rendering/shadows/shadows/soft_shadow_quality" type="int" setter="" getter="" default="2"> Quality setting for shadows cast by [OmniLight3D]s and [SpotLight3D]s. Higher quality settings use more samples when reading from shadow maps and are thus slower. Low quality settings may result in shadows looking grainy. [b]Note:[/b] The Soft Very Low setting will automatically multiply [i]constant[/i] shadow blur by 0.75x to reduce the amount of noise visible. This automatic blur change only affects the constant blur factor defined in [member Light3D.shadow_blur], not the variable blur performed by [DirectionalLight3D]s' [member Light3D.light_angular_distance]. [b]Note:[/b] The Soft High and Soft Ultra settings will automatically multiply shadow blur by 1.5× and 2× respectively to make better use of the increased sample count. This increased blur also improves stability of dynamic object shadows. diff --git a/doc/classes/QuadOccluder3D.xml b/doc/classes/QuadOccluder3D.xml index c1b89149f5..44cbfb88ff 100644 --- a/doc/classes/QuadOccluder3D.xml +++ b/doc/classes/QuadOccluder3D.xml @@ -1,13 +1,17 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="QuadOccluder3D" inherits="Occluder3D" version="4.0"> <brief_description> + Flat plane shape for use with occlusion culling in [OccluderInstance3D]. </brief_description> <description> + [QuadOccluder3D] stores a flat plane shape that can be used by the engine's occlusion culling system. See also [PolygonOccluder3D] if you need to customize the quad's shape. + See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling. </description> <tutorials> </tutorials> <members> <member name="size" type="Vector2" setter="set_size" getter="get_size" default="Vector2(1, 1)"> + The quad's size in 3D units. </member> </members> </class> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 82728c0570..8ef10d1be4 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -1455,6 +1455,9 @@ <argument index="1" name="transparency" type="float" /> <description> Sets the transparency for the given geometry instance. Equivalent to [member GeometryInstance3D.transparency]. + A transparency of [code]0.0[/code] is fully opaque, while [code]1.0[/code] is fully transparent. Values greater than [code]0.0[/code] (exclusive) will force the geometry's materials to go through the transparent pipeline, which is slower to render and can exhibit rendering issues due to incorrect transparency sorting. However, unlike using a transparent material, setting [code]transparency[/code] to a value greater than [code]0.0[/code] (exclusive) will [i]not[/i] disable shadow rendering. + In spatial shaders, [code]1.0 - transparency[/code] is set as the default value of the [code]ALPHA[/code] built-in. + [b]Note:[/b] [code]transparency[/code] is clamped between [code]0.0[/code] and [code]1.0[/code], so this property cannot be used to make transparent materials more opaque than they originally are. </description> </method> <method name="instance_geometry_set_visibility_range"> @@ -4181,11 +4184,11 @@ <constant name="ENV_SSIL_QUALITY_ULTRA" value="4" enum="EnvironmentSSILQuality"> Highest quality screen-space indirect lighting. Uses the adaptive target setting which can be dynamically adjusted to smoothly balance performance and visual quality. </constant> - <constant name="ENV_SDFGI_Y_SCALE_DISABLED" value="0" enum="EnvironmentSDFGIYScale"> + <constant name="ENV_SDFGI_Y_SCALE_50_PERCENT" value="0" enum="EnvironmentSDFGIYScale"> </constant> <constant name="ENV_SDFGI_Y_SCALE_75_PERCENT" value="1" enum="EnvironmentSDFGIYScale"> </constant> - <constant name="ENV_SDFGI_Y_SCALE_50_PERCENT" value="2" enum="EnvironmentSDFGIYScale"> + <constant name="ENV_SDFGI_Y_SCALE_100_PERCENT" value="2" enum="EnvironmentSDFGIYScale"> </constant> <constant name="ENV_SDFGI_RAY_COUNT_4" value="0" enum="EnvironmentSDFGIRayCount"> </constant> diff --git a/doc/classes/ResourceUID.xml b/doc/classes/ResourceUID.xml index 9e3d647ccf..a5ceae898f 100644 --- a/doc/classes/ResourceUID.xml +++ b/doc/classes/ResourceUID.xml @@ -14,7 +14,7 @@ <description> </description> </method> - <method name="create_id" qualifiers="const"> + <method name="create_id"> <return type="int" /> <description> </description> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 95dffd3e28..cb733f34ca 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -49,12 +49,32 @@ Clears the tag stack and sets [member text] to an empty string. </description> </method> + <method name="get_character_line"> + <return type="int" /> + <argument index="0" name="character" type="int" /> + <description> + Returns the line number of the character position provided. + </description> + </method> + <method name="get_character_paragraph"> + <return type="int" /> + <argument index="0" name="character" type="int" /> + <description> + Returns the paragraph number of the character position provided. + </description> + </method> <method name="get_content_height" qualifiers="const"> <return type="int" /> <description> Returns the height of the content. </description> </method> + <method name="get_content_width" qualifiers="const"> + <return type="int" /> + <description> + Returns the width of the content. + </description> + </method> <method name="get_line_count" qualifiers="const"> <return type="int" /> <description> diff --git a/doc/classes/SphereOccluder3D.xml b/doc/classes/SphereOccluder3D.xml index 1ffa51e170..da847cc43f 100644 --- a/doc/classes/SphereOccluder3D.xml +++ b/doc/classes/SphereOccluder3D.xml @@ -1,13 +1,17 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="SphereOccluder3D" inherits="Occluder3D" version="4.0"> <brief_description> + Spherical shape for use with occlusion culling in [OccluderInstance3D]. </brief_description> <description> + [SphereOccluder3D] stores a sphere shape that can be used by the engine's occlusion culling system. + See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling. </description> <tutorials> </tutorials> <members> <member name="radius" type="float" setter="set_radius" getter="get_radius" default="1.0"> + The sphere's radius in 3D units. </member> </members> </class> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index a6182f5dab..6b8c455203 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -241,7 +241,8 @@ <method name="hash" qualifiers="const"> <return type="int" /> <description> - Hashes the string and returns a 32-bit integer. + Returns the 32-bit hash value representing the string's contents. + [b]Note:[/b] [String]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the strings are equal, because different strings can have identical hash values due to hash collisions. </description> </method> <method name="hex_to_int" qualifiers="const"> diff --git a/doc/classes/TextServerExtension.xml b/doc/classes/TextServerExtension.xml index b500bd5658..b212cec5f2 100644 --- a/doc/classes/TextServerExtension.xml +++ b/doc/classes/TextServerExtension.xml @@ -557,7 +557,7 @@ <argument index="0" name="font_rid" type="RID" /> <argument index="1" name="force_autohinter" type="bool" /> <description> - If set to [code]true[/code] auto-hinting is preffered over font built-in hinting. + If set to [code]true[/code] auto-hinting is preferred over font built-in hinting. </description> </method> <method name="_font_set_global_oversampling" qualifiers="virtual"> diff --git a/doc/classes/Theme.xml b/doc/classes/Theme.xml index b1367be263..f2775e60f3 100644 --- a/doc/classes/Theme.xml +++ b/doc/classes/Theme.xml @@ -13,6 +13,14 @@ <link title="Using the theme editor">$DOCS_URL/tutorials/ui/gui_using_theme_editor.html</link> </tutorials> <methods> + <method name="add_type"> + <return type="void" /> + <argument index="0" name="theme_type" type="StringName" /> + <description> + Adds an empty theme type for every valid data type. + [b]Note:[/b] Empty types are not saved with the theme. This method only exists to perform in-memory changes to the resource. Use available [code]set_*[/code] methods to add theme items. + </description> + </method> <method name="clear"> <return type="void" /> <description> @@ -375,6 +383,13 @@ [b]Note:[/b] This modifies the current theme. If you want to merge two themes together without modifying either one, create a new empty theme and merge the other two into it one after another. </description> </method> + <method name="remove_type"> + <return type="void" /> + <argument index="0" name="theme_type" type="StringName" /> + <description> + Removes the theme type, gracefully discarding defined theme items. If the type is a variation, this information is also erased. If the type is a base for type variations, those variations lose their base. + </description> + </method> <method name="rename_color"> <return type="void" /> <argument index="0" name="old_name" type="StringName" /> diff --git a/doc/classes/TranslationServer.xml b/doc/classes/TranslationServer.xml index 6ece42da6b..546b7ec242 100644 --- a/doc/classes/TranslationServer.xml +++ b/doc/classes/TranslationServer.xml @@ -138,7 +138,7 @@ <return type="String" /> <argument index="0" name="locale" type="String" /> <description> - Retunrs [code]locale[/code] string standardized to match known locales (e.g. [code]en-US[/code] would be matched to [code]en_US[/code]). + Returns [code]locale[/code] string standardized to match known locales (e.g. [code]en-US[/code] would be matched to [code]en_US[/code]). </description> </method> <method name="translate" qualifiers="const"> diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index 4b051c4938..35a70ae53f 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -72,6 +72,13 @@ [b]Note:[/b] Despite the name of this method, the focus cursor itself is only visible in [constant SELECT_MULTI] mode. </description> </method> + <method name="get_button_id_at_position" qualifiers="const"> + <return type="int" /> + <argument index="0" name="position" type="Vector2" /> + <description> + Returns the button id at [code]position[/code], or -1 if no button is there. + </description> + </method> <method name="get_column_at_position" qualifiers="const"> <return type="int" /> <argument index="0" name="position" type="Vector2" /> diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml index 12c91cdd10..675c534e7b 100644 --- a/doc/classes/TreeItem.xml +++ b/doc/classes/TreeItem.xml @@ -14,11 +14,11 @@ <return type="void" /> <argument index="0" name="column" type="int" /> <argument index="1" name="button" type="Texture2D" /> - <argument index="2" name="button_idx" type="int" default="-1" /> + <argument index="2" name="id" type="int" default="-1" /> <argument index="3" name="disabled" type="bool" default="false" /> <argument index="4" name="tooltip" type="String" default="""" /> <description> - Adds a button with [Texture2D] [code]button[/code] at column [code]column[/code]. The [code]button_idx[/code] index is used to identify the button when calling other methods. If not specified, the next available index is used, which may be retrieved by calling [method get_button_count] immediately after this method. Optionally, the button can be [code]disabled[/code] and have a [code]tooltip[/code]. + Adds a button with [Texture2D] [code]button[/code] at column [code]column[/code]. The [code]id[/code] is used to identify the button. If not specified, the next available index is used, which may be retrieved by calling [method get_button_count] immediately after this method. Optionally, the button can be [code]disabled[/code] and have a [code]tooltip[/code]. </description> </method> <method name="call_recursive" qualifiers="vararg"> @@ -80,6 +80,14 @@ Returns the [Texture2D] of the button at index [code]button_idx[/code] in column [code]column[/code]. </description> </method> + <method name="get_button_by_id" qualifiers="const"> + <return type="int" /> + <argument index="0" name="column" type="int" /> + <argument index="1" name="id" type="int" /> + <description> + Returns the button index if there is a button with id [code]id[/code] in column [code]column[/code], otherwise returns -1. + </description> + </method> <method name="get_button_count" qualifiers="const"> <return type="int" /> <argument index="0" name="column" type="int" /> @@ -87,6 +95,14 @@ Returns the number of buttons in column [code]column[/code]. May be used to get the most recently added button's index, if no index was specified. </description> </method> + <method name="get_button_id" qualifiers="const"> + <return type="int" /> + <argument index="0" name="column" type="int" /> + <argument index="1" name="button_idx" type="int" /> + <description> + Returns the id for the button at index [code]button_idx[/code] in column [code]column[/code]. + </description> + </method> <method name="get_button_tooltip" qualifiers="const"> <return type="String" /> <argument index="0" name="column" type="int" /> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 7a60ca9fa6..93c1e8417b 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -55,7 +55,7 @@ <method name="get_mouse_position" qualifiers="const"> <return type="Vector2" /> <description> - Returns the mouse's positon in this [Viewport] using the coordinate system of this [Viewport]. + Returns the mouse's position in this [Viewport] using the coordinate system of this [Viewport]. </description> </method> <method name="get_render_info"> @@ -128,7 +128,7 @@ <method name="gui_release_focus"> <return type="void" /> <description> - Removes the focus from the currently focussed [Control] within this viewport. If no [Control] has the focus, does nothing. + Removes the focus from the currently focused [Control] within this viewport. If no [Control] has the focus, does nothing. </description> </method> <method name="is_embedding_subwindows" qualifiers="const"> @@ -285,6 +285,8 @@ <member name="use_debanding" type="bool" setter="set_use_debanding" getter="is_using_debanding" default="false"> </member> <member name="use_occlusion_culling" type="bool" setter="set_use_occlusion_culling" getter="is_using_occlusion_culling" default="false"> + If [code]true[/code], [OccluderInstance3D] nodes will be usable for occlusion culling in 3D for this viewport. For the root viewport, [member ProjectSettings.rendering/occlusion_culling/use_occlusion_culling] must be set to [code]true[/code] instead. + [b]Note:[/b] Enabling occlusion culling has a cost on the CPU. Only enable occlusion culling if you actually plan to use it, and think whether your scene can actually benefit from occlusion culling. Large, open scenes with few or no objects blocking the view will generally not benefit much from occlusion culling. Large open scenes generally benefit more from mesh LOD and visibility ranges ([member GeometryInstance3D.visibility_range_begin] and [member GeometryInstance3D.visibility_range_end]) compared to occlusion culling. </member> <member name="use_xr" type="bool" setter="set_use_xr" getter="is_using_xr" default="false"> If [code]true[/code], the viewport will use the primary XR interface to render XR output. When applicable this can result in a stereoscopic image and the resulting render being output to a headset. diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 68f3b66f43..365beb434b 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -536,19 +536,19 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Inheritance tree # Ascendants if class_def.inherits: - inh = class_def.inherits.strip() + inherits = class_def.inherits.strip() f.write("**" + translate("Inherits:") + "** ") first = True - while inh in state.classes: + while inherits in state.classes: if not first: f.write(" **<** ") else: first = False - f.write(make_type(inh, state)) - inode = state.classes[inh].inherits + f.write(make_type(inherits, state)) + inode = state.classes[inherits].inherits if inode: - inh = inode.strip() + inherits = inode.strip() else: break f.write("\n\n") diff --git a/doc/translations/classes.pot b/doc/translations/classes.pot index a802e3a7ac..ca8bc21508 100644 --- a/doc/translations/classes.pot +++ b/doc/translations/classes.pot @@ -34818,7 +34818,7 @@ msgstr "" #: doc/classes/NavigationAgent.xml doc/classes/NavigationAgent2D.xml msgid "" "The minimal amount of time for which this agent's velocities, that are " -"computed with the collision avoidance algorithim, are safe with respect to " +"computed with the collision avoidance algorithm, are safe with respect to " "other agents. The larger the number, the sooner the agent will respond to " "other agents, but the less freedom in choosing its velocities. Must be " "positive." diff --git a/doc/translations/extract.py b/doc/translations/extract.py index f8223701d5..5708e0072d 100644 --- a/doc/translations/extract.py +++ b/doc/translations/extract.py @@ -222,10 +222,14 @@ def _make_translation_catalog(classes): desc_list = classes[class_name] for elem in desc_list.doc.iter(): if elem.tag in EXTRACT_TAGS: - if not elem.text or len(elem.text) == 0: + elem_text = elem.text + if elem.tag == "link": + elem_text = elem.attrib["title"] if "title" in elem.attrib else "" + if not elem_text or len(elem_text) == 0: continue - line_no = elem._start_line_number if elem.text[0] != "\n" else elem._start_line_number + 1 - desc_str = elem.text.strip() + + line_no = elem._start_line_number if elem_text[0] != "\n" else elem._start_line_number + 1 + desc_str = elem_text.strip() code_block_regions = _make_codeblock_regions(desc_str, desc_list.path) desc_msg = _strip_and_split_desc(desc_str, code_block_regions) desc_obj = Desc(line_no, desc_msg, desc_list) |