control.h

hl2 source code. Do not use it illegal.

// Inheritance flags.
#define INHERIT_POS_X	(1<<0)
#define INHERIT_POS_Y	(1<<1)
#define INHERIT_POS_Z	(1<<2)
#define INHERIT_ROT_X	(1<<3)
#define INHERIT_ROT_Y	(1<<4)
#define INHERIT_ROT_Z	(1<<5)
#define INHERIT_SCL_X	(1<<6)
#define INHERIT_SCL_Y	(1<<7)
#define INHERIT_SCL_Z	(1<<8)
#define INHERIT_ALL		511

class Control : public ReferenceTarget {
	public:
		Control() {SetORT(ORT_CONSTANT,ORT_BEFORE);SetORT(ORT_CONSTANT,ORT_AFTER);};
		virtual ~Control() {};

		virtual void Copy(Control *from)=0;
		virtual void CommitValue(TimeValue t) {}
		virtual void RestoreValue(TimeValue t) {}
		virtual INode* GetTarget() { return NULL; } 
		virtual RefResult SetTarget(INode *targ) {return REF_SUCCEED;}

		// Implemented by transform controllers that have position controller
		// that can be edited in the trajectory branch
		virtual Control *GetPositionController() {return NULL;}
		virtual Control *GetRotationController() {return NULL;}
		virtual Control *GetScaleController() {return NULL;}
		virtual BOOL SetPositionController(Control *c) {return FALSE;}
		virtual BOOL SetRotationController(Control *c) {return FALSE;}
		virtual BOOL SetScaleController(Control *c) {return FALSE;}

		// If a controller has an 'X', 'Y', or 'Z' controller, it can implement
		// these methods so that its sub controllers can respect track view filters
		virtual Control *GetXController() {return NULL;}
		virtual Control *GetYController() {return NULL;}
		virtual Control *GetZController() {return NULL;}

		// Implemented by look at controllers that have a float valued roll
		// controller so that the roll can be edited via the transform type-in
		virtual Control *GetRollController() {return NULL;}
		virtual BOOL SetRollController(Control *c) {return FALSE;}

		// Implemented by any Point3 controller that wishes to indicate that it is intended
		// to control floating point RGB color values
		virtual BOOL IsColorController() {return FALSE;}

		// Implemented by TM controllers that support 
		// filtering out inheritance
		virtual DWORD GetInheritanceFlags() {return INHERIT_ALL;}
		virtual BOOL SetInheritanceFlags(DWORD f,BOOL keepPos) {return FALSE;} // return TRUE if TM controller supports inheritance

		virtual BOOL IsLeaf() {return TRUE;}
		virtual int IsKeyable() {return 1;}

		// If a controller does not want to allow another controller
		// to be assigned on top of it, it can return FALSE to this method.
		virtual BOOL IsReplaceable() {return TRUE;}		

		// This is called on TM, pos, rot, and scale controllers when their
		// input matrix is about to change. If they return FALSE, the node will
		// call SetValue() to make the necessary adjustments.
		virtual BOOL ChangeParents(TimeValue t,const Matrix3& oldP,const Matrix3& newP,const Matrix3& tm) {return FALSE;}

		// val points to an instance of a data type that corresponds with the controller
		// type. float for float controllers, etc.
		// Note that for SetValue on Rotation controllers, if the SetValue is
		// relative, val points to an AngAxis while if it is absolute it points
		// to a Quat.
		virtual void GetValue(TimeValue t, void *val, Interval &valid, GetSetMethod method=CTRL_ABSOLUTE)=0;	
		virtual	void SetValue(TimeValue t, void *val, int commit=1, GetSetMethod method=CTRL_ABSOLUTE)=0;

		// Transform controllers that do not inherit their parent's  transform 
		// should override this method. Returning FALSE will cause SetValue 
		// to be called even in the case when the parent is also being transformed.
		virtual BOOL InheritsParentTransform() { return TRUE; }

		virtual int GetORT(int type) {return (aflag>>(type==ORT_BEFORE?A_ORT_BEFORESHIFT:A_ORT_AFTERSHIFT))&A_ORT_MASK;}
		CoreExport virtual void SetORT(int ort,int type);
		
		// Sets the enabled/disabled state for ORTs
		CoreExport virtual void EnableORTs(BOOL enable);

		// Default implementations of load and save handle loading and saving of out of range type.
		// Call these from derived class load and save.
		// NOTE: Must call these before any of the derived class chunks are loaded or saved.
		CoreExport IOResult Save(ISave *isave);
		CoreExport IOResult Load(ILoad *iload);

		// For IK
		// Note: IK params must be given in the order they are applied to
		// the parent matrix. When derivatives are computed for a parameter
		// that parameter will apply itself to the parent matrix so the next
		// parameter has the appropriate reference frame. If a controller isn't
		// participating in IK then it should return FALSE and the client (usually PRS)
		// will apply the controller's value to the parent TM.
		virtual void EnumIKParams(IKEnumCallback &callback) {}
		virtual BOOL CompDeriv(TimeValue t,Matrix3& ptm,IKDeriv& derivs,DWORD flags) {return FALSE;}
		virtual float IncIKParam(TimeValue t,int index,float delta) {return 0.0f;}
		virtual void ClearIKParam(Interval iv,int index) {return;}
		virtual BOOL CanCopyIKParams(int which) {return FALSE;}
		virtual IKClipObject *CopyIKParams(int which) {return NULL;}
		virtual BOOL CanPasteIKParams(IKClipObject *co,int which) {return FALSE;}
		virtual void PasteIKParams(IKClipObject *co,int which) {}
		virtual void InitIKJoints(InitJointData *posData,InitJointData *rotData) {}
		virtual BOOL GetIKJoints(InitJointData *posData,InitJointData *rotData) {return FALSE;}
		virtual BOOL GetDOFParams(TimeValue t,Matrix3 &ptm,DOFParams &dofs,BOOL nodeSel) {return FALSE;}
		virtual BOOL CreateLockKey(TimeValue t, int which) {return FALSE;}
		virtual void MirrorIKConstraints(int axis,int which,BOOL pasteMirror=FALSE) {}
		virtual BOOL TerminateIK() {return FALSE;} // controllers can act as terminators.

		// Called on a transform controller when the a message is received from a pin node
		virtual RefResult PinNodeChanged(RefMessage message,Interval changeInt, PartID &partID) {return REF_SUCCEED;}

		// Called on a transform controller when one of the node level IK parameters has been changed
		virtual void NodeIKParamsChanged() {}

		// Called in a transform controller when a node invalidates its TM cache
		virtual void TMInvalidated() {}

		// Let's the TM controller determine if it's OK to bind (IK bind) to a particular node.
		virtual BOOL OKToBindToNode(INode *node) {return TRUE;}

		// Ease curves
		virtual BOOL CanApplyEaseMultCurves() {return TRUE;}
		CoreExport TimeValue ApplyEase(TimeValue t,Interval &valid);
		CoreExport void AppendEaseCurve(Control *cont);
		CoreExport void DeleteEaseCurve(int i);
		CoreExport int NumEaseCurves();

		// Multiplier curves		
		CoreExport float GetMultVal(TimeValue t,Interval &valid);
		CoreExport void AppendMultCurve(Control *cont);
		CoreExport void DeleteMultCurve(int i);
		CoreExport int NumMultCurves();

		// These are implemented to handle ease curves. If a controller
		// is a leaf controller, then it MUST NOT BY DEFINITION have any
		// sub controllers or references. If it is a leaf controller, then
		// these are implemented to handle the ease curve list.
		// If it is NOT a leaf controller, then these can be overridden.
		CoreExport int NumRefs();
		CoreExport RefTargetHandle GetReference(int i);
		CoreExport void SetReference(int i, RefTargetHandle rtarg);
		CoreExport int NumSubs();
		CoreExport Animatable* SubAnim(int i);
		CoreExport TSTR SubAnimName(int i);

		// Default implementations of some Animatable methods
		CoreExport void* GetInterface(ULONG id);
		CoreExport int PaintFCurves(			
			ParamDimensionBase *dim,
			HDC hdc,
			Rect& rcGraph,
			Rect& rcPaint,
			float tzoom,
			int tscroll,
			float vzoom,
			int vscroll,
			DWORD flags );
		CoreExport int GetFCurveExtents(
			ParamDimensionBase *dim,
			float &min, float &max, DWORD flags);


		// This is called on transform controller after a node is
		// cloned and the clone process has finished
		virtual void PostCloneNode() {}

		// Slave TM controllers can implement this to prevent plug-ins
		// deleting their node via the DeleteNode API.
		virtual BOOL PreventNodeDeletion() {return FALSE;}

		// New interface for visibility float controllers to allow view dependent visibility
		// The default implementation will call GetValue()
		CoreExport virtual float EvalVisibility(TimeValue t,View &view,Box3 pbox,Interval &valid);
		
		// Called on visibility controllers. Gives them the option to completely hide an object in the viewports
		virtual BOOL VisibleInViewports() {return TRUE;}

		// Called on transform controllers or visibility controllers when a node is cloned and the user has chosen to instance
		virtual BOOL CanInstanceController() {return TRUE;}

		// Should be called by any leaf controller's clone method so
		// that ease and multipier curves are cloned.
		CoreExport void CloneControl(Control *ctrl,RemapDir &remap);

		//-------------------------------------------------------
		// Controllers that wish to have an apparatus available in
		// the scene will implement these methods:
		// NOTE: Most of these methods are duplicated in BaseObject or Object
		// (see object.h for descriptions).
		virtual int Display(TimeValue t, INode* inode, ViewExp *vpt, int flags) { return 0; };
		virtual int HitTest(TimeValue t, INode* inode, int type, int crossing, int flags, IPoint2 *p, ViewExp *vpt) { return 0; }
		virtual	void GetWorldBoundBox(TimeValue t,INode* inode, ViewExp *vpt, Box3& box) {}

		virtual void ActivateSubobjSel(int level, XFormModes& modes ) {}

