frame.h

/****************************************************************************

 Copyright (C) 2002-2013 Gilles Debunne. All rights reserved.

 This file is part of the QGLViewer library version 2.5.2.

 http://www.libqglviewer.com - contact@libqglviewer.com

 This file may be used under the terms of the GNU General Public License 
 versions 2.0 or 3.0 as published by the Free Software Foundation and
 appearing in the LICENSE file included in the packaging of this file.
 In addition, as a special exception, Gilles Debunne gives you certain 
 additional rights, described in the file GPL_EXCEPTION in this package.

 libQGLViewer uses dual licensing. Commercial/proprietary software must
 purchase a libQGLViewer Commercial License.

 This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

*****************************************************************************/

#ifndef QGLVIEWER_FRAME_H
#define QGLVIEWER_FRAME_H

#include <QObject>
#include <QString>

#include "constraint.h"
// #include "GL/gl.h" is now included in config.h for ease of configuration

namespace qglviewer {
class QGLVIEWER_EXPORT Frame : public QObject
{
    Q_OBJECT

public:
    Frame();

    virtual ~Frame() {}

    Frame(const Frame& frame);
    Frame& operator=(const Frame& frame);

Q_SIGNALS:
    void modified();

    void interpolated();

public:
    Frame(const Vec& position, const Quaternion& orientation);

    void setPosition(const Vec& position);
    void setPosition(float x, float y, float z);
    void setPositionWithConstraint(Vec& position);

    void setOrientation(const Quaternion& orientation);
    void setOrientation(double q0, double q1, double q2, double q3);
    void setOrientationWithConstraint(Quaternion& orientation);

    void setPositionAndOrientation(const Vec& position, const Quaternion& orientation);
    void setPositionAndOrientationWithConstraint(Vec& position, Quaternion& orientation);

    Vec position() const;
    Quaternion orientation() const;

    void getPosition(float& x, float& y, float& z) const;
    void getOrientation(double& q0, double& q1, double& q2, double& q3) const;


public:
    void setTranslation(const Vec& translation) { t_ = translation; Q_EMIT modified(); }
    void setTranslation(float x, float y, float z);
    void setTranslationWithConstraint(Vec& translation);

    void setRotation(const Quaternion& rotation) { q_ = rotation; Q_EMIT modified(); }
    void setRotation(double q0, double q1, double q2, double q3);
    void setRotationWithConstraint(Quaternion& rotation);

    void setTranslationAndRotation(const Vec& translation, const Quaternion& rotation);
    void setTranslationAndRotationWithConstraint(Vec& translation, Quaternion& rotation);

    Vec translation() const { return t_; }
    Quaternion rotation() const { return q_; }

    void getTranslation(float& x, float& y, float& z) const;
    void getRotation(double& q0, double& q1, double& q2, double& q3) const;

public:
    const Frame* referenceFrame() const { return referenceFrame_; }
    void setReferenceFrame(const Frame* const refFrame);
    bool settingAsReferenceFrameWillCreateALoop(const Frame* const frame);


    void translate(Vec& t);
    void translate(const Vec& t);
    // Some compilers complain about "overloading cannot distinguish from previous declaration"
    // Simply comment out the following method and its associated implementation
    void translate(float x, float y, float z);
    void translate(float& x, float& y, float& z);

    void rotate(Quaternion& q);
    void rotate(const Quaternion& q);
    // Some compilers complain about "overloading cannot distinguish from previous declaration"
    // Simply comment out the following method and its associated implementation
    void rotate(double q0, double q1, double q2, double q3);
    void rotate(double& q0, double& q1, double& q2, double& q3);

    void rotateAroundPoint(Quaternion& rotation, const Vec& point);
    void rotateAroundPoint(const Quaternion& rotation, const Vec& point);

    void alignWithFrame(const Frame* const frame, bool move=false, float threshold=0.0f);
    void projectOnLine(const Vec& origin, const Vec& direction);


    Vec coordinatesOf(const Vec& src) const;
    Vec inverseCoordinatesOf(const Vec& src) const;
    Vec localCoordinatesOf(const Vec& src) const;
    Vec localInverseCoordinatesOf(const Vec& src) const;
    Vec coordinatesOfIn(const Vec& src, const Frame* const in) const;
    Vec coordinatesOfFrom(const Vec& src, const Frame* const from) const;

    void getCoordinatesOf(const float src[3], float res[3]) const;
    void getInverseCoordinatesOf(const float src[3], float res[3]) const;
    void getLocalCoordinatesOf(const float src[3], float res[3]) const;
    void getLocalInverseCoordinatesOf(const float src[3], float res[3]) const;
    void getCoordinatesOfIn(const float src[3], float res[3], const Frame* const in) const;
    void getCoordinatesOfFrom(const float src[3], float res[3], const Frame* const from) const;

    // A frame is as a new coordinate system, defined with respect to a reference frame (the world
    // coordinate system by default, see the "Composition of frame" section).

    // The transformOf() (resp. inverseTransformOf()) functions transform a 3D vector from (resp.
    // to) the world coordinates system. This section defines the 3D vector transformation
    // functions. See the Coordinate system transformation of 3D points above for the transformation
    // of 3D points. The difference between the two sets of functions is simple: for vectors, only
    // the rotational part of the transformations is taken into account, while translation is also
    // considered for 3D points.

    // The length of the resulting transformed vector is identical to the one of the source vector
    // for all the described functions.

    // When local is prepended to the names of the functions, the functions simply transform from
    // (and to) the reference frame.

    // When In (resp. From) is appended to the names, the functions transform from (resp. To) the
    // frame that is given as an argument. The frame does not need to be in the same branch or the
    // hierarchical tree, and can be \c NULL (the world coordinates system).

    // Combining any of these functions with its inverse (in any order) leads to the identity.
    Vec transformOf(const Vec& src) const;
    Vec inverseTransformOf(const Vec& src) const;
    Vec localTransformOf(const Vec& src) const;
    Vec localInverseTransformOf(const Vec& src) const;
    Vec transformOfIn(const Vec& src, const Frame* const in) const;
    Vec transformOfFrom(const Vec& src, const Frame* const from) const;

    void getTransformOf(const float src[3], float res[3]) const;
    void getInverseTransformOf(const float src[3], float res[3]) const;
    void getLocalTransformOf(const float src[3], float res[3]) const;
    void getLocalInverseTransformOf(const float src[3], float res[3]) const;
    void getTransformOfIn(const float src[3], float res[3], const Frame* const in) const;
    void getTransformOfFrom(const float src[3], float res[3], const Frame* const from) const;


    Constraint* constraint() const { return constraint_; }
    void setConstraint(Constraint* const constraint) { constraint_ = constraint; }

public:
    const GLdouble* matrix() const;
    void getMatrix(GLdouble m[4][4]) const;
    void getMatrix(GLdouble m[16]) const;

    const GLdouble* worldMatrix() const;
    void getWorldMatrix(GLdouble m[4][4]) const;
    void getWorldMatrix(GLdouble m[16]) const;

    void setFromMatrix(const GLdouble m[4][4]);
    void setFromMatrix(const GLdouble m[16]);

    Frame inverse() const;
    Frame worldInverse() const { return Frame(-(orientation().inverseRotate(position())), orientation().inverse()); }

public:
    virtual QDomElement domElement(const QString& name, QDomDocument& document) const;
public Q_SLOTS:
    virtual void initFromDOMElement(const QDomElement& element);

private:
    // P o s i t i o n   a n d   o r i e n t a t i o n
    Vec t_;
    Quaternion q_;

    // C o n s t r a i n t s
    Constraint* constraint_;

    // F r a m e   c o m p o s i t i o n
    const Frame* referenceFrame_;
};

} // namespace qglviewer

#endif // QGLVIEWER_FRAME_H