Merge pull request #28330 from BastiaanOlij/improve_multimesh

Added set_as_bulk_array, fixed transform2D saving and documentation

doc/classes/MultiMesh.xml

@@ -44,7 +44,7 @@
 			<argument index="0" name="instance" type="int">
 			</argument>
 			<description>
-				Return the transform of a specific instance.
+				Return the [Transform] of a specific instance.
 			</description>
 		</method>
 		<method name="get_instance_transform_2d" qualifiers="const">
@@ -53,6 +53,18 @@
 			<argument index="0" name="instance" type="int">
 			</argument>
 			<description>
+				Return the [Transform2D] of a specific instance.
+			</description>
+		</method>
+		<method name="set_as_bulk_array">
+			<return type="void">
+			</return>
+			<argument index="0" name="arg0" type="PoolRealArray">
+			</argument>
+			<description>
+				Set all data related to the instances in one go. This is especially useful when loading the data from disk or preparing the data from GDNative.
+				All data is packed in one large float array. An array may look like this: Transform for instance 1, color data for instance 1, custom data for instance 1, transform for instance 2, color data for instance 2, etc...
+				[Transform] is stored as 12 floats, [Transform2D] is stored as 8 floats, COLOR_8BIT / CUSTOM_DATA_8BIT is stored as 1 float (4 bytes as is) and COLOR_FLOAT / CUSTOM_DATA_FLOAT is stored as 4 floats.
 			</description>
 		</method>
 		<method name="set_instance_color">
@@ -86,7 +98,7 @@
 			<argument index="1" name="transform" type="Transform">
 			</argument>
 			<description>
-				Set the transform for a specific instance.
+				Set the [Transform] for a specific instance.
 			</description>
 		</method>
 		<method name="set_instance_transform_2d">
@@ -97,6 +109,7 @@
 			<argument index="1" name="transform" type="Transform2D">
 			</argument>
 			<description>
+				Set the [Transform2D] for a specific instance.
 			</description>
 		</method>
 	</methods>
@@ -108,7 +121,7 @@
 			Format of custom data in custom data array that gets passed to shader.
 		</member>
 		<member name="instance_count" type="int" setter="set_instance_count" getter="get_instance_count">
-			Number of instances that will get drawn.
+			Number of instances that will get drawn. This clears and (re)sizes the buffers. By default all instances are drawn but you can limit this with [member visible_instance_count].
 		</member>
 		<member name="mesh" type="Mesh" setter="set_mesh" getter="get_mesh">
 			Mesh to be drawn.
@@ -117,6 +130,7 @@
 			Format of transform used to transform mesh, either 2D or 3D.
 		</member>
 		<member name="visible_instance_count" type="int" setter="set_visible_instance_count" getter="get_visible_instance_count">
+			Limits the number of instances drawn, -1 draws all instances. Changing this does not change the sizes of the buffers.
 		</member>
 	</members>
 	<constants>

scene/resources/multimesh.cpp