		virtual void SelectSubComponent(CtrlHitRecord *hitRec, BOOL selected, BOOL all, BOOL invert=FALSE) {}
		virtual void ClearSelection(int selLevel) {}
		virtual int SubObjectIndex(CtrlHitRecord *hitRec) {return 0;}		
		virtual void SelectAll(int selLevel) {}
		virtual void InvertSelection(int selLevel) {}

		virtual void GetSubObjectCenters(SubObjAxisCallback *cb,TimeValue t,INode *node) {}
		virtual void GetSubObjectTMs(SubObjAxisCallback *cb,TimeValue t,INode *node) {}

		// Modify sub object apparatuses
		virtual void SubMove( TimeValue t, Matrix3& partm, Matrix3& tmAxis, Point3& val, BOOL localOrigin=FALSE ){}
		virtual void SubRotate( TimeValue t, Matrix3& partm, Matrix3& tmAxis, Quat& val, BOOL localOrigin=FALSE ){}
		virtual void SubScale( TimeValue t, Matrix3& partm, Matrix3& tmAxis, Point3& val, BOOL localOrigin=FALSE ){}		
		
		// Schematic View Animatable Overides...
		CoreExport SvGraphNodeReference SvTraverseAnimGraph(IGraphObjectManager *gom, Animatable *object, int id, DWORD flags);

		// Called when the user rescales time in the time configuration dialog. If FALSE
		// is returned from this method then MapKeys() will be used to perform the scaling. 
		// Controllers can override this method to handle things like rescaling tagents that 
		// MapKeys() won't affect and return TRUE if they don't want map keys to be called.
		virtual BOOL RescaleTime(Interval oseg, Interval nseg) {return FALSE;}
	};


// Any controller that does not evaluate itself as a function of it's
// input can subclass off this class.
// GetValueLocalTime() will never ask the controller to apply the value,
// it will always ask for it absolute.
class StdControl : public Control {
	public:		
		virtual void GetValueLocalTime(TimeValue t, void *val, Interval &valid, GetSetMethod method=CTRL_ABSOLUTE)=0;
		virtual	void SetValueLocalTime(TimeValue t, void *val, int commit=1, GetSetMethod method=CTRL_ABSOLUTE)=0;
		CoreExport void GetValue(TimeValue t, void *val, Interval &valid, GetSetMethod method=CTRL_ABSOLUTE);
		CoreExport void SetValue(TimeValue t, void *val, int commit=1, GetSetMethod method=CTRL_ABSOLUTE);

		virtual void Extrapolate(Interval range,TimeValue t,void *val,Interval &valid,int type)=0;
		
		virtual void *CreateTempValue()=0;
		virtual void DeleteTempValue(void *val)=0;
		virtual void ApplyValue(void *val, void *delta)=0;
		virtual void MultiplyValue(void *val, float m)=0;
	};


// Each super class of controller may have a specific packet defined that
// the 'val' pointer will point to instead of a literal value.
// In reality, probably only the Transform controller will do this.
enum SetXFormCommand { XFORM_MOVE, XFORM_ROTATE, XFORM_SCALE, XFORM_SET };
class SetXFormPacket {
	public:
		SetXFormCommand command;
		Matrix3 tmParent;
		Matrix3 tmAxis;		// if command is XFORM_SET, this will contain the new value for the XFORM.		
		Point3 p;
		Quat q;
		AngAxis aa;
		BOOL localOrigin;		
		
		// XFORM_SET
		SetXFormPacket(const Matrix3& mat,const Matrix3& par=Matrix3(1))
			{command=XFORM_SET,tmParent=par,tmAxis=mat;}

		// XFORM_MOVE
		SetXFormPacket(Point3 pt, const Matrix3& par=Matrix3(1), 
						const Matrix3& a=Matrix3(1))
			{command=XFORM_MOVE;tmParent=par;tmAxis=a;p=pt;localOrigin=FALSE;}

		// XFORM_ROTATE
		SetXFormPacket(Quat qt, BOOL l, const Matrix3& par=Matrix3(1),
						const Matrix3& a=Matrix3(1))
			{command=XFORM_ROTATE;tmParent=par;tmAxis=a;q=qt;aa=AngAxis(q);localOrigin=l;}
		SetXFormPacket(AngAxis aA, BOOL l, const Matrix3& par=Matrix3(1),
						const Matrix3& a=Matrix3(1))
			{command=XFORM_ROTATE;tmParent=par;tmAxis=a;q=Quat(aA);aa=aA;localOrigin=l;}

		// XFORM_SCALE
		SetXFormPacket(Point3 pt, BOOL l, const Matrix3& par=Matrix3(1),
						const Matrix3& a=Matrix3(1))
			{command=XFORM_SCALE;tmParent=par;tmAxis=a;p=pt;localOrigin=l;}

		// Just in case you want to do it by hand...
		SetXFormPacket() {};
	};



// This is a special control base class for controllers that control
// morphing of geomoetry.
//
// The 'val' pointer used with GetValue will point to an object state.
// This would be the result of evaluating a combination of targets and
// producing a new object that is some combination of the targets.