OgreHapticsDevice.h

Go to the documentation of this file.

/*
This source file is part of OgreHaptics
 (a library for wrapping haptics devices for use with the open-source
 graphics engine OGRE, http://www.ogre3d.org)

Copyright (c) 2006 - 2008 Jorrit de Vries
Also see acknowledgements in Readme.html

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License
as published by the Free Software Foundation; either version 2.1
of the License, or (at your option) any later version.

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
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the
Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
*/
// -- Frame listener & events implementation based on Ogre::Root, original copyright follows --
//
// This source file is part of OGRE
//    (Object-oriented Graphics Rendering Engine)
// For the latest info, see http://www.ogre3d.org/
//
// Copyright (c) 2000-2006 Torus Knot Software Ltd
// Also see acknowledgements in Readme.html
//
// This program is free software; you can redistribute it and/or modify it under
// the terms of the GNU Lesser General Public License as published by the Free Software
// Foundation; either version 2 of the License, or (at your option) any later
// version.
//
// This program 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 GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License along with
// this program; if not, write to the Free Software Foundation, Inc., 59 Temple
// Place - Suite 330, Boston, MA 02111-1307, USA, or go to
// http://www.gnu.org/copyleft/lesser.txt.
//
// You may alternatively use this source under the terms of a specific version of
// the OGRE Unrestricted License provided you have obtained such a license from
// Torus Knot Software Ltd.
#ifndef _OgreHapticsDevice_H__
#define _OgreHapticsDevice_H__

#include "OgreHapticsPrerequisites.h"
#include "OgreHapticsAtomic.h"
#include "OgreHapticsCommon.h"
#include "OgreHapticsConcurrentQueue.h"
#include "OgreHapticsEvent.h"
#include "OgreHapticsForceOutput.h"

namespace OgreHaptics {

    enum DeviceButton
    {
        DB_NO_BUTTON = 0,
        DB_BUTTON1 = 0x01,
        DB_BUTTON2 = 0x02,
        DB_BUTTON3 = 0x04,
        DB_BUTTON4 = 0x08,
        DB_INKWELL = DB_BUTTON3,
        DB_SAFETY = DB_BUTTON4,
    };

    enum DeviceCalibrationState
    {
        DCS_NOT_INITIALISED,
        DCS_NEEDS_CALIBRATION,
        DCS_CALIBRATED
    };

    enum DeviceCalibrationType
    {
        DCT_UNKNOWN,
        DCT_AUTO,
        DCT_INKWELL,
        DCT_PULL_PUSH,
        DCT_RESET_POSITION
    };

    struct DeviceState
    {
        DeviceState()
            : buttons(0),
            force(Vector3::ZERO),
            torque(Vector3::ZERO),
            position(Vector3::ZERO),
            linearVelocity(Vector3::ZERO),
            angularVelocity(Vector3::ZERO),
            orientation(Quaternion::IDENTITY)
        {}
        DeviceState(const DeviceState& rhs)
            : buttons(rhs.buttons),
            force(rhs.force),
            torque(rhs.torque),
            position(rhs.position),
            linearVelocity(rhs.linearVelocity),
            angularVelocity(rhs.angularVelocity),
            orientation(rhs.orientation)
        {}

        int buttons;
        Vector3 force;
        Vector3 torque;
        Vector3 position;
        Vector3 linearVelocity;
        Vector3 angularVelocity;
        Quaternion orientation;

        DeviceState& operator = (const DeviceState& rhs)
        {
            buttons = rhs.buttons;
            force = rhs.force;
            torque = rhs.torque;
            position = rhs.position;
            linearVelocity = rhs.linearVelocity;
            angularVelocity = rhs.angularVelocity;
            orientation = rhs.orientation;
            return *this;
        }
    };

    class _OgreHapticsExport DeviceEvent : public EventArgs
    {
    public:
        DeviceEvent(EventType type, Device* devic, DeviceState state,
            DeviceButton btn, DeviceCalibrationState calState)
            : EventArgs(type),
            device(devic),
            cachedState(state),
            button(btn),
            calibrationState(calState)
        {}
        virtual ~DeviceEvent() {}

        Device* device;
        DeviceState cachedState;
        DeviceButton button;
        DeviceCalibrationState calibrationState;
    };

    class _OgreHapticsExport DeviceListener
    {
    public:
        virtual ~DeviceListener() {}

        virtual void buttonPressed(const DeviceEvent& evt) {}
        virtual void buttonReleased(const DeviceEvent& evt) {}
        virtual void calibrationStateChanged(const DeviceEvent& evt) {}
    };

    class _OgreHapticsExport Device
    {
        // Allow RenderSystem class full access
        friend class RenderSystem;
    public:
        struct RenderStats
        {
            float lastFPS;
            float avgFPS;
            float bestFPS;
            float worstFPS;
            double bestFrameTime;
            double worstFrameTime;
        };

