Merge pull request #91818 from rburing/fti_multimesh

Physics interpolation: `MultiMesh`

2 files changed, 71 insertions, 0 deletions

diff --git a/doc/classes/MultiMesh.xml b/doc/classes/MultiMesh.xml
index 529912171c..e99694c3f0 100644
--- a/doc/classes/MultiMesh.xml
+++ b/doc/classes/MultiMesh.xml
@@ -51,6 +51,24 @@
 				Returns the [Transform2D] of a specific instance.
 			</description>
 		</method>
+		<method name="reset_instance_physics_interpolation">
+			<return type="void" />
+			<param index="0" name="instance" type="int" />
+			<description>
+				When using [i]physics interpolation[/i], this function allows you to prevent interpolation on an instance in the current physics tick.
+				This allows you to move instances instantaneously, and should usually be used when initially placing an instance such as a bullet to prevent graphical glitches.
+			</description>
+		</method>
+		<method name="set_buffer_interpolated">
+			<return type="void" />
+			<param index="0" name="buffer_curr" type="PackedFloat32Array" />
+			<param index="1" name="buffer_prev" type="PackedFloat32Array" />
+			<description>
+				An alternative to setting the [member buffer] property, which can be used with [i]physics interpolation[/i]. This method takes two arrays, and can set the data for the current and previous tick in one go. The renderer will automatically interpolate the data at each frame.
+				This is useful for situations where the order of instances may change from physics tick to tick, such as particle systems.
+				When the order of instances is coherent, the simpler alternative of setting [member buffer] can still be used with interpolation.
+			</description>
+		</method>
 		<method name="set_instance_color">
 			<return type="void" />
 			<param index="0" name="instance" type="int" />
@@ -109,6 +127,11 @@
 			[Mesh] resource to be instanced.
 			The looks of the individual instances can be modified using [method set_instance_color] and [method set_instance_custom_data].
 		</member>
+		<member name="physics_interpolation_quality" type="int" setter="set_physics_interpolation_quality" getter="get_physics_interpolation_quality" enum="MultiMesh.PhysicsInterpolationQuality" default="0">
+			Choose whether to use an interpolation method that favors speed or quality.
+			When using low physics tick rates (typically below 20) or high rates of object rotation, you may get better results from the high quality setting.
+			[b]Note:[/b] Fast quality does not equate to low quality. Except in the special cases mentioned above, the quality should be comparable to high quality.
+		</member>
 		<member name="transform_2d_array" type="PackedVector2Array" setter="_set_transform_2d_array" getter="_get_transform_2d_array" deprecated="Accessing this property is very slow. Use [method set_instance_transform_2d] and [method get_instance_transform_2d] instead.">
 			Array containing each [Transform2D] value used by all instances of this mesh, as a [PackedVector2Array]. Each transform is divided into 3 [Vector2] values corresponding to the transforms' [code]x[/code], [code]y[/code], and [code]origin[/code].
 		</member>
@@ -135,5 +158,11 @@
 		<constant name="TRANSFORM_3D" value="1" enum="TransformFormat">
 			Use this when using 3D transforms.
 		</constant>
+		<constant name="INTERP_QUALITY_FAST" value="0" enum="PhysicsInterpolationQuality">
+			Always interpolate using Basis lerping, which can produce warping artifacts in some situations.
+		</constant>
+		<constant name="INTERP_QUALITY_HIGH" value="1" enum="PhysicsInterpolationQuality">
+			Attempt to interpolate using Basis slerping (spherical linear interpolation) where possible, otherwise fall back to lerping.
+		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml
index edc3dc8793..c81d5d4fab 100644
--- a/doc/classes/RenderingServer.xml
+++ b/doc/classes/RenderingServer.xml
@@ -2566,6 +2566,15 @@
 				Returns the [Transform2D] of the specified instance. For use when the multimesh is set to use 2D transforms.
 			</description>
 		</method>
+		<method name="multimesh_instance_reset_physics_interpolation">
+			<return type="void" />
+			<param index="0" name="multimesh" type="RID" />
+			<param index="1" name="index" type="int" />
+			<description>
+				Prevents physics interpolation for the specified instance during the current physics tick.
+				This is useful when moving an instance to a new location, to give an instantaneous change rather than interpolation from the previous location.
+			</description>
+		</method>
 		<method name="multimesh_instance_set_color">
 			<return type="void" />
 			<param index="0" name="multimesh" type="RID" />
@@ -2623,6 +2632,16 @@
 				[/codeblock]
 			</description>
 		</method>
+		<method name="multimesh_set_buffer_interpolated">
+			<return type="void" />
+			<param index="0" name="multimesh" type="RID" />
+			<param index="1" name="buffer" type="PackedFloat32Array" />
+			<param index="2" name="buffer_previous" type="PackedFloat32Array" />
+			<description>
+				Alternative version of [method multimesh_set_buffer] for use with physics interpolation.
+				Takes both an array of current data and an array of data for the previous physics tick.
+			</description>
+		</method>
 		<method name="multimesh_set_custom_aabb">
 			<return type="void" />
 			<param index="0" name="multimesh" type="RID" />
@@ -2639,6 +2658,23 @@
 				Sets the mesh to be drawn by the multimesh. Equivalent to [member MultiMesh.mesh].
 			</description>
 		</method>
+		<method name="multimesh_set_physics_interpolated">
+			<return type="void" />
+			<param index="0" name="multimesh" type="RID" />
+			<param index="1" name="interpolated" type="bool" />
+			<description>
+				Turns on and off physics interpolation for this MultiMesh resource.
+			</description>
+		</method>
+		<method name="multimesh_set_physics_interpolation_quality">
+			<return type="void" />
+			<param index="0" name="multimesh" type="RID" />
+			<param index="1" name="quality" type="int" enum="RenderingServer.MultimeshPhysicsInterpolationQuality" />
+			<description>
+				Sets the physics interpolation quality for the [MultiMesh].
+				A value of [constant MULTIMESH_INTERP_QUALITY_FAST] gives fast but low quality interpolation, a value of [constant MULTIMESH_INTERP_QUALITY_HIGH] gives slower but higher quality interpolation.
+			</description>
+		</method>
 		<method name="multimesh_set_visible_instances">
 			<return type="void" />
 			<param index="0" name="multimesh" type="RID" />
@@ -4508,6 +4544,12 @@
 		<constant name="MULTIMESH_TRANSFORM_3D" value="1" enum="MultimeshTransformFormat">
 			Use [Transform3D] to store MultiMesh transform.
 		</constant>
+		<constant name="MULTIMESH_INTERP_QUALITY_FAST" value="0" enum="MultimeshPhysicsInterpolationQuality">
+			MultiMesh physics interpolation favors speed over quality.
+		</constant>
+		<constant name="MULTIMESH_INTERP_QUALITY_HIGH" value="1" enum="MultimeshPhysicsInterpolationQuality">
+			MultiMesh physics interpolation favors quality over speed.
+		</constant>
 		<constant name="LIGHT_PROJECTOR_FILTER_NEAREST" value="0" enum="LightProjectorFilter">
 			Nearest-neighbor filter for light projectors (use for pixel art light projectors). No mipmaps are used for rendering, which means light projectors at a distance will look sharp but grainy. This has roughly the same performance cost as using mipmaps.
 		</constant>