Merge pull request #8539 from clayjohn/doc_surfacetool

Added documentation for SurfaceTool

doc/base/classes.xml

@@ -43086,43 +43086,58 @@
 		Helper tool to create geometry.
 	</brief_description>
 	<description>
-		Helper tool to create geometry.
+		The [SurfaceTool] is used to construct a [Mesh] by specifying vertex attributes individually. It can be used to construct a [Mesh] from script. All properties except index need to be added before a call to [method add_vertex]. For example adding vertex colors and UVs looks like
+		[codeblock]
+		var st = SurfaceTool.new()
+		st.begin(Mesh.PRIMITIVE_TRIANGLES)
+		st.add_color(Color(1, 0, 0))
+		st.add_uv(Vector2(0, 0))
+		st.add_vertex(Vector3(0, 0, 0))
+		[/codeblock]
+		The [SurfaceTool] now contains one vertex of a triangle which has a UV coordinate and a specified [Color]. If another vertex were added without calls to [method add_uv] or [method add_color] then the last values would be used.
+		It is very important that vertex attributes are passed [b]before[/b] the call to [method add_vertex], failure to do this will result in an error when committing the vertex information to a mesh.
 	</description>
 	<methods>
 		<method name="add_bones">
 			<argument index="0" name="bones" type="PoolIntArray">
 			</argument>
 			<description>
+				Add an array of bones for the next Vertex to use.
 			</description>
 		</method>
 		<method name="add_color">
 			<argument index="0" name="color" type="Color">
 			</argument>
 			<description>
+				Specify a [Color] for the next Vertex to use.
 			</description>
 		</method>
 		<method name="add_index">
 			<argument index="0" name="index" type="int">
 			</argument>
 			<description>
+				Adds an index to index array if you are using indexed Vertices. Does not need to be called before adding Vertex.
 			</description>
 		</method>
 		<method name="add_normal">
 			<argument index="0" name="normal" type="Vector3">
 			</argument>
 			<description>
+				Specify a normal for the next Vertex to use.
 			</description>
 		</method>
 		<method name="add_smooth_group">
 			<argument index="0" name="smooth" type="bool">
 			</argument>
 			<description>
+				Specify whether current Vertex (if using only Vertex arrays) or current index (if also using index arrays) should utilize smooth normals for normal calculation.
 			</description>
 		</method>
 		<method name="add_tangent">
 			<argument index="0" name="tangent" type="Plane">
 			</argument>
 			<description>
+				Specify a Tangent for the next Vertex to use.
 			</description>
 		</method>
 		<method name="add_triangle_fan">
@@ -43139,40 +43154,47 @@
 			<argument index="5" name="tangents" type="Array" default="Array()">
 			</argument>
 			<description>
+				Insert a triangle fan made of array data into [Mesh] being constructed.
 			</description>
 		</method>
 		<method name="add_uv">
 			<argument index="0" name="uv" type="Vector2">
 			</argument>
 			<description>
+				Specify UV Coordinate for next Vertex to use.
 			</description>
 		</method>
 		<method name="add_uv2">
 			<argument index="0" name="uv2" type="Vector2">
 			</argument>
 			<description>
+				Specify an optional second set of UV coordinates for next Vertex to use.
 			</description>
 		</method>
 		<method name="add_vertex">
 			<argument index="0" name="vertex" type="Vector3">
 			</argument>
 			<description>
+				Specify position of current Vertex. Should be called after specifying other vertex properties (e.g. Color, UV).
 			</description>
 		</method>
 		<method name="add_weights">
 			<argument index="0" name="weights" type="PoolRealArray">
 			</argument>
 			<description>
+				Specify weight value for next Vertex to use.
 			</description>
 		</method>
 		<method name="begin">
 			<argument index="0" name="primitive" type="int">
 			</argument>
 			<description>
+				Called before adding any Vertices. Takes the primitive type as an argument (e.g. Mesh.PRIMITIVE_TRIANGLES).
 			</description>
 		</method>
 		<method name="clear">
 			<description>
+				Clear all information passed into the surface tool so far.
 			</description>
 		</method>
 		<method name="commit">
@@ -43181,24 +43203,29 @@
 			<argument index="0" name="existing" type="Mesh" default="NULL">
 			</argument>
 			<description>
+				Returns a constructed [Mesh] from current information passed in. If an existing [Mesh] is passed in as an argument, will add an extra surface to the existing [Mesh].
 			</description>
 		</method>
 		<method name="deindex">
 			<description>
+				Removes index array by expanding Vertex array.
 			</description>
 		</method>
 		<method name="generate_normals">
 			<description>
+				Generates normals from Vertices so you do not have to do it manually.
 			</description>
 		</method>
 		<method name="index">
 			<description>
+				Shrinks Vertex array by creating an index array. Avoids reusing Vertices.
 			</description>
 		</method>
 		<method name="set_material">
 			<argument index="0" name="material" type="Material">
 			</argument>
 			<description>
+				Sets [Material] to be used by the [Mesh] you are constructing.
 			</description>
 		</method>
 	</methods>