OpenSceneGraph/include/osgGA/MatrixManipulator

/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield 
 *
 * This library is open source and may be redistributed and/or modified under  
 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or 
 * (at your option) any later version.  The full license is in LICENSE file
 * included with this distribution, and on the openscenegraph.org website.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
 * OpenSceneGraph Public License for more details.
*/

#ifndef OSGGA_MatrixManipulator
#define OSGGA_MatrixManipulator 1

#include <osg/Node>
#include <osg/Matrix>

#include <osgUtil/SceneView>

#include <osgGA/Export>
#include <osgGA/GUIEventHandler>
#include <osgGA/GUIEventAdapter>
#include <osgGA/GUIActionAdapter>

namespace osgGA{

/**

MatrixManipulator is an abstract base class defining the interface, and a certain
amount of default functionality, for classes which wish to control OSG cameras
in response to GUI events.

*/
class OSGGA_EXPORT MatrixManipulator : public GUIEventHandler
{
public:


        virtual const char* className() const { return "MatrixManipulator"; }

        /** set the position of the matrix manipulator using a 4x4 Matrix.*/
        virtual void setByMatrix(const osg::Matrix& matrix) = 0;

        /** set the position of the matrix manipulator using a 4x4 Matrix.*/
        virtual void setByInverseMatrix(const osg::Matrix& matrix) = 0;

        /** get the position of the manipulator as 4x4 Matrix.*/
        virtual osg::Matrix getMatrix() const = 0;

        /** get the position of the manipulator as a inverse matrix of the manipulator, typically used as a model view matrix.*/
        virtual osg::Matrix getInverseMatrix() const = 0;

        /** Get the FusionDistanceMode. Used by SceneView for setting up setereo convergence.*/
        virtual osgUtil::SceneView::FusionDistanceMode getFusionDistanceMode() const { return osgUtil::SceneView::PROPORTIONAL_TO_SCREEN_DISTANCE; }

        /** Get the FusionDistanceValue. Used by SceneView for setting up setereo convergence.*/
        virtual float getFusionDistanceValue() const { return 1.0f; }


        /**
        Attach a node to the manipulator, automatically detaching any previously attached node.
        setNode(NULL) detaches previous nodes.
        May be ignored by manipulators which do not require a reference model.
        */
        virtual void setNode(osg::Node*) {}

        /** Return const node if attached.*/
        virtual const osg::Node* getNode() const { return NULL; }

        /** Return node if attached.*/
        virtual osg::Node* getNode() { return NULL; }

        /**
        Move the camera to the default position. 
        May be ignored by manipulators if home functionality is not appropriate.
        */
        virtual void home(const GUIEventAdapter& ,GUIActionAdapter&) {}

        /**
        Start/restart the manipulator.
        FIXME: what does this actually mean? Provide examples.
        */
        virtual void init(const GUIEventAdapter& ,GUIActionAdapter&) {}

        /** Handle events, return true if handled, false otherwise. */
        virtual bool handle(const GUIEventAdapter& ea,GUIActionAdapter& us);

        /** Handle visitations */
        virtual void accept(GUIEventHandlerVisitor& v)    { v.visit(*this); }

protected:

        MatrixManipulator();
        virtual ~MatrixManipulator();

};

}

#endif