        virtual ~Device();

        virtual void _notifyCreator(RenderSystem* renderSystem);
        virtual RenderSystem* _getCreator(void) const { return mCreator; }

        const String& getName(void) const { return mName; }

        const String& _getInitName(void) const { return mInitName; }
        int _getInitIndex(void) const { return mIndex; }

        const String& getModel(void) const { return mModel; }
        int getSDKVersion(void) const { return mSDKVersion; }
        int getDriverVersion(void) const { return mDriverVersion; }

        //virtual void getConfigOptions(void) = 0;
        //virtual void setConfigOption(const String& name, const String& value) = 0; 

        virtual void initialise(void) = 0;
        virtual void shutdown(void) = 0;
        bool isInitialised(void) const { return mIsInitialised; };
        
        DeviceCalibrationType getCalibrationType(void) const { return mCalibrationType; }
        bool needsCalibration(void) const;
        DeviceCalibrationState getCalibrationState(void) const;
        virtual void calibrate(void) = 0;

        virtual void enable(void) = 0;
        void disable(void);
        bool isEnabled(void) const { return mIsEnabled; }
        
        const RenderStats& getStatistics(void);
        void resetStatistics(void);

        const Real* getDeviceWorkspaceDimensions(void) const;

        void setTouchspaceExtents(const Vector3& leftLowerBack,
            const Vector3& rightUpperFront);
        void setTouchspaceExtents(Real left, Real bottom, Real back,
            Real right, Real top, Real front);
        const Real* getTouchspaceExtents(void) const { return mTouchspaceExtents; }

        void setWorldTouchMatrix(const Matrix4& worldTouchMatrix);
        const Matrix4& getWorldTouchMatrix(void) const { return mWorldTouchMatrix; }
        const Matrix4& getTouchWorkspaceMatrix(void) const { return mTouchWorkspaceMatrix; }
        const Matrix4& getWorldTouchWorkspaceMatrix(void) const { return mWorldTouchWorkspaceMatrix; }
        const Vector3* getWorldWorkspaceCorners(void);
        void updateWorkspaceMapping(bool synchronise = true);

        void capture(void);

        void setDeviceListener(DeviceListener* listener) { mListener = listener; }

        bool isButtonDown(DeviceButton button);

        const Vector3& getPosition(void) const;
        const Quaternion& getOrientation(void) const;
        const Vector3& getForce(void) const;
        const Vector3& getTorque(void) const;
        const Vector3& getLinearVelocity(void) const;
        const Vector3& getAngularVelocity(void) const;

        const Vector3& getWorldPosition(void) const;
        const Quaternion& getWorldOrientation(void) const;
        const Vector3& getWorldForce(void) const;
        const Vector3& getWorldTorque(void) const;
        const Vector3& getWorldLinearVelocity(void) const;
        const Vector3& getWorldAngularVelocity(void) const;

        void update(void);

        const Vector3& _getPosition(void) const;
        const Quaternion& _getOrientation(void) const;
        const Vector3& _getForce(void) const;
        const Vector3& _getTorque(void) const;
        const Vector3& _getLinearVelocity(void) const;
        const Vector3& _getAngularVelocity(void) const;

        const Vector3& _getWorldPosition(void) const;
        const Quaternion& _getWorldOrientation(void) const;
        const Vector3& _getWorldForce(void) const;
        const Vector3& _getWorldTorque(void) const;
        const Vector3& _getWorldLinearVelocity(void) const;
        const Vector3& _getWorldAngularVelocity(void) const;

        const Vector3& _getPreviousPosition(void) const;
        const Quaternion& _getPreviousOrientation(void) const;
        const Vector3& _getPreviousForce(void) const;
        const Vector3& _getPreviousTorque(void) const;
        const Vector3& _getPreviousLinearVelocity(void) const;
        const Vector3& _getPreviousAngularVelocity(void) const;

        const Vector3& _getPreviousWorldPosition(void) const;
        const Quaternion& _getPreviousWorldOrientation(void) const;
        const Vector3& _getPreviousWorldForce(void) const;
        const Vector3& _getPreviousWorldTorque(void) const;
        const Vector3& _getPreviousWorldLinearVelocity(void) const;
        const Vector3& _getPreviousWorldAngularVelocity(void) const;

        bool _isButtonDown(DeviceButton button);

        virtual bool _setOption(const String& key, const void* value);

        virtual bool _getOption(const String& key, void* value);

        void _setFrameListener(FrameListener* listener);

        void _addEffect(ForceEffect* effect);
        void _removeEffect(ForceEffect* effect, bool immediate = false);
        void _restartEffect(ForceEffect* effect);
        void _updateEffect(ForceEffect* effect);

        virtual void _applyForces(const Vector3& force, const Vector3& torque) = 0;