@@ -32,6 +32,8 @@
 #include "servers/visual_server.h"
 
 void MultiMesh::_set_transform_array(const PoolVector<Vector3> &p_array) {
+	if (transform_format != TRANSFORM_3D)
+		return;
 
 	PoolVector<Vector3> xforms = p_array;
 	int len = xforms.size();
@@ -55,6 +57,9 @@ void MultiMesh::_set_transform_array(const PoolVector<Vector3> &p_array) {
 
 PoolVector<Vector3> MultiMesh::_get_transform_array() const {
 
+	if (transform_format != TRANSFORM_3D)
+		return PoolVector<Vector3>();
+
 	if (instance_count == 0)
 		return PoolVector<Vector3>();
 
@@ -75,6 +80,54 @@ PoolVector<Vector3> MultiMesh::_get_transform_array() const {
 	return xforms;
 }
 
+void MultiMesh::_set_transform_2d_array(const PoolVector<Vector2> &p_array) {
+
+	if (transform_format != TRANSFORM_2D)
+		return;
+
+	PoolVector<Vector2> xforms = p_array;
+	int len = xforms.size();
+	ERR_FAIL_COND((len / 3) != instance_count);
+	if (len == 0)
+		return;
+
+	PoolVector<Vector2>::Read r = xforms.read();
+
+	for (int i = 0; i < len / 3; i++) {
+
+		Transform2D t;
+		t.elements[0] = r[i * 3 + 0];
+		t.elements[1] = r[i * 3 + 1];
+		t.elements[2] = r[i * 3 + 2];
+
+		set_instance_transform_2d(i, t);
+	}
+}
+
+PoolVector<Vector2> MultiMesh::_get_transform_2d_array() const {
+
+	if (transform_format != TRANSFORM_2D)
+		return PoolVector<Vector2>();
+
+	if (instance_count == 0)
+		return PoolVector<Vector2>();
+
+	PoolVector<Vector2> xforms;
+	xforms.resize(instance_count * 3);
+
+	PoolVector<Vector2>::Write w = xforms.write();
+
+	for (int i = 0; i < instance_count; i++) {
+
+		Transform2D t = get_instance_transform_2d(i);
+		w[i * 3 + 0] = t.elements[0];
+		w[i * 3 + 1] = t.elements[1];
+		w[i * 3 + 2] = t.elements[2];
+	}
+
+	return xforms;
+}
+
 void MultiMesh::_set_color_array(const PoolVector<Color> &p_array) {
 
 	PoolVector<Color> colors = p_array;
@@ -210,6 +263,11 @@ Color MultiMesh::get_instance_custom_data(int p_instance) const {
 	return VisualServer::get_singleton()->multimesh_instance_get_custom_data(multimesh, p_instance);
 }
 
+void MultiMesh::set_as_bulk_array(const PoolVector<float> &p_array) {
+
+	VisualServer::get_singleton()->multimesh_set_as_bulk_array(multimesh, p_array);
+}
+
 AABB MultiMesh::get_aabb() const {
 
 	return VisualServer::get_singleton()->multimesh_get_aabb(multimesh);
@@ -275,10 +333,13 @@ void MultiMesh::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("get_instance_color", "instance"), &MultiMesh::get_instance_color);
 	ClassDB::bind_method(D_METHOD("set_instance_custom_data", "instance", "custom_data"), &MultiMesh::set_instance_custom_data);
 	ClassDB::bind_method(D_METHOD("get_instance_custom_data", "instance"), &MultiMesh::get_instance_custom_data);
+	ClassDB::bind_method(D_METHOD("set_as_bulk_array", "array"), &MultiMesh::set_as_bulk_array);
 	ClassDB::bind_method(D_METHOD("get_aabb"), &MultiMesh::get_aabb);
 
 	ClassDB::bind_method(D_METHOD("_set_transform_array"), &MultiMesh::_set_transform_array);
 	ClassDB::bind_method(D_METHOD("_get_transform_array"), &MultiMesh::_get_transform_array);
+	ClassDB::bind_method(D_METHOD("_set_transform_2d_array"), &MultiMesh::_set_transform_2d_array);
+	ClassDB::bind_method(D_METHOD("_get_transform_2d_array"), &MultiMesh::_get_transform_2d_array);
 	ClassDB::bind_method(D_METHOD("_set_color_array"), &MultiMesh::_set_color_array);
 	ClassDB::bind_method(D_METHOD("_get_color_array"), &MultiMesh::_get_color_array);
 	ClassDB::bind_method(D_METHOD("_set_custom_data_array"), &MultiMesh::_set_custom_data_array);
@@ -291,6 +352,7 @@ void MultiMesh::_bind_methods() {
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "visible_instance_count", PROPERTY_HINT_RANGE, "-1,16384,1,or_greater"), "set_visible_instance_count", "get_visible_instance_count");
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "mesh", PROPERTY_HINT_RESOURCE_TYPE, "Mesh"), "set_mesh", "get_mesh");
 	ADD_PROPERTY(PropertyInfo(Variant::POOL_VECTOR3_ARRAY, "transform_array", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NOEDITOR | PROPERTY_USAGE_INTERNAL), "_set_transform_array", "_get_transform_array");
+	ADD_PROPERTY(PropertyInfo(Variant::POOL_VECTOR2_ARRAY, "transform_2d_array", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NOEDITOR | PROPERTY_USAGE_INTERNAL), "_set_transform_2d_array", "_get_transform_2d_array");
 	ADD_PROPERTY(PropertyInfo(Variant::POOL_COLOR_ARRAY, "color_array", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NOEDITOR | PROPERTY_USAGE_INTERNAL), "_set_color_array", "_get_color_array");
 	ADD_PROPERTY(PropertyInfo(Variant::POOL_COLOR_ARRAY, "custom_data_array", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NOEDITOR | PROPERTY_USAGE_INTERNAL), "_set_custom_data_array", "_get_custom_data_array");
 

scene/resources/multimesh.h

@@ -72,6 +72,9 @@ protected:
 	void _set_transform_array(const PoolVector<Vector3> &p_array);
 	PoolVector<Vector3> _get_transform_array() const;
 
+	void _set_transform_2d_array(const PoolVector<Vector2> &p_array);
+	PoolVector<Vector2> _get_transform_2d_array() const;
+
 	void _set_color_array(const PoolVector<Color> &p_array);
 	PoolVector<Color> _get_color_array() const;
 
@@ -108,6 +111,8 @@ public:
 	void set_instance_custom_data(int p_instance, const Color &p_custom_data);
 	Color get_instance_custom_data(int p_instance) const;
 
+	void set_as_bulk_array(const PoolVector<float> &p_array);
+
 	virtual AABB get_aabb() const;
 
 	virtual RID get_rid() const;