<?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.phys.picker" module="jit" category="Jitter Physics">
	<digest>
		Constraint picking in a physics world
	</digest>
	<description>
		The <o>jit.phys.picker</o> object responds to mouse clicks and drags in the destination by creating a constraint on <o>jit.phys.body</o> objects intersecting with the mouse. Multi-touch picking is facilitated by the <m>touch</m> message.
	</description>
	<!--METADATA-->
	<metadatalist>
		<metadata name="author">
			Cycling '74
		</metadata>
		<metadata name="tag">
			TEXT_HERE
		</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>
			</digest>
			<description>
				TEXT_HERE
			</description>
		</inlet>
	</inletlist>
	<!--OUTLETS-->
	<outletlist>
		<outlet id="0" type="OUTLET_TYPE">
			<digest>
				mouse picker messages
			</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="touch">
			<arglist>
				<arg name="index" type="long" />
				<arg name="down" type="long" />
				<arg name="screen-x" type="long" />
				<arg name="screen-y" type="long" />
			</arglist>
			<digest>
				Create or update a multi-touch picking point.
			</digest>
			<description>
				Update the multi-touch point at <ar>index</ar> (or create if doesn't exist). The constraint is enabled if <ar>down</ar> is 1, and the position is set from <ar>screen-x</ar> and <ar>screen-y</ar>.
			</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="body" get="1" set="0" type="symbol" size="1">
			<digest>
				Intersecting body
			</digest>
			<description>
				The name of the <o>jit.phys.body</o> currently intersecting with the mouse.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Body" />
			</attributelist>
		</attribute>
		<attribute name="dynamics" get="1" set="1" type="int" size="1">
			<digest>
				Dynamics enable flag
			</digest>
			<description>
				Enable/disable dynamic constraint picking intersecting bodies (default = 1).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Dynamics" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="enable" get="1" set="1" type="int" size="1">
			<digest>
				Enable picker in simulation
			</digest>
			<description>
				Enable the picker contraint and ray-testing in the physics simulation (default = 1).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Enable" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="filterclass" get="1" set="1" type="symbol" size="1">
			<digest>
				Name of this object's collision filter-class.
			</digest>
			<description>
				Set the name of this object's collision filter-class (default = default). Other objects most specify the <ar>filterclass</ar> name in their <ar>filters</ar> list to enable collisions with this object. Maximum allowed unique names is 10.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Filter Class" />
			</attributelist>
		</attribute>
		<attribute name="filters" get="1" set="1" type="symbol" size="10">
			<digest>
				List of filterclass names this object collides with
			</digest>
			<description>
				Specify a list of <at>filterclass</at> names to enable collisions with (default = all). Possible values include <ar>all</ar> and <ar>default</ar>. Additional values include any user-specified <at>filterclass</at> names (maximum allowed = 10).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Filters" />
			</attributelist>
		</attribute>
		<attribute name="hover" get="1" set="1" type="int" size="1">
			<digest>
				Hover enable flag
			</digest>
			<description>
				Enable/disable mouse hovering allowing for picking without the mouse button down (default = 0).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Hover" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="local_position" get="1" set="0" type="float" size="3">
			<digest>
				The local constraint position
			</digest>
			<description>
				The local-space constraint position on the picked body (default = 0 0 0).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Local Position" />
			</attributelist>
		</attribute>
		<attribute name="output_positions" get="1" set="1" type="int" size="1">
			<digest>
				Enable output of position values
			</digest>
			<description>
				Enable/disable the output of local and world position values when an object is selected(default = 0). When enabled the local position on the clicked object, and the world-space position of the constraint are output following the object name and mouse-state.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Output Positions" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="pickmode" get="1" set="1" type="symbol" size="1">
			<digest>
				Constraint picking mode
			</digest>
			<description>
				Determines how the constraint is applied to the intersecting body (default = surface).
			</description>
			<attributelist>
				<attribute name="enumvals" get="1" set="1" type="atom" size="2">
					<enumlist>
						<enum name="center">
							<digest>
								The constraint is applied to the bodies center of mass
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="surface">
							<digest>
								The constraint is applied to the intersecting surface point
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Pick Mode" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enum" />
			</attributelist>
		</attribute>
		<attribute name="position" get="1" set="0" type="float" size="3">
			<digest>
				The constraint position
			</digest>
			<description>
				The current constraint picking position (default = 0 0 0).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Position" />
			</attributelist>
		</attribute>
		<attribute name="strength" get="1" set="1" type="float" size="1">
			<digest>
				Constraint strength value
			</digest>
			<description>
				Set the constraint strength (default = 0.2). Determines what proportion of the joint error will be fixed each simulation step. Values between 0.1 and 0.8 are recommended.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Strength" />
			</attributelist>
		</attribute>
		<attribute name="stretch" get="1" set="1" type="float" size="1">
			<digest>
				Constraint stretch value
			</digest>
			<description>
				Set the constraint stretch (default = 0.0). Setting to a positive value allows forces acting on rigid bodies to violate the constraint by an amount proportional to the stretch value.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Stretch" />
			</attributelist>
		</attribute>
		<attribute name="ui_priority" get="1" set="1" type="int" size="1">
			<digest>
				UI priority value
			</digest>
			<description>
				UI priority value (default = -800). 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>
		<attribute name="worldname" get="1" set="1" type="symbol" size="1">
			<digest>
				Name of the context the constraint picker is bound to
			</digest>
			<description>
				The name of a <o>jit.phys.world</o> context this constraint picker is bound to.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="World Name" />
			</attributelist>
		</attribute>
	</attributelist>
	<jitterattributelist />
	<!--EXAMPLE-->
	<examplelist>
		<example caption="Constraint picking in a physics world" img="jit.phys.picker.png" />
	</examplelist>
	<!--SEEALSO-->
	<seealsolist>
		<seealso name="jit.phys.world" />
		<seealso name="jit.phys.body" />
		<seealso name="jit.gl.picker" />
	</seealsolist>
	<discussion>
		When an intersection occurs, the <o>jit.phys.body</o> name and current mouse-state is sent out the leftmost outlet. If <at>dynamics</at> is enabled, a point-to-point constraint is created on the picked body that persists until the mouse button is released. When dragging a rigid-body with dynamics enabled, holding down the option key will move the object towards and away from the camera. If the option key is held and the mouse is released, the constraint will persist, allowing the mouse to be repositioned on the rigid-body.
	</discussion>
</c74object>
