rlm@83: 
rlm@83: 
rlm@83: 
rlm@83: 
rlm@83: (ConeJoint
rlm@83: 	RigidBody A
rlm@83: 	RigidBody B
rlm@83: 	Vector3f PivotA
rlm@83: 	Vector3f PivotB
rlm@83: 	Matrix3f RotA
rlm@83: 	Matrix3f RotB
rlm@83: )
rlm@83: 
rlm@83: Parameters:
rlm@83: 
rlm@83: The specification of a cone joint depends on local coordinates,
rlm@83: that is coordinates relative to the given rigid bodies.
rlm@83: 
rlm@83: ***
rlm@83: DIGRESSION ABOUT LOCAL COORDINATES
rlm@83: 
rlm@83: Each rigid body has its own coordinate system.
rlm@83: If an object is placed, unrotated, at the origin of the world,
rlm@83: then its coordinate system is the same as the world's coordinate
rlm@83: system. In other words, the origin of the object coincides with the
rlm@83: origin of the world, and the XYZ axes of the object coincide with the
rlm@83: XYZ axes of the world.
rlm@83: 
rlm@83: When you translate the object, its "origin" goes with it.
rlm@83: The origin of the object is always the center of the object.
rlm@83: 
rlm@83: When you rotate the object, its axes go with it.
rlm@83: For example, if you rotate the object pi/2 radians righthandedly
rlm@83: about the Z axis, its own X axis will move to coincide with the
rlm@83: world's Y axis; its own Y axis will move to coincide with the
rlm@83: world's -X axis; its Z axis will remain aligned with the world's
rlm@83: Z-axis.
rlm@83: 
rlm@83: 
rlm@83: In such a way, you can see the way in which the translations and rotations of an
rlm@83: object alter its local coordinates.
rlm@83: 
rlm@83: 
rlm@83: ## a haphazard elaboration of the above
rlm@83: 
rlm@83: Converting from world coordinates to local coordinates amounts to
rlm@83: finding the transformation that undoes all the rotations and
rlm@83: translations that the Object has suffered, then applying that
rlm@83: undoing-transformation to the world coordinates.
rlm@83: 
rlm@83:             +position of obj   +rot of obj
rlm@83: world axes  ---------------> x -----------> obj axes
rlm@83: 
rlm@83: 
rlm@83: 1. Start with the world coordinates of the Object and a test-object.
rlm@83: 2. Subtract the world coordinates of the Object from each. Now the
rlm@83: Object is at the origin (though still has its rotation, if any) and
rlm@83: the test-object is somewhere else (irrelevant).
rlm@83: 3. Rotate the whole world about the origin so that the Object becomes
rlm@83: unrotated. Now the object is unrotated at the origin, and the
rlm@83: test-object is somewhere else.
rlm@83: 4. That somewhere-else is the coordinates of the test-object as seen
rlm@83: from the Object's own coordinate system (the system in which the Object is always
rlm@83: unrotated and centered at the origin)
rlm@83: 
rlm@83: cf: get-subjective-rotation
rlm@83: cf: get-subjective-position
rlm@83: 
rlm@83: ***
rlm@83: 
rlm@83: 
rlm@83: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
rlm@83: 
rlm@83: Now, to understand the ConeJoint constructor: 
rlm@83: Suppose you have the position of the cone joint picked out, as well as its
rlm@83: orientation (orientation aka rotation matters because the limits of
rlm@83: rotation are taken with respect to the xy and xz plane of the _joint's_
rlm@83: coordinate system. This is what the documentation means by "by
rlm@83: default, the x-axis").
rlm@83: 
rlm@83: Then: 
rlm@83: Pivot-a is the position of the joint, as expressed in the coordinate
rlm@83: system of object-a.
rlm@83: Pivot-a is the position of the joint again, this time as expressed in
rlm@83: the coordinate system of object-b.
rlm@83: 
rlm@83: (Use get-subjective-position to calculate this conveniently)
rlm@83: 
rlm@83: 
rlm@83: Rot-a is the orientation of the joint, as expressed in the
rlm@83: coordinate system of object-a. By default, it is aligned with a's
rlm@83: coordinate system, making the cone's axis along a's x-axis, and its
rlm@83: limits of rotation in a's xy and xz planes.
rlm@83: 
rlm@83: Analogously for b.
rlm@83: 
rlm@83: If inconsistent pivot locations are given, it's possible to recover by
rlm@83: moving the objects. I think the engine prefers to keep object b still
rlm@83: and move everything else, but it may not always be so.
rlm@83: 
rlm@83: If inconsistent rotations are given ... I don't know what
rlm@83: happens. Beez happens.
rlm@83: 
rlm@83: 
rlm@83: Modulo a bunch of forced object migration because your pivots give
rlm@83: inconsistent indicators of where the joint should be expected, etc., this is
rlm@83: how the method works.
rlm@83: 
rlm@83: 
rlm@83: 
rlm@83: # Another implementation option would have been to specify the positions and
rlm@83: # rotations of THREE things --- object A, object B, and the joint --- all in terms of world
rlm@83: # coordinates. This wouldn't be any more or less fragile (i.e. subject to explosions
rlm@83: # of inconsistency) but it might be nice to avoid those
rlm@83: # transformations into local coordinates, even if we had to introduce
rlm@83: # more parameters into such a new method
rlm@83: # (specifically, the position and orientation of the joint would be new).
rlm@83: 
rlm@83: # I wouldn't mind because after all, don't we already  need to keep in mind the position and orientation of the
rlm@83: # joint in the existing method? Lest it explode in inconsistency? I
rlm@83: # suggest we create a clojure method that creates cone joints in the
rlm@83: # transformation-free way.
rlm@83: # cf. joint-create, my first attempt
rlm@83: 
rlm@83: 
rlm@83: 
rlm@83: