ivp_template_constraint.hxx

hl2 source code. Do not use it illegal.

// Copyright (C) Ipion Software GmbH 1999-2000. All rights reserved.

// Do not misuse this code for bad purpose.

//IVP_EXPORT_PUBLIC

#ifndef _IVP_CONSTRAINT_TEMPLATE_INCLUDED
#define _IVP_CONSTRAINT_TEMPLATE_INCLUDED

#include "ivp_constraint_types.hxx"

class IVP_Real_Object;

/********************************************************************************
 *  Name:           IVP_Template_Constraint
 *  Description:    an interface structure for constraints
 *                  A constraint limits one (attached) object relative to another
 *		    (reference) object due to possible movement.
 *  Attention:      The "Attention:" sections of ivp_templates.hxx applies to this
 *		    template, too.
 *******************************************************************************/

class IVP_Template_Constraint {
public:
    friend class IVP_Environment;
public:
    /********************************************************************************
     *  Attention:      You may change the public variables in this class.
     *                  It is recommended to use the functions though.
     *  Note:           Like everywhere, the matrices have to be right-hand matrices.
     *******************************************************************************/

    IVP_CONSTRAINT_FLAGS flags; // not yet used

    /*******************************************************************************
     *  Name:           objectR   ("Reference object")
     *  Description:    The constraint's coordinate space definition is relative to
     *			the reference object's coordinate space.
     *                  When the objectR moves, the coordinate system of the 
     *			constraint moves accordingly.
     *  Default value:  NULL  (means: the reference space is world space)
     ******************************************************************************/
    IVP_Real_Object *objectR; // reference object
    void set_reference_object(IVP_Real_Object *objR);

    /*******************************************************************************
     *  Feature:        m_Ros_f_Rfs
     *  Description:    This matrix defines the translation axes of the constraint in reference object space
     *  Note:           If the rotation axes are not given, this matrix also defines the rotation axes.
     *                  The first column describes the x translation axis of the constraint.
     *  Note:           You can simply set the m_Ros_f_Rfs pointer to any applicable matrix.
     *  Note:           Or, you can use the buffer mm_Ros_f_Rfs and set: m_Ros_f_Rfs = &mm_Ros_f_Rfs;
     *  Default value:  NULL  (means: the constraint translation coordinate system is set to the reference object space)
     ******************************************************************************/
    IVP_U_Matrix  mm_Ros_f_Rfs;   // internal buffer
    IVP_U_Matrix  *m_Ros_f_Rfs;   // if NULL than Ros == Rfs
    
    void set_fixing_point_Ros    (const IVP_U_Point *anchor); // set anchor point, given in reference object space.
    void set_translation_axes_Ros(const IVP_U_Matrix3 *trans_axes);  // set direction of axle
    void set_translation_axes_as_object_space(); // this sets m_Ros_f_Rfs to NULL

    /******************************************************************************
     *  Feature:        m_Ros_f_Rrs
     *  Description:    This matrix defines the rotation axes of the constraint in reference object space.
     *  Note:           You can set the m_Ros_f_Rrs pointer to any applicable matrix.
     *  Note:           Or, you can use the buffer mm_Ros_f_Rfs and set: m_Ros_f_Rrs = &mm_Ros_f_Rrs;
     *  Default value:  NULL  (means: the rotation axes are equal to the translation axes)
     *  Note:           Setting m_Ros_f_Rrs to NULL results in faster constraints.
     *****************************************************************************/
    IVP_U_Matrix3 mm_Ros_f_Rrs;  // internal buffer
    IVP_U_Matrix3*m_Ros_f_Rrs;   // NULL means: Rrs == Rfs
    void set_rotation_axes_Ros(const IVP_U_Matrix3 *rot_axes);
    void set_rotation_axes_as_translation_axes(); // this sets m_Ros_f_Rrs to NULL

    /******************************************************************************
     *  Name:           objectA  ("Attached object")
     *  Description:    This is the object that is attached to the Reference object by the constraint.
     *                  When objectR and objectA move, the constraint axes move with objectR - not with objectA.
     *  Default value:  NULL  (means: an imaginary "world object"; its object coordinate system is world coordinate space)
     *	Note:		If the attached object is NULL (i.e. is the world space),
     *			moving the Reference object won't be possible.
     *****************************************************************************/
    IVP_Real_Object *objectA;
    void set_attached_object(IVP_Real_Object *objA);

