<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<!--This is an automatically generated file. DO NOT EDIT THIS FILE DIRECTLY. Rather, use the _ref.xml files found in the 'edits' folder.-->
<c74object name="jit.anim.drive" module="jit" category="Jitter Animation">
	<digest>
		Animate a 3D transform
	</digest>
	<description>
		Animates relative transforms over time with easing. The <o>jit.anim.drive</o> object works in conjunction with <o>jit.anim.node</o> and OpenGL objects to perform this function. Double clicking the object will open a ui mapping dictionary, allowing certain user interface actions to be mapped to animation messages.
	</description>
	<!--METADATA-->
	<metadatalist>
		<metadata name="author">
			Cycling '74
		</metadata>
		<metadata name="tag">
			Jitter
		</metadata>
	</metadatalist>
	<!--INLETS-->
	<inletlist>
		<inlet id="0" type="INLET_TYPE">
			<digest>
				messages in
			</digest>
			<description>
				TEXT_HERE
			</description>
		</inlet>
		<inlet id="1" type="INLET_TYPE">
			<digest>
				messages in
			</digest>
			<description>
				TEXT_HERE
			</description>
		</inlet>
	</inletlist>
	<!--OUTLETS-->
	<outletlist>
		<outlet id="0" type="OUTLET_TYPE">
			<digest>
				messages to anim.node objects
			</digest>
			<description>
				TEXT_HERE
			</description>
		</outlet>
		<outlet id="1" type="OUTLET_TYPE">
			<digest>
				dumpout
			</digest>
			<description>
				TEXT_HERE
			</description>
		</outlet>
	</outletlist>
	<!--MESSAGES-->
	<methodlist>
		<method name="bang">
			<arglist />
			<digest>
				Output messages if animating
			</digest>
			<description>
				Causes the animation messages to be output, if currently animating.
			</description>
		</method>
		<method name="anim_reset">
			<arglist />
			<digest>
				Disable all animations
			</digest>
			<description>
				TEXT_HERE
			</description>
		</method>
		<method name="(mouse)">
			<digest>
				Mouse events
			</digest>
			<description>
				TEXT_HERE
			</description>
		</method>
		<method name="dictionary">
			<arglist>
				<arg name="name" optional="0" type="symbol" />
			</arglist>
			<digest>
				Dictionary input to set the ui mapping
			</digest>
			<description>
				The incoming dictionary is cloned and used to set the ui mapping.
			</description>
		</method>
		<method name="grow">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
			</arglist>
			<digest>
				Scale along axis
			</digest>
			<description>
				Scale the attached object along each axis by the amount provided. The axis arguments are multiplied by <at>speed</at>.
			</description>
		</method>
		<method name="move">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
			</arglist>
			<digest>
				Move along axis
			</digest>
			<description>
				Move the attached object along the axis provided, relative to the space indicated by the objects's <at>movemode</at> attribute. The axis arguments are multiplied by <at>speed</at>.
			</description>
		</method>
		<method name="moveto">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
				<arg name="duration" type="float" />
			</arglist>
			<digest>
				Move to a position over a specified time
			</digest>
			<description>
				Move the attached object to the specified position over the specified length of time (in seconds). Easing in and out is applied to the movement based on the <at>easefunc</at> attribute.
			</description>
		</method>
		<method name="scaleto">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
				<arg name="duration" type="float" />
			</arglist>
			<digest>
				Scale over a specified time
			</digest>
			<description>
				Scale the attached object to the specified scale value over the specified length of time (in seconds). Easing in and out is applied to the scaling based on the <at>easefunc</at> attribute.
			</description>
		</method>
		<method name="springto">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
			</arglist>
			<digest>
				Move to a position using mass-spring simulation
			</digest>
			<description>
				Move the attached object to the specified position using a mass-spring simulation.
			</description>
		</method>
		<method name="rotateto">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
				<arg name="w" type="float" />
				<arg name="duration" type="float" />
			</arglist>
			<digest>
				Rotate over a specified time
			</digest>
			<description>
				Rotate the attached object to the specified quaternion orientation over the specified length of time (in seconds). Easing in and out is applied to the rotation based on the <at>easefunc</at> attribute.
			</description>
		</method>
		<method name="ui_dict">
			<arglist />
			<digest>
				See the <m>dictionary</m> listing
			</digest>
			<description>
				TEXT_HERE
			</description>
		</method>
		<method name="ui_key">
			<arglist>
				<arg name="key" type="symbol" />
			</arglist>
			<digest>
				Send the specified key
			</digest>
			<description>
				Send the specified key. If the key is in the ui mapping dictionary, the corresponding animation will be enabled.
			</description>
		</method>
		<method name="ui_keyup">
			<arglist>
				<arg name="key" type="symbol" />
			</arglist>
			<digest>
				Send the specified keyup
			</digest>
			<description>
				Send the specified keyup. If the key is in the ui mapping dictionary, the corresponding animation will be disabled.
			</description>
		</method>
		<method name="ui_mouse">
			<arglist>
				<arg name="screen-x" type="int" />
				<arg name="screen-y" type="int" />
				<arg name="mouse-down" type="int" />
			</arglist>
			<digest>
				Send the mouse event
			</digest>
			<description>
				Send the mouse event. If the event is in the ui mapping dictionary, the corresponding animation will be enabled.
			</description>
		</method>
		<method name="update_drive">
			<arglist />
			<digest>
				See the <m>bang</m> listing
			</digest>
			<description>
				TEXT_HERE
			</description>
		</method>
		<method name="turn">
			<arglist>
				<arg name="x" type="float" />
				<arg name="y" type="float" />
				<arg name="z" type="float" />
			</arglist>
			<digest>
				Rotate along axis
			</digest>
			<description>
				Rotate the attached object along each axis by the amount provided, relative to the space indicated by the <at>turnmode</at> attribute. The axis arguments are multiplied by <at>speed</at>.
			</description>
		</method>
	</methodlist>
	<jittermethodlist>
		<jittermethod name="exportattrs" />
		<jittermethod name="exportsummary" />
		<jittermethod name="getattributes" />
		<jittermethod name="getstate" />
		<jittermethod name="importattrs" />
		<jittermethod name="summary" />
	</jittermethodlist>
	<!--ATTRIBUTES-->
	<attributelist>
		<attribute name="active" get="1" set="0" type="int" size="1">
			<digest>
				Currently animating
			</digest>
			<description>
				Indicates if the object is currently animating.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Active" />
			</attributelist>
		</attribute>
		<attribute name="automatic" get="1" set="1" type="int" size="1">
			<digest>
				Automatic updates
			</digest>
			<description>
				Enables automatic update messages (default = 1). Requires the <at>targetname</at> object to belong to a valid OpenGL context.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Automatic" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="drawto" get="1" set="1" type="symbol" size="1">
			<digest>
				Assign to named drawing context.
			</digest>
			<description>
				Assign to the named drawing context, allowing for updates to be received automatically.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Drawto" />
			</attributelist>
		</attribute>
		<attribute name="ease" get="1" set="1" type="float" size="1">
			<digest>
				Ease time
			</digest>
			<description>
				Set both <at>easein</at> and <at>easeout</at> attributes (default = 1.).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Ease" />
			</attributelist>
		</attribute>
		<attribute name="easefunc" get="1" set="1" type="symbol" size="1">
			<digest>
				Easing mode
			</digest>
			<description>
				Determines how the easing is applied (default = linear).
			</description>
			<attributelist>
				<attribute name="enumvals" get="1" set="1" type="atom" size="3">
					<enumlist>
						<enum name="linear">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="quadratic">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="cubic">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Easing Function" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enum" />
			</attributelist>
		</attribute>
		<attribute name="easein" get="1" set="1" type="float" size="1">
			<digest>
				Ease-in time
			</digest>
			<description>
				Determines how long it will take (in seconds) for a specific animation message to go from it's current value to the new value (default = 1.). This attribute only affects the <m>move</m>, <m>turn</m> and <m>grow</m> animations.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Ease In" />
			</attributelist>
		</attribute>
		<attribute name="easeout" get="1" set="1" type="float" size="1">
			<digest>
				Ease-out time
			</digest>
			<description>
				Determines how long it will take (in seconds) for a specific animation message to go from it's current value to 0 (default = 1.). This attribute only affects the <m>move</m>, <m>turn</m> and <m>grow</m> animations.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Ease Out" />
			</attributelist>
		</attribute>
		<attribute name="evalreport" get="1" set="1" type="int" size="1">
			<digest>
				Enable/disable evaluation parameter reporting
			</digest>
			<description>
				Enable/disable the evaluation parameter reporting out the dumpout (default = 0). The report is a 3 element list where each element represents the current evaluation parameters for the <m>moveto</m>, <m>rotateto</m>, and <m>scaleto</m> messages, in that order.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Eval Report" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="name" get="1" set="1" type="symbol" size="1">
			<digest>
				Instance name
			</digest>
			<description>
				Specifies the name of the instance (default = UID).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Name" />
			</attributelist>
		</attribute>
		<attribute name="position" get="1" set="1" type="float" size="3">
			<digest>
				Current position
			</digest>
			<description>
				The current stored position in 3D space. This attribute is used for the <m>moveto</m> and <m>springto</m> messages (default = 0 0 0).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Position" />
			</attributelist>
		</attribute>
		<attribute name="quat" get="1" set="1" type="float" size="4">
			<digest>
				Current orientation
			</digest>
			<description>
				The current orientation in 3D space, stored as a quaternion value. This attribute is used for the <m>rotateto</m> message (default = 0 0 0 1).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Quat" />
			</attributelist>
		</attribute>
		<attribute name="scale" get="1" set="1" type="float" size="3">
			<digest>
				Current scale
			</digest>
			<description>
				The current stored scale in 3D space. This attribute is used for the <m>scaleto</m> message (default = 1 1 1).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Scale" />
			</attributelist>
		</attribute>
		<attribute name="speed" get="1" set="1" type="float" size="1">
			<digest>
				Animation speed
			</digest>
			<description>
				The speed of animations in units per second. (default = 30.)
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Speed" />
			</attributelist>
		</attribute>
		<attribute name="spring_damp" get="1" set="1" type="float" size="1">
			<digest>
				Spring dampening
			</digest>
			<description>
				The dampening amount applied to the spring equation used in the <m>springto</m> message (default = 0.1).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Spring Damping" />
			</attributelist>
		</attribute>
		<attribute name="spring_mass" get="1" set="1" type="float" size="1">
			<digest>
				Spring mass
			</digest>
			<description>
				The mass amount applied to the spring equation used in the <m>springto</m> message (default = 1.).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Spring Mass" />
			</attributelist>
		</attribute>
		<attribute name="spring_stiff" get="1" set="1" type="float" size="1">
			<digest>
				Spring stiffness
			</digest>
			<description>
				The stiffness amount applied to the spring equation used in the <m>springto</m> message (default = 0.2).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Spring Stiffness" />
			</attributelist>
		</attribute>
		<attribute name="spring_thresh" get="1" set="1" type="float" size="1">
			<digest>
				Spring simulation threshold
			</digest>
			<description>
				The threshold value to determine when the spring simulation is no longer active. Used in the <m>springto</m> message (default = 0.0001).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Spring Threshold" />
			</attributelist>
		</attribute>
		<attribute name="targetname" get="1" set="1" type="symbol" size="1">
			<digest>
				Name of target object
			</digest>
			<description>
				The name of the target object that should be either an OpenGL object, or a <o>jit.anim.node</o> object.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Target Name" />
			</attributelist>
		</attribute>
		<attribute name="ui_listen" get="1" set="1" type="int" size="1">
			<digest>
				Enable UI message receiving
			</digest>
			<description>
				Cause UI mouse and keyboard messages to be received from context window (default = 0). Requires the <at>targetname</at> object to belong to a valid OpenGL context.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="UI Listen" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="ui_map" get="1" set="1" type="symbol" size="1">
			<digest>
				UI mapping dictionary name
			</digest>
			<description>
				Name associated with the ui mapping dictionary (default = UID). If an existing dictionary is registered to that name, this dictionary will reference the registered dictionary.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="UI Map" />
			</attributelist>
		</attribute>
		<attribute name="ui_map_clone" get="1" set="1" type="symbol" size="1">
			<digest>
				Dictionary to clone for UI map
			</digest>
			<description>
				The name of a registered dictionary to clone as the UI mapping dictionary.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="UI Map Clone" />
			</attributelist>
		</attribute>
		<attribute name="ui_priority" get="1" set="1" type="int" size="1">
			<digest>
				UI priority value
			</digest>
			<description>
				UI priority value (default = 900). When multiple UI objects are listening to the same window, ui_priority determines the order objects receive input. Lower values test first.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="UI Priority" />
			</attributelist>
		</attribute>
	</attributelist>
	<jitterattributelist />
	<!--EXAMPLE-->
	<examplelist>
		<example caption="Animate a 3D transform" img="jit.anim.drive.png" />
	</examplelist>
	<!--SEEALSO-->
	<seealsolist>
		<seealso name="jit.anim.node" />
		<seealso name="jit.anim.path" />
		<seealso name="jit.gl.camera" />
	</seealsolist>
	<discussion>
		UI mapping of key and mouse input is facilitated by editing the ui-map dictionary. Key input is mapped alpha-numeric keys and arrow keys (using up, down, left and right instead of the key symbol). Mouse mapping looks for the following dictionary entries:
		<br />
		Horizontal: mouse_horizontal, mouse_h, mouse_x
		<br />
		Horizontal with button down: mouse_down_horizontal, mouse_down_h, mouse_down_x
		<br />
		Vertical: mouse_vertical, mouse_v, mouse_y
		<br />
		Vertical with button down: mouse_down_vertical, mouse_down_v, mouse_down_y
		<br />
		UI input can be mapped to <m>move</m>, <m>turn</m> and <m>grow</m> messages.
	</discussion>
</c74object>
