# AxisPlaneConstraint Class Reference

An abstract class for Frame Constraints defined by an axis or a plane. More...

List of all members.

## Public Types
enum | Type { FREE, AXIS, PLANE, FORBIDDEN }
## Public Member Functions
| AxisPlaneConstraint ()
virtual | ~AxisPlaneConstraint ()
## Translation constraint
virtual void | constrainTranslation (Vec &translation, Frame *const frame)
void | setTranslationConstraint (Type type, const Vec &direction)
void | setTranslationConstraintType (Type type)
void | setTranslationConstraintDirection (const Vec &direction)
Type | translationConstraintType () const
Vec | translationConstraintDirection () const
## Rotation constraint
virtual void | constrainRotation (Quaternion &rotation, Frame *const frame)
void | setRotationConstraint (Type type, const Vec &direction)
void | setRotationConstraintType (Type type)
void | setRotationConstraintDirection (const Vec &direction)
Type | rotationConstraintType () const
Vec | rotationConstraintDirection () const

## Detailed Description

An abstract class for Frame Constraints defined by an axis or a plane.

AxisPlaneConstraint is an interface for (translation and/or rotation) Constraint that are defined by a direction. translationConstraintType() and rotationConstraintType() define how this direction should be interpreted: as an axis (AxisPlaneConstraint::AXIS) or as a plane normal (AxisPlaneConstraint::PLANE). See the Type() documentation for details.

The three implementations of this class: LocalConstraint, WorldConstraint and CameraConstraint differ by the coordinate system in which this direction is expressed.

Different implementations of this class are illustrated in the contrainedCamera and constrainedFrame examples.

Attention:
  When applied, the rotational Constraint may not intuitively follow the mouse displacement. A solution would be to directly measure the rotation angle in screen coordinates, but that would imply to know the QGLViewer::camera(), so that we can compute the projected coordinates of the rotation center (as is done with the SCREEN_ROTATE binding). However, adding an extra pointer to the QGLViewer::camera() in all the AxisPlaneConstraint derived classes (which the user would have to update in a multi-viewer application) was judged as an overkill.

## Member Enumeration Documentation

enum Type

Type lists the different types of translation and rotation constraints that are available.

It specifies the meaning of the constraint direction (see translationConstraintDirection() and rotationConstraintDirection()): as an axis direction (AxisPlaneConstraint::AXIS) or a plane normal (AxisPlaneConstraint::PLANE). AxisPlaneConstraint::FREE means no constraint while AxisPlaneConstraint::FORBIDDEN completely forbids the translation and/or the rotation.

See translationConstraintType() and rotationConstraintType().

Attention:
  The AxisPlaneConstraint::PLANE Type is not valid for rotational constraint.

New derived classes can use their own extended enum for specific constraints:

        class MyAxisPlaneConstraint : public AxisPlaneConstraint
        {
        public:
          enum MyType { FREE, AXIS, PLANE, FORBIDDEN, CUSTOM };
          virtual void constrainTranslation(Vec &translation, Frame *const frame)
          {
            // translationConstraintType() is simply an int. CUSTOM Type is handled seamlessly.
            switch (translationConstraintType())
            {
            case MyAxisPlaneConstraint::FREE: ... break;
            case MyAxisPlaneConstraint::CUSTOM: ... break;
            }
          };

          MyAxisPlaneConstraint* c = new MyAxisPlaneConstraint();
          // Note the Type conversion
          c->setTranslationConstraintType(AxisPlaneConstraint::Type(MyAxisPlaneConstraint::CUSTOM));
        };

Enumerator:

  FREE |
  AXIS |
  PLANE |
  FORBIDDEN |

## Constructor & Destructor Documentation

AxisPlaneConstraint | ( |  | ) |

Default constructor.

translationConstraintType() and rotationConstraintType() are set to AxisPlaneConstraint::FREE. translationConstraintDirection() and rotationConstraintDirection() are set to (0,0,0).

virtual ~AxisPlaneConstraint | ( |  | ) | `[virtual]`

Virtual destructor. Empty.

## Member Function Documentation

virtual void constrainRotation | ( | Quaternion & | rotation,
|  | Frame *const | frame |
| ) |  |  | `[virtual]`

Overloading of Constraint::constrainRotation(). Empty.

Reimplemented from Constraint.

Reimplemented in LocalConstraint, WorldConstraint, and CameraConstraint.

virtual void constrainTranslation | ( | Vec & | translation,
|  | Frame *const | frame |
| ) |  |  | `[virtual]`

Overloading of Constraint::constrainTranslation(). Empty

Reimplemented from Constraint.

Reimplemented in LocalConstraint, WorldConstraint, and CameraConstraint.

Vec rotationConstraintDirection | ( |  | ) | const

Returns the axis direction used by the rotation constraint.

This direction is defined only when rotationConstraintType() is AxisPlaneConstraint::AXIS.

The AxisPlaneConstraint derived classes express this direction in different coordinate system (camera for CameraConstraint, local for LocalConstraint, and world for WorldConstraint). This value can be modified with setRotationConstraintDirection().

Type rotationConstraintType | ( |  | ) | const

Returns the rotation constraint Type().

void setRotationConstraint | ( | Type | type,
|  | const Vec & | direction |
| ) |  |  |

Simply calls setRotationConstraintType() and setRotationConstraintDirection().

void setRotationConstraintDirection | ( | const Vec & | direction | ) |

Defines the rotationConstraintDirection(). The coordinate system where `direction` is expressed depends on your class implementation.

void setRotationConstraintType | ( | Type | type | ) |

Set the Type() of the rotationConstraintType(). Default is AxisPlaneConstraint::FREE.

Depending on this value, the Frame will freely rotate (AxisPlaneConstraint::FREE), will only be able to rotate around an axis (AxisPlaneConstraint::AXIS), or will not able to rotate at all (AxisPlaneConstraint::FORBIDDEN).

Use Frame::setOrientation() to define the orientation of the constrained Frame before it gets constrained.

Attention:
  An AxisPlaneConstraint::PLANE Type() is not meaningful for rotational constraints and will be ignored.

void setTranslationConstraint | ( | Type | type,
|  | const Vec & | direction |
| ) |  |  |

Simply calls setTranslationConstraintType() and setTranslationConstraintDirection().

void setTranslationConstraintDirection | ( | const Vec & | direction | ) |

Defines the translationConstraintDirection(). The coordinate system where `direction` is expressed depends on your class implementation.

void setTranslationConstraintType | ( | Type | type | ) |

Sets the Type() of the translationConstraintType(). Default is AxisPlaneConstraint::FREE.

Vec translationConstraintDirection | ( |  | ) | const

Returns the direction used by the translation constraint.

It represents the axis direction (AxisPlaneConstraint::AXIS) or the plane normal (AxisPlaneConstraint::PLANE) depending on the translationConstraintType(). It is undefined for AxisPlaneConstraint::FREE or AxisPlaneConstraint::FORBIDDEN.

The AxisPlaneConstraint derived classes express this direction in different coordinate system (camera for CameraConstraint, local for LocalConstraint, and world for WorldConstraint). This value can be modified with setTranslationConstraintDirection().

Type translationConstraintType | ( |  | ) | const

Returns the translation constraint Type().

Depending on this value, the Frame will freely translate (AxisPlaneConstraint::FREE), will only be able to translate along an axis direction (AxisPlaneConstraint::AXIS), will be forced to stay into a plane (AxisPlaneConstraint::PLANE) or will not able to translate at all (AxisPlaneConstraint::FORBIDDEN).

Use Frame::setPosition() to define the position of the constrained Frame before it gets constrained.