    /******************************************************************************
     *  Feature:        m_Aos_f_Afs
     *  Description:    This matrix defines where the translation axes of the constraint should be in a relaxed constraint,
     *                  seen from the object system of the *Attached* object.
     *                  You will need this variable only if you are generating a constraint that is *not* relaxed.
     *                  The first time the constraint is simulated, it will give the objects a big push that moves them into a relaxed position.
     *  Note:           There is no need to set any "m_Aos_f_Ars" (rotation axes) since
     *                  the constraint calculates from m_Aos_f_Afs and m_Fos_f_Frs where the rotation axes should be.
     *  Default value:  NULL  (this means that the constraint is relaxed.)
     *****************************************************************************/
    IVP_U_Matrix  mm_Aos_f_Afs, *m_Aos_f_Afs;   // NULL means: Afs == Rfs
    void set_attached_fixing_point_Aos(const IVP_U_Point *trans_attached); // where the anchor should be on the attached object, seen in attached object system.
    void set_attached_translation_axes_Aos(const IVP_U_Matrix3 *rot_attached);
    void set_constraint_is_relaxed(); // this sets m_Aos_f_Afs to NULL (default)

    // --------------------------------------------------------
    // The function controlling the behaviour of the controller
    // if force_factor > damp_factor you get a springy behaviour
    // if force_factor < damp_factor ->smooth movement
    // --------------------------------------------------------
    IVP_FLOAT force_factor;	// force factor   [ 0.. 1.0 .. 1.5f ]     default: 1.0
    IVP_FLOAT damp_factor;	// damp:   [ 0 ...1.0f ..1.5f ]		default: 1.0


    /******************************************************************************
     *  Feature:        limited_axis_stiffness
     *  Description:    The same as relaxation_rate_per_dtime, but defined for all limited axis only
     *  Note		Small values should be used for limited constraints to remove
     *                  the effect of jumping constraints
     *****************************************************************************/
    IVP_FLOAT limited_axis_stiffness;
    
    /******************************************************************************
     *  Feature:        axis_type[6]
     *  Description:    You can define here what type of constraint you want to have.
     *                  axis_type[0] is the X translation axis.
     *                  axis_type[1] is the Y translation axis.
     *                  axis_type[2] is the Z translation axis.
     *                  axis_type[3] is the X rotation axis.
     *                  axis_type[4] is the Y rotation axis.
     *                  axis_type[5] is the Z rotation axis.
     *                  You can set any of these to any of the following values:
     *                  IVP_CONSTRAINT_FIXED   --  the objects must not move in this direction.
     *                  IVP_CONSTRAINT_FREE    --  the objects should be able to move freely in this direction.
     *                  IVP_CONSTRAINT_LIMITED --  the objects are allowed to move freely only within a given limitation.
     *                                             Set borderleft_Rfs and borderright_Rfs accordingly to these borders.
     *  Note:           If you set borders, always set them so that the left border value is smaller than the right border value.
     *  Note:           To determine what is "left" and "right" in terms of rotation, look into the direction of the axis.
     *                  Clockwise is right, anti-clockwise is left.
     *  Note:           Try to set up constraints in a way that borderleft < 0 < borderright and that
     *                  borderright has about the same value as -borderleft. You will get more accurate constraints.
     *  Default value:  {IVP_CONSTRAINT_FIXED, IVP_CONSTRAINT_FIXED, IVP_CONSTRAINT_FIXED,
     *                   IVP_CONSTRAINT_FREE,  IVP_CONSTRAINT_FREE,  IVP_CONSTRAINT_FREE}
     *                  (this is a ball-and-socket constraint)
     *****************************************************************************/
    IVP_CONSTRAINT_AXIS_TYPE axis_type[6];  // [author's note: think about a bitfield]
    IVP_FLOAT borderleft_Rfs[6], borderright_Rfs[6];
    //IVP_U_Point center_trans_Ros, center_rot_Ros;
    void fix_translation_axis(IVP_COORDINATE_INDEX which);  // make the constraint unmoveable in a specific direction
    void free_translation_axis(IVP_COORDINATE_INDEX which); // make the constraint moveable in a specific direction
    void limit_translation_axis(IVP_COORDINATE_INDEX which, IVP_FLOAT border_left, IVP_FLOAT border_right);  // Note: limitations are not yet fully tested.
    void fix_rotation_axis(IVP_COORDINATE_INDEX which);  // tell which rotation axis cannot be rotated around.
    void free_rotation_axis(IVP_COORDINATE_INDEX which); // tell which roation axis can be freely rotated around.
    void limit_rotation_axis(IVP_COORDINATE_INDEX which, IVP_FLOAT border_left, IVP_FLOAT border_right);  // Note: limitations are not yet fully tested.

