An interface class for Frame constraints. More...

#include <easy3d/renderer/constraint.h>

Inheritance diagram for Constraint:

Public Member Functions
virtual	~Constraint ()=default

virtual void	constrainTranslation (vec3 &translation, Frame *const frame)

virtual void	constrainRotation (quat &rotation, Frame *const frame)

Detailed Description

An interface class for Frame constraints.

This class defines the interface for the Constraints that can be applied to a Frame to limit its motion. Use Frame::setConstraint() to associate a Constraint to a Frame (default is a NULL Frame::constraint()).

How does it work ?

The Constraint acts as a filter on the translation and rotation Frame increments. constrainTranslation() and constrainRotation() should be overloaded to specify the constraint behavior: the desired displacement is given as a parameter that can optionally be modified.

Here is how the Frame::translate() and Frame::rotate() methods use the Constraint:

 Frame::translate(vec3& T)
{
    if (constraint())
      constraint()->constrainTranslation(T, this);
    t += T;
}
 
Frame::rotate(quat& Q)
{
    if (constraint())
      constraint()->constrainRotation(Q, this);
    q *= Q;
}

The default behavior of constrainTranslation() and constrainRotation() is empty (meaning no filtering).

The Frame which uses the Constraint is passed as a parameter to the constrainTranslation() and constrainRotation() methods, so that they can have access to its current state (mainly Frame::position() and Frame::orientation()). It is not const for versatility reasons, but directly modifying it should be avoided.

Attention: Frame::setTranslation(), Frame::setRotation() and similar methods will actually indeed set the frame position and orientation, without taking the constraint into account. Use the WithConstraint versions of these methods to enforce the Constraint.

Implemented Constraints

Classical axial and plane Constraints are provided for convenience: see the LocalConstraint, WorldConstraint and CameraConstraint classes' documentations.

Try the constrainedFrame and constrainedCamera examples for an illustration.

Creating new Constraints

The implementation of a new Constraint class simply consists in overloading the filtering methods:

// This Constraint enforces that the Frame cannot have a negative z world
coordinate. class myConstraint : public Constraint
{
public:
    virtual void constrainTranslation(vec3& t, Frame * const fr)
      {
            // Express t in the world coordinate system.
            const vec3 tWorld = fr->inverseTransformOf(t);
    if (fr->position().z + tWorld.z < 0.0) // check the new fr z coordinate
      t.z = fr->transformOf(-fr->position().z); // t.z is clamped so that
next z position is 0.0
      }
};

Note that the translation (resp. rotation) parameter passed to constrainTranslation() (resp. constrainRotation()) is expressed in the local Frame coordinate system. Here, we use the Frame::transformOf() and Frame::inverseTransformOf() method to convert it to and from the world coordinate system.

Combined constraints can easily be achieved by creating a new class that applies the different constraint filters:

myConstraint::constrainTranslation(vec3& v, Frame* const fr)
{
    constraint1->constrainTranslation(v, fr);
    constraint2->constrainTranslation(v, fr);
    // and so on, with possible branches, tests, loops...
}

Constructor & Destructor Documentation

◆ ~Constraint()

virtual ~Constraint ( )

virtualdefault

Virtual destructor. Empty.

Member Function Documentation

◆ constrainRotation()

virtual void constrainRotation	(	quat &	rotation,
		Frame *const	frame )

inlinevirtual

Filters the rotation applied to the frame. This default implementation is empty (no filtering).

Overload this method in your own Constraint class to define a new rotation constraint. See constrainTranslation() for details.

Use Frame::inverseTransformOf() on the rotation quat::axis() to express rotation in the world coordinate system if needed.

Reimplemented in AxisPlaneConstraint, CameraConstraint, LocalConstraint, and WorldConstraint.

◆ constrainTranslation()

virtual void constrainTranslation	(	vec3 &	translation,
		Frame *const	frame )

inlinevirtual

Filters the translation applied to the frame. This default implementation is empty (no filtering).

Overload this method in your own Constraint class to define a new translation constraint. frame is the Frame to which is applied the translation. It is not defined const, but you should refrain from directly changing its value in the constraint. Use its Frame::position() and update the translation accordingly instead.

translation is expressed in local frame coordinate system. Use Frame::inverseTransformOf() to express it in the world coordinate system if needed.