Merge pull request #35458 from clayjohn/DOCS-misc2

Finish documenting CSG* and *probes classes

doc/classes/GIProbe.xml

@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GIProbe" inherits="VisualInstance" category="Core" version="3.2">
 	<brief_description>
+		Real-time global illumination (GI) probe.
 	</brief_description>
 	<description>
+		[GIProbe]s are used to provide high-quality real-time indirect light to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. [GIProbe]s need to be baked before using, however, once baked, dynamic objects will receive light from them. Further, lights can be fully dynamic or baked.
+		Having [GIProbe]s in a scene can be expensive, the quality of the probe can be turned down in exchange for better performance in the [ProjectSettings] using [member ProjectSettings.rendering/quality/voxel_cone_tracing/high_quality].
 	</description>
 	<tutorials>
 		<link>https://docs.godotengine.org/en/latest/tutorials/3d/gi_probes.html</link>
@@ -16,45 +19,62 @@
 			<argument index="1" name="create_visual_debug" type="bool" default="false">
 			</argument>
 			<description>
+				Bakes the effect from all [GeometryInstance]s marked with [member GeometryInstance.use_in_baked_light] and [Light]s marked with either [constant Light.BAKE_INDIRECT] or [constant Light.BAKE_ALL]. If [code]create_visual_debug[/code] is [code]true[/code], after baking the light, this will generate a [MultiMesh] that has a cube representing each solid cell with each cube colored to the cell's albedo color. This can be used to visualize the [GIProbe]'s data and debug any issues that may be occurring.
 			</description>
 		</method>
 		<method name="debug_bake">
 			<return type="void">
 			</return>
 			<description>
+				Calls [method bake] with [code]create_visual_debug[/code] enabled.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="bias" type="float" setter="set_bias" getter="get_bias" default="1.5">
+			Offsets the lookup of the light contribution from the [GIProbe]. This can be used to avoid self-shadowing, but may introduce light leaking at higher values. This and [member normal_bias] should be played around with to minimize self-shadowing and light leaking.
+			[b]Note:[/b] [code]bias[/code] should usually be above 1.0 as that is the size of the voxels.
 		</member>
 		<member name="compress" type="bool" setter="set_compress" getter="is_compressed" default="false">
+			If [code]true[/code], the data for this [GIProbe] will be compressed. Compression saves space, but results in far worse visual quality.
 		</member>
 		<member name="data" type="GIProbeData" setter="set_probe_data" getter="get_probe_data">
+			The [GIProbeData] resource that holds the data for this [GIProbe].
 		</member>
 		<member name="dynamic_range" type="int" setter="set_dynamic_range" getter="get_dynamic_range" default="4">
+			The maximum brightness that the [GIProbe] will recognize. Brightness will be scaled within this range.
 		</member>
 		<member name="energy" type="float" setter="set_energy" getter="get_energy" default="1.0">
+			Energy multiplier. Makes the lighting contribution from the [GIProbe] brighter.
 		</member>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3( 10, 10, 10 )">
+			The size of the area covered by the [GIProbe]. If you make the extents larger without increasing the subdivisions with [member subdiv], the size of each cell will increase and result in lower detailed lighting.
 		</member>
 		<member name="interior" type="bool" setter="set_interior" getter="is_interior" default="false">
+			If [code]true[/code], ignores the sky contribution when calculating lighting.
 		</member>
 		<member name="normal_bias" type="float" setter="set_normal_bias" getter="get_normal_bias" default="0.0">
+			Offsets the lookup into the [GIProbe] based on the object's normal direction. Can be used to reduce some self-shadowing artifacts.
 		</member>
 		<member name="propagation" type="float" setter="set_propagation" getter="get_propagation" default="0.7">
+			How much light propagates through the probe internally. A higher value allows light to spread further.
 		</member>
 		<member name="subdiv" type="int" setter="set_subdiv" getter="get_subdiv" enum="GIProbe.Subdiv" default="1">
