<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<c74object name="sdt.impact~">

	<digest>
		[solids, interactor] Impact interaction between two solid objects.
	</digest>

	<description>
		<o>sdt.impact~</o> simulates the nonlinear impact force generated by two objects colliding (e.g. a hammer hitting a resonator).
		<br />
		N.B. It must be used in conjuction with two solid object models (either <o>sdt.inertial~</o> or <o>sdt.modal~</o>)
		forming a structure "object0 &#8596; <o>sdt.impact~</o> &#8596; object1".
		This is achieved by specifying the two objects' IDs as creation arguments.
		<br />
		Outlets: Their number depends on the creation argument <ar>Max-outlets</ar>.
		They output signals respectively representing the displacement (m) at each pickup point of the interacting objects, starting
		from those of object0 and then of object1.
		Such displacement represent the sound (actually, vibration) produced at various locations on the objects.
		<br />
		<br />
		Impact force is computed from the relative position and velocity between the contact points of the two objects and
		is made up of an elastic component and a dissipative one:
		<br />
		* The elastic term is described by the force stiffness (parameter <i>k</i>) and an exponent (parameter <i>alpha</i>) which represents
		the sharpness of the hammer.
		<br />
		* The dissipative component is described by a dissipation factor (parameter <i>mu</i>).
	</description>

	<!--METADATA-->
	<metadatalist>
		<metadata name="tag">Sound Design Toolkit</metadata>
	</metadatalist>

	<!--INLETS
	<inletlist>
		<inlet id="0" type="message">
			<digest>test</digest>
			<description></description>
		</inlet>

		<inlet id="0" type="signal">
			<digest>External force on object0 (N).</digest>
			<description></description>
		</inlet>

		<inlet id="1" type="signal">
			<digest>Impact velocity of object0 (m/s). Also puts object0 and object1 in contact.</digest>
			<description></description>
		</inlet>

		<inlet id="2" type="signal">
			<digest>Fragment size for object0 [0., 1.]. Used by compound models such as <o>sdt.breaking~</o>.</digest>
			<description></description>
		</inlet>

		<inlet id="3" type="signal">
			<digest>External force on object1 (N).</digest>
			<description></description>
		</inlet>

		<inlet id="4" type="signal">
			<digest>Impact velocity of object1 (m/s). Also puts object0 and object1 in contact.</digest>
			<description></description>
		</inlet>

		<inlet id="5" type="signal">
			<digest>Fragment size of object1 [0., 1.]. Used by compound models such as <o>sdt.breaking~</o>.</digest>
			<description></description>
		</inlet>
	</inletlist>
	-->

	<!--OUTLETS The number of outlets dynamically changes according to the creation argument <ar>Max-outlets</ar>
	<outletlist>
		<outlet id="0" type="signal">
			<digest>Output sound / displacement at the respective pickup point (m).</digest>
		</outlet>
	</outletlist>
	-->

	<!--ARGUMENTS-->
	<objarglist>
		<objarg name="Unique_ID-object0" optional="0" type="symbol">
			<digest>Mandatory: Name of first object (object0) to be referenced (typically <o>sdt.inertial</o>).</digest>
		</objarg>

		<objarg name="Unique_ID-object1" optional="0" type="symbol">
			<digest>Mandatory: Name of second object (object1) to be referenced (typically <o>sdt.modal</o>).</digest>.
		</objarg>

		<objarg name="Max-outlets" optional="0" type="int">
			<digest>Mandatory: Maximum number of outlets. They should correspond to the total number of pickups of object0 + object1.
							If greater than the number of pickup points, the unused outlets are disabled;
							if lower than the number of pickup points, only the first ones are output,
							always starting from pickup0.
			</digest>
		</objarg>
	</objarglist>

	<!--MESSAGES-->
	<methodlist>
		<method name="messages">
			<digest>
				Inlet 0: Messages and attributes to the object.
			</digest>
			<description>
			</description>
		</method>

		<method name="signal">
			<digest>
				All inlets accept signals (see description below).
			</digest>
			<description>
				Inlet 0: External force on object0 (N). <br />
			  Inlet 1: Sets the velocity of object0 (m/s) and puts the two objects in contact. <br />
				Inlet 2: Fragment size of object0 [0., 1.].<br />
			  Inlet 3: External force on object1 (N). <br />
			  Inlet 4: Sets the velocity of object1 (m/s) and puts the two objects in contact. <br />
				Inlet 5: Fragment size of the object1 [0., 1.].
			</description>
		</method>
	</methodlist>

	<!--ATTRIBUTES-->
	<attributelist>
		<attribute name="stiffness" get="1" set="1" type="float" size="1" >
				<digest>Impact stiffness.</digest>
				<description></description>
		</attribute>

		<attribute name="dissipation" get="1" set="1" type="float" size="1">
				<digest>Dissipation coefficient [0., 1.].</digest>
				<description></description>
		</attribute>

		<attribute name="shape" get="1" set="1" type="float" size="1" >
				<digest>Contact shape factor (1.5 for spherical objects).</digest>
				<description></description>
		</attribute>

		<attribute name="contact0" get="1" set="1" type="int" size="1" >
				<digest>Pickup index of the contact point for object0 (hammer).</digest>
				<description></description>
		</attribute>

		<attribute name="contact1" get="1" set="1" type="int" size="1" >
				<digest>Pickup index of the contact point for object1 (resonator).</digest>
				<description></description>
		</attribute>
	</attributelist>

	<!--SEEALSO-->
	<seealsolist>
		<seealso name="sdt.inertial"/>
		<seealso name="sdt.modal"/>
		<seealso name="sdt.friction~"/>
		<seealso name="sdt.bouncing~"/>
		<seealso name="sdt.breaking~"/>
		<seealso name="sdt.crumpling~"/>
		<seealso name="sdt.rolling~"/>
		<seealso name="sdt.scraping~"/>
	</seealsolist>

</c74object>
