Merge pull request #104561 from Calinou/doc-csgshape3d-deferred-updates

Document CSGShape3D updates being deferred until the next frame

modules/csg/doc_classes/CSGShape3D.xml

@@ -5,11 +5,10 @@
 	</brief_description>
 	<description>
 		This is the CSG base class that provides CSG operation support to the various CSG nodes in Godot.
-		[b]Performance:[/b] CSG nodes are only intended for prototyping as they have a significant CPU performance cost.
-		Consider baking final CSG operation results into static geometry that replaces the CSG nodes.
+		[b]Performance:[/b] CSG nodes are only intended for prototyping as they have a significant CPU performance cost. Consider baking final CSG operation results into static geometry that replaces the CSG nodes.
 		Individual CSG root node results can be baked to nodes with static resources with the editor menu that appears when a CSG root node is selected.
 		Individual CSG root nodes can also be baked to static resources with scripts by calling [method bake_static_mesh] for the visual mesh or [method bake_collision_shape] for the physics collision.
-		Entire scenes of CSG nodes can be baked to static geometry and exported with the editor gltf scene exporter.
+		Entire scenes of CSG nodes can be baked to static geometry and exported with the editor glTF scene exporter: [b]Scene &gt; Export As... &gt; glTF 2.0 Scene...[/b]
 	</description>
 	<tutorials>
 		<link title="Prototyping levels with CSG">$DOCS_URL/tutorials/3d/csg_tools.html</link>
@@ -20,12 +19,14 @@
 			<description>
 				Returns a baked physics [ConcavePolygonShape3D] of this node's CSG operation result. Returns an empty shape if the node is not a CSG root node or has no valid geometry.
 				[b]Performance:[/b] If the CSG operation results in a very detailed geometry with many faces physics performance will be very slow. Concave shapes should in general only be used for static level geometry and not with dynamic objects that are moving.
+				[b]Note:[/b] CSG mesh data updates are deferred, which means they are updated with a delay of one rendered frame. To avoid getting an empty shape or outdated mesh data, make sure to call [code]await get_tree().process_frame[/code] before using [method bake_collision_shape] in [method Node._ready] or after changing properties on the [CSGShape3D].
 			</description>
 		</method>
 		<method name="bake_static_mesh">
 			<return type="ArrayMesh" />
 			<description>
 				Returns a baked static [ArrayMesh] of this node's CSG operation result. Materials from involved CSG nodes are added as extra mesh surfaces. Returns an empty mesh if the node is not a CSG root node or has no valid geometry.
+				[b]Note:[/b] CSG mesh data updates are deferred, which means they are updated with a delay of one rendered frame. To avoid getting an empty mesh or outdated mesh data, make sure to call [code]await get_tree().process_frame[/code] before using [method bake_static_mesh] in [method Node._ready] or after changing properties on the [CSGShape3D].
 			</description>
 		</method>
 		<method name="get_collision_layer_value" qualifiers="const">
@@ -46,6 +47,7 @@
 			<return type="Array" />
 			<description>
 				Returns an [Array] with two elements, the first is the [Transform3D] of this node and the second is the root [Mesh] of this node. Only works when this node is the root shape.
+				[b]Note:[/b] CSG mesh data updates are deferred, which means they are updated with a delay of one rendered frame. To avoid getting an empty shape or outdated mesh data, make sure to call [code]await get_tree().process_frame[/code] before using [method get_meshes] in [method Node._ready] or after changing properties on the [CSGShape3D].
 			</description>
 		</method>
 		<method name="is_root_shape" qualifiers="const">
@@ -73,7 +75,7 @@
 	</methods>
 	<members>
 		<member name="calculate_tangents" type="bool" setter="set_calculate_tangents" getter="is_calculating_tangents" default="true">
-			Calculate tangents for the CSG shape which allows the use of normal maps. This is only applied on the root shape, this setting is ignored on any child.
+			Calculate tangents for the CSG shape which allows the use of normal and height maps. This is only applied on the root shape, this setting is ignored on any child. Setting this to [code]false[/code] can speed up shape generation slightly.
 		</member>
 		<member name="collision_layer" type="int" setter="set_collision_layer" getter="get_collision_layer" default="1">
 			The physics layers this area is in.