+			Number of times to subdivide the grid that the [GIProbe] operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance.
 		</member>
 	</members>
 	<constants>
 		<constant name="SUBDIV_64" value="0" enum="Subdiv">
+			Use 64 subdivisions. This is the lowest quality setting, but the fastest. Use it if you can, but especially use it on lower-end hardware.
 		</constant>
 		<constant name="SUBDIV_128" value="1" enum="Subdiv">
+			Use 128 subdivisions. This is the default quality setting.
 		</constant>
 		<constant name="SUBDIV_256" value="2" enum="Subdiv">
+			Use 256 subdivisions.
 		</constant>
 		<constant name="SUBDIV_512" value="3" enum="Subdiv">
+			Use 512 subdivisions. This is the highest quality setting, but the slowest. On lower-end hardware this could cause the GPU to stall.
 		</constant>
 		<constant name="SUBDIV_MAX" value="4" enum="Subdiv">
 			Represents the size of the [enum Subdiv] enum.

doc/classes/ProjectSettings.xml

@@ -792,6 +792,7 @@
 			Default background clear color. Overridable per [Viewport] using its [Environment]. See [member Environment.background_mode] and [member Environment.background_color] in particular. To change this default color programmatically, use [method VisualServer.set_default_clear_color].
 		</member>
 		<member name="rendering/environment/default_environment" type="String" setter="" getter="" default="&quot;&quot;">
+			[Environment] that will be used as a fallback environment in case a scene does not specify its own environment. The default environment is loaded in at scene load time regardless of whether you have set an environment or not. If you do not rely on the fallback environment, it is best to delete [code]default_env.tres[/code], or to specify a different default environment here.
 		</member>
 		<member name="rendering/limits/buffers/blend_shape_max_buffer_size_kb" type="int" setter="" getter="" default="4096">
 			Max buffer size for blend shapes. Any blend shape bigger than this will not work.
@@ -825,6 +826,8 @@
 			If [code]true[/code], forces snapping of polygons to pixels in 2D rendering. May help in some pixel art styles.
 		</member>
 		<member name="rendering/quality/depth/hdr" type="bool" setter="" getter="" default="true">
+			If [code]true[/code], allocates the main framebuffer with high dynamic range. High dynamic range allows the use of [Color] values greater than 1.
+			[b]Note:[/b] Only available on the GLES3 backend.
 		</member>
 		<member name="rendering/quality/depth/hdr.mobile" type="bool" setter="" getter="" default="false">
 		</member>
@@ -851,18 +854,23 @@
 			Maximum anisotropic filter level used for textures with anisotropy enabled. Higher values will result in sharper textures when viewed from oblique angles, at the cost of performance. Only power-of-two values are valid (2, 4, 8, 16).
 		</member>
 		<member name="rendering/quality/filters/msaa" type="int" setter="" getter="" default="0">
+			Sets the number of MSAA samples to use. MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware.
+			[b]Note:[/b] MSAA is not available on HTML5 export using the GLES2 backend.
 		</member>
 		<member name="rendering/quality/filters/use_nearest_mipmap_filter" type="bool" setter="" getter="" default="false">
 			If [code]true[/code], uses nearest-neighbor mipmap filtering when using mipmaps (also called "bilinear filtering"), which will result in visible seams appearing between mipmap stages. This may increase performance in mobile as less memory bandwidth is used. If [code]false[/code], linear mipmap filtering (also called "trilinear filtering") is used.
 		</member>
 		<member name="rendering/quality/intended_usage/framebuffer_allocation" type="int" setter="" getter="" default="2">
-			Strategy used for framebuffer allocation. The simpler it is, the less resources it uses (but the less features it supports).
+			Strategy used for framebuffer allocation. The simpler it is, the less resources it uses (but the less features it supports). If set to "2D Without Sampling" or "3D Without Effects", sample buffers will not be allocated. This means [code]SCREEN_TEXTURE[/code] and [code]DEPTH_TEXTURE[/code] will not be available in shaders and post-processing effects will not be available in the [Environment].
 		</member>
 		<member name="rendering/quality/intended_usage/framebuffer_allocation.mobile" type="int" setter="" getter="" default="3">
+			Same as [member rendering/quality/intended_usage/framebuffer_allocation] but for mobile defaults to "3D Without Effects". If effects are desired, set to "3D".
 		</member>
 		<member name="rendering/quality/reflections/atlas_size" type="int" setter="" getter="" default="2048">
+			Size of the atlas used by reflection probes. A larger size can result in higher visual quality, while a smaller size will be faster and take up less memory.
 		</member>
 		<member name="rendering/quality/reflections/atlas_subdiv" type="int" setter="" getter="" default="8">
+			Number of subdivisions to use for the reflection atlas. A higher number lowers the quality of each atlas, but allows you to use more.
 		</member>
 		<member name="rendering/quality/reflections/high_quality_ggx" type="bool" setter="" getter="" default="true">
 			If [code]true[/code], uses a high amount of samples to create blurred variants of reflection probes and panorama backgrounds (sky). Those blurred variants are used by rough materials.

doc/classes/ReflectionProbe.xml

@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		Capture its surroundings as a dual parabolid image, and stores versions of it with increasing levels of blur to simulate different material roughnesses.
+		The [ReflectionProbe] is used to create high-quality reflections at the cost of performance. It can be combined with [GIProbe]s and Screen Space Reflections to achieve high quality reflections. [ReflectionProbe]s render all objects within their [member cull_mask], so updating them can be quite expensive. It is best to update them once with the important static objects and then leave them.
 	</description>
 	<tutorials>
 		<link>https://docs.godotengine.org/en/latest/tutorials/3d/reflection_probes.html</link>
@@ -16,34 +17,45 @@
 			If [code]true[/code], enables box projection. This makes reflections look more correct in rectangle-shaped rooms by offsetting the reflection center depending on the camera's location.
 		</member>
 		<member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="1048575">
+			Sets the cull mask which determines what objects are drawn by this probe. Every [VisualInstance] with a layer included in this cull mask will be rendered by the probe. It is best to only include large objects which are likely to take up a lot of space in the reflection in order to save on rendering cost.
 		</member>
 		<member name="enable_shadows" type="bool" setter="set_enable_shadows" getter="are_shadows_enabled" default="false">
 			If [code]true[/code], computes shadows in the reflection probe. This makes the reflection probe slower to render; you may want to disable this if using the [constant UPDATE_ALWAYS] [member update_mode].
 		</member>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3( 1, 1, 1 )">
+			The size of the reflection probe. The larger the extents the more space covered by the probe which will lower the perceived resolution. It is best to keep the extents only as large as you need them.
 		</member>
 		<member name="intensity" type="float" setter="set_intensity" getter="get_intensity" default="1.0">
-			Defines the reflection intensity.
+			Defines the reflection intensity. Intensity modulates the strength of the reflection.
 		</member>
 		<member name="interior_ambient_color" type="Color" setter="set_interior_ambient" getter="get_interior_ambient" default="Color( 0, 0, 0, 1 )">
+			Sets the ambient light color to be used when this probe is set to [member interior_enable].
 		</member>
 		<member name="interior_ambient_contrib" type="float" setter="set_interior_ambient_probe_contribution" getter="get_interior_ambient_probe_contribution" default="0.0">
+			Sets the contribution value for how much the reflection affects the ambient light for this reflection probe when set to [member interior_enable]. Useful so that ambient light matches the color of the room.
 		</member>
 		<member name="interior_ambient_energy" type="float" setter="set_interior_ambient_energy" getter="get_interior_ambient_energy" default="1.0">
+			Sets the energy multiplier for this reflection probe's ambient light contribution when set to [member interior_enable].
 		</member>
 		<member name="interior_enable" type="bool" setter="set_as_interior" getter="is_set_as_interior" default="false">
+			If [code]true[/code], reflections will ignore sky contribution. Ambient lighting is then controlled by the [code]interior_ambient_*[/code] properties.
 		</member>
 		<member name="max_distance" type="float" setter="set_max_distance" getter="get_max_distance" default="0.0">
+			Sets the max distance away from the probe an object can be before it is culled.
 		</member>
 		<member name="origin_offset" type="Vector3" setter="set_origin_offset" getter="get_origin_offset" default="Vector3( 0, 0, 0 )">
+			Sets the origin offset to be used when this reflection probe is in box project mode.
 		</member>
 		<member name="update_mode" type="int" setter="set_update_mode" getter="get_update_mode" enum="ReflectionProbe.UpdateMode" default="0">
+			Sets how frequently the probe is updated. Can be [constant UPDATE_ONCE] or [constant UPDATE_ALWAYS].
 		</member>
 	</members>
 	<constants>
 		<constant name="UPDATE_ONCE" value="0" enum="UpdateMode">
+			Update the probe once on the next frame.
 		</constant>
 		<constant name="UPDATE_ALWAYS" value="1" enum="UpdateMode">
+			Update the probe every frame. This is needed when you want to capture dynamic objects. However, it results in an increased render time. Use [constant UPDATE_ONCE] whenever possible.
 		</constant>
 	</constants>
 </class>

doc/classes/SpatialMaterial.xml

@@ -106,7 +106,7 @@
 			Sets the strength of the clearcoat effect. Setting to [code]0[/code] looks the same as disabling the clearcoat effect.
 		</member>
 		<member name="clearcoat_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
-			If [code]true[/code], clearcoat rendering is enabled. Adds a secondary transparent pass to the lighting calculation resulting in an added specular blob. This makes materials appear as if they have a clear layer on them that can either by glossy or rough.
+			If [code]true[/code], clearcoat rendering is enabled. Adds a secondary transparent pass to the lighting calculation resulting in an added specular blob. This makes materials appear as if they have a clear layer on them that can be either glossy or rough.
 		</member>
 		<member name="clearcoat_gloss" type="float" setter="set_clearcoat_gloss" getter="get_clearcoat_gloss">
 			Sets the roughness of the clearcoat pass. A higher value results in a smoother clearcoat while a lower value results in a rougher clearcoat.

modules/csg/doc_classes/CSGMesh.xml

@@ -12,9 +12,10 @@
 	</methods>
 	<members>
 		<member name="material" type="Material" setter="set_material" getter="get_material">
+			The [Material] used in drawing the CSG shape.
 		</member>
 		<member name="mesh" type="Mesh" setter="set_mesh" getter="get_mesh">
-			The mesh resource to use as a CSG shape.
+			The [Mesh] resource to use as a CSG shape.
 		</member>
 	</members>
 	<constants>

modules/csg/doc_classes/CSGPrimitive.xml

@@ -4,6 +4,7 @@
 		Base class for CSG primitives.
 	</brief_description>
 	<description>
+		Parent class for various CSG primitives. It contains code and functionality that is common between them. It cannot be used directly. Instead use one of the various classes that inherit from it.
 	</description>
 	<tutorials>
 	</tutorials>

modules/csg/doc_classes/CSGShape.xml

@@ -31,6 +31,7 @@
 			<return type="Array">
 			</return>
 			<description>
+				Returns an [Array] with two elements, the first is the [Transform] of this node and the second is the root [Mesh] of this node. Only works when this node is the root shape.
 			</description>
 		</method>
 		<method name="is_root_shape" qualifiers="const">
@@ -79,6 +80,7 @@
 			The operation that is performed on this shape. This is ignored for the first CSG child node as the operation is between this node and the previous child of this nodes parent.
 		</member>
 		<member name="snap" type="float" setter="set_snap" getter="get_snap" default="0.001">
+			Snap makes the mesh snap to a given distance so that the faces of two meshes can be perfectly aligned. A lower value results in greater precision but may be harder to adjust.
 		</member>
 		<member name="use_collision" type="bool" setter="set_use_collision" getter="is_using_collision" default="false">
 			Adds a collision shape to the physics engine for our CSG shape. This will always act like a static body. Note that the collision shape is still active even if the CSG shape itself is hidden.