    /******************************************************************************
     *  Feature:        maximpulse_type[6]
     *  Description:    You can set how strong the constraints are.
     *                  The maximpulse parameter(s) describe the maximum impulse that the constraint should endure,
     *                  described in N*s (Newton second, a metric impulse unit).
     *                  The maximpulse_type values have the following meanings:
     *                  IVP_CFE_NONE   --  the constraint has infinite force, no matter what maximpulse says.
     *                  IVP_CFE_CLIP   --  clip the constraint force to be maximal the given impulse (makes waygiving constraints). (not yet implemented)
     *                  IVP_CFE_BREAK  --  the constraint breaks (deletes itself) when the constraints' burden exceeds the given maximpulse.
     *                  IVP_CFE_BEND   --  not yet implemented.
     *  Attention:      Currently, you HAVE TO set all six maximpulse values to the *same* value
     *                  and all six maximpulse_type types to the *same* type since that concept is
     *                  implemented only partially yet.
     *  Attention:      the IVP_CFE_CLIP is still under construction, limiting rotation axes can be dangerous
     *  Note:           Currently, the maximpulse value is effectively internally very random
     *                  between (0.5 * maximpulse) and (1.0 * maximpulse), the latter being more probable.
     *  Default value:  {IVP_CFE_NONE, IVP_CFE_NONE, IVP_CFE_NONE, IVP_CFE_NONE, IVP_CFE_NONE, IVP_CFE_NONE},
     *                  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0}
     *****************************************************************************/
    IVP_CONSTRAINT_FORCE_EXCEED maximpulse_type[6];
    IVP_FLOAT maximpulse[6];
    void set_max_translation_impulse(IVP_CONSTRAINT_FORCE_EXCEED impulsetype, IVP_FLOAT impulse);
    void set_max_translation_impulse(IVP_COORDINATE_INDEX coord, IVP_CONSTRAINT_FORCE_EXCEED impulsetype, IVP_FLOAT impulse);    // not yet implemented:
    void set_max_rotation_impulse(IVP_CONSTRAINT_FORCE_EXCEED impulsetype, IVP_FLOAT impulse);
    void set_max_rotation_impulse(IVP_COORDINATE_INDEX coord, IVP_CONSTRAINT_FORCE_EXCEED impulsetype, IVP_FLOAT impulse);   // not yet implemented:

private: // internal functions
    void sort_coordinates(const IVP_Template_Constraint &tmpl);
public:
    /******************************************************************************
     *  Feature:        All-in-one constraint setting functions
     *  Description:    You may use one of the following functions if you prefer one single big
     *                  function call instead of many small function calls.
     *                  Each of the following functions set the constraint completely.
     *                  These functions do not provide the complete functionality,
     *                  however you can easily combine them with the above functions.
     *  Note:           Some of these functions provide some alternative ways of thinking of constraints.
     *  Attention:      All previous settings of Template_Constraint will be overwritten by each one of the following functions.
     *****************************************************************************/

    /******************************************************************************
     * Names of some special constraints:
     * ----------------------------------
     *
     * the first digit is nr of fixed translation dimensions, the second digit is nr of fixed rotation dimensions
     * english and german descriptions
     *                         _  _  _  _  _  _
     * 00 free, no limitation                   keine Verbindung
     * 01
     * 02
     * 03 always heading the same orientation _ Raumverschiebung
     * 10 rolling on a plane                    auf einer Ebene bewegbar
     * 11 a cardanjoint moving on a plane