        virtual void _makeCurrent(void) = 0;
    protected:
        Device(const String& name, const DeviceInitInfo& initInfo, int index = -1);

        String mName;
        String mInitName;
        String mModel;
        RenderSystem* mCreator;
        Timer* mTimer;
        int mIndex;
        int mSDKVersion;
        int mDriverVersion;
        bool mIsInitialised;
        bool mIsEnabled;
        bool mDeviceWorkspaceDimensionsDirty;
        bool mRecalcWorkspaceMapping;
        bool mSynchroniseWorkspaceMatrices;
        bool mRecalcWorldWorkspaceCorners;
        DeviceCalibrationType mCalibrationType;
        
        Real mDeviceWorkspaceDimensions[6];
        Real mTouchspaceExtents[6];
        Matrix4 mWorldTouchMatrix;
        Matrix4 mhtWorldTouchMatrix;
        Matrix4 mTouchWorkspaceMatrix;
        Matrix4 mhtTouchWorkspaceMatrix;
        Matrix4 mInverseTouchWorkspaceMatrix;
        Matrix4 mhtInverseTouchWorkspaceMatrix;
        Matrix4 mWorldTouchWorkspaceMatrix;
        Matrix4 mhtWorldTouchWorkspaceMatrix;
        Matrix4 mInverseWorldTouchWorkspaceMatrix;
        Matrix4 mhtInverseWorldTouchWorkspaceMatrix;
        Vector3 mWorldWorkspaceCorners[8];

        AtomicScalar<DeviceCalibrationState> mCalibrationState;
        mutable RenderStats mStats;
        RenderStats mhtStats;
        unsigned int mhtFrameCount;
        double mhtFrameTime;
        double mhtLastTime;
        double mhtLastSecond;

        DeviceState mDeviceState;
        DeviceState mhtDeviceState;
        DeviceState mhtPreviousDeviceState;
        DeviceState mWorldDeviceState;
        DeviceState mhtWorldDeviceState;
        DeviceState mhtPreviousWorldDeviceState;

        enum EventTypes
        {
            ET_BUTTON_DOWN,
            ET_BUTTON_UP,
            ET_CALIBRATION_STATE_CHANGED
        };
        ConcurrentQueue<EventArgs*> mEventQueue;
        ConcurrentQueue<EventArgs*>::HazardPtr* mEventQueueHazardPtr;
        ConcurrentQueue<EventArgs*>::HazardPtr* mhtEventQueueHazardPtr;
        DeviceListener* mListener;

        enum FrameEventTimeType
        {
            FETT_ANY = 0,
            FETT_STARTED = 1,
            FETT_ENDED = 2,
            FETT_COUNT = 3
        };
        double mEventTimes[FETT_COUNT][2];

        FrameListener* mFrameListener;
        AtomicScalar<int> mFrameListenerLock;

        typedef std::set<ForceEffect*> ForceEffectList;
        ForceEffectList mEffectsToStart;
        ForceEffectList mEffectsToStop;
        ForceEffectList mEffectsToUpdate;
        ForceEffectList mhtFadingInEffects;
        ForceEffectList mhtSustainingEffects;
        ForceEffectList mhtFadingOutEffects;
        ForceOutput mhtOutput;

        void _fireEvent(EventType type, const EventArgs& evt);
        void _fireFrameStarted(void);
        void _fireFrameEnded(void);
        virtual void clearEventTimes(void);
        double calculateEventTime(double currentTime, FrameEventTimeType type);
        void _fireFrameStarted(FrameEvent& evt);
        void _fireFrameEnded(FrameEvent& evt);

        void updateTouchWorkspaceMapping(void);
        void updateWorldWorkspaceCorners(void);

        virtual void disableImpl(void) = 0;
        void renderCallbackImpl(void);

        void updateStats(double currentTime);
        void updateStates(void);
        virtual void obtainStateValues(double timeElapsed) = 0;
        /*
        Checks if the state, e.g. pressed or released, of a grip button has
        changed and adds event to queue in the case of change of button state.
        @remarks
            Used in the haptic thread.
        */
        void checkButtonState(int oldButtons, int newButtons, DeviceButton button);
        void renderEffects(double currentTime);

        void synchroniseMatricesCallbackImpl(void);
        void synchroniseEffectsCallbackImpl(void);

        static SchedulerCallbackCode statisticsResetCallback(void* params);
        static SchedulerCallbackCode synchroniseStatisticsCallback(void* params);
        static SchedulerCallbackCode synchroniseStatesCallback(void* params);
        static SchedulerCallbackCode synchroniseMatricesCallback(void* params);
        static SchedulerCallbackCode updateCallback(void* params);
        static SchedulerCallbackCode removeEffectImmediateCallback(void* params);
    };

}

#endif

---

Last modified Tue Jan 6 22:31:25 2009