// ===========================================================================
// Copyright 2018 Autodesk, Inc. All rights reserved.
//
// Use of this software is subject to the terms of the Autodesk license
// agreement provided at the time of installation or download, or which
// otherwise accompanies this software in either electronic or hard copy form.
// ===========================================================================
//==========================================================
//
//	Rotate Pivot Animation Controls
//  -------------------------------
//
//	There are four MEL procedures provided for animating
//	the rotate pivot of an object in a way that prevents
//	the object from jumping suddenly each time the pivot 
//	moves.
//
//	The functions are:
//
//	1)	pivotKey(px,py,pz):	keys the rotate pivot to
//		position (px,py,pz) in local space at the 
//		current frame.
//
//	2)	pivotKeyCur(): keys the rotate pivot to its
//		current position in local space at the current
//		frame.
//
//	3)	pivotKeyUpdate(): runs through all pivot
//		keyframes and ensures that the object remains
//		stationary at the points where the pivot
//		moves.
//
//	The pivotKey() and pivotKeyCur() functions use 
//	stepped tangents, so the pivot point instantaneously
//	moves from one keyframed position to the next.  This
//	helps to avoid unpredictable behaviour that can result
//	from smoothly varying both the rotate and rotate pivot 
//	values at the same time.
//
//	The following is an example sequence of commands:
//
//	1) - create a poly cube and select it
//
//	2) - frame 1
//	   - run pivotKeyCur() to set a pivot key
//	   - keyframe object's rotation
//
//	3) - frame 20
//	   - rotate the object and key its rotation
//
//  4) - frame 21
//	   - run pivotKey( 0.5, 0.5, 0.5 ) to move the
//		 pivot to (0.5,0.5,0.5) in local space and
//		 set a key
//
//	5) - frame 40
//	   - rotate the object and key its rotation
//
//	The result will be:
//
//	- frames 1->20:  object rotates about its center
//	- frame 21:      pivot moves to object's corner
//	- frames 21->40: object rotates about corner
//
//  When you play the animation, the object will 
//  remain stationary at frame 21 when the pivot
//  changes.
//
//  If, however, you go and modify the object's
//	rotation at frame 20, you will find that 
//	a jump will occur when the pivot changes at frame
//	21.  To fix this, just run pivotKeyUpdate() with the
//	object selected.  This will run through all keyframes
//	and ensure that no jumps occur when the pivot changes.
//
//	The reason why pivotKeyUpdate() is necessary is that
//	in order to prevent the jumping when the pivot changes,
//	we are keying the rotatePivotTranslate attribute.  The
//	required value for that attribute is dependent on the
//	object's rotation at that point, so if the rotation 
//	changes, we need to update the rotatePivotTranslate
//	keys to avoid jumping.  This function automatically
//	updates those keys.
//
//==========================================================

global proc pivotKey( float $px, float $py, float $pz )
//
//	Description:
//		
//		For the first selected transform, sets a key
//		on the rotate pivot at position ($px,$py,$pz)
//		in local object coordinates for the current
//		frame.  Also keys the rotatePivotTranslate
//		compensation attribute at the same frame
//		to prevent the object from jumping.  If
//		the rotation value at this frame is changed
//		later on, run the pivotKeyUpdate() function
//		to update the rotatePivotTranslate attrs to
//		compensate for the new rotation.
//
{
	//	get the selected transform
	//
	string $sl[] = `ls -sl -transforms`;
	if( size($sl) == 0 )
	{
		error( (uiRes("m_pivotKey.kPivotKeyErr")) );
	}
	string $o = $sl[0];

	//	move its pivot to the specified position in 
	//	local space (this will automatically update
	//	the rotatePivotTranslate value to keep
	//	the object stationary).
	//
	move -ls $px $py $pz ($o + ".rotatePivot");

	//	ensure that the rotatePivot and rotatePivotTranslate
	//	attrs are keyable
	//
	setAttr -k 1 ($o + ".rotatePivotX");
	setAttr -k 1 ($o + ".rotatePivotY");
	setAttr -k 1 ($o + ".rotatePivotZ");
	setAttr -k 1 ($o + ".rotatePivotTranslateX");
	setAttr -k 1 ($o + ".rotatePivotTranslateY");
	setAttr -k 1 ($o + ".rotatePivotTranslateZ");

	//	keyframe the rotatePivot and rotatePivotTranslate
	//	values.
	//
	setKeyframe ($o + ".rotatePivotX");
	setKeyframe ($o + ".rotatePivotY");
	setKeyframe ($o + ".rotatePivotZ");
	setKeyframe ($o + ".rotatePivotTranslateX");
	setKeyframe ($o + ".rotatePivotTranslateY");
	setKeyframe ($o + ".rotatePivotTranslateZ");

	//	ensure that we are using stepped tangents for
	//	the rotatePivot and rotatePivotTranslate attrs,
	//	so that they only change at the keyed times.
	//
	keyTangent -e -ott step -attribute rotatePivotX $o;
	keyTangent -e -ott step -attribute rotatePivotY $o;
	keyTangent -e -ott step -attribute rotatePivotZ $o;
	keyTangent -e -ott step -attribute rotatePivotTranslateX $o;
	keyTangent -e -ott step -attribute rotatePivotTranslateY $o;
	keyTangent -e -ott step -attribute rotatePivotTranslateZ $o;
}