Changeset 3286

Timestamp:

Jul 13, 2009, 8:54:43 PM (15 years ago)

Author:

rgrieder

Message:

Added and adjusted documentation for the devices.
Also removed one last ugliness where the InputManager was called from within a device (which should not even know about the InputManager).

Location:

code/branches/core4/src/core/input

Files:

• InputDevice.h (modified) (10 diffs)
• InputHandler.h (modified) (3 diffs)
• InputManager.cc (modified) (5 diffs)
• InputManager.h (modified) (1 diff)
• InputPrereqs.h (modified) (12 diffs)
• JoyStick.cc (modified) (5 diffs)
• JoyStick.h (modified) (4 diffs)
• JoyStickQuantityListener.cc (modified) (1 diff)
• JoyStickQuantityListener.h (modified) (2 diffs)
• Keyboard.h (modified) (3 diffs)
• Mouse.cc (modified) (4 diffs)
• Mouse.h (modified) (6 diffs)

code/branches/core4/src/core/input/InputDevice.h

@@ -29 +29 @@
 /**
 @file
-@brief 
+@brief
+    Implementation of InputDevice and InputDeviceTemplated
 */
 
@@ -38 +39 @@
 
 #include <vector>
-#include <boost/foreach.hpp>
 #include <ois/OISInputManager.h>
 
 #include "util/Debug.h"
 #include "core/Clock.h"
-// TODO: Try to remove this
-#include "InputManager.h"
 #include "InputState.h"
 
@@ -51 +49 @@
     /**
     @brief
+        Abstract base class for all input devices (mouse, keyboard and joy sticks).
+
+        It provides common virtual functions to be used by the InputManager.
     */
     class InputDevice
     {
-        friend class InputManager;
-
     public:
-        InputDevice(unsigned int id) : bCalibrating_(false), id_(id) { }
+        //! Only resets the members
+        InputDevice(unsigned int id) : bCalibrating_(false), deviceID_(id) { }
         virtual ~InputDevice() { }
-        virtual std::string getClassName() = 0;
+        //! Returns the device class (derived) name as string
+        virtual std::string getClassName() const = 0;
+        //! Updates the device which should in turn distribute events
         virtual void update(const Clock& time) = 0;
+        //! Clear all button related buffers
         virtual void clearBuffers() = 0;
 
+        //! Start calibrating (only useful for joy sticks)
         void startCalibration()
         {
@@ -69 +73 @@
         }
 
+        //! Stop calibrating and evaluate the data (only useful for joy sticks)
         void stopCalibration()
         {
@@ -75 +80 @@
         }
 
-        unsigned int getDeviceID() { return this->id_; }
+        //! Returns a reference to the internal input state vector. Use with care!
+        std::vector<InputState*>& getStateListRef() { return this->inputStates_; }
+        //! Returns the ID of the device (the same as in InputDeviceEnumerator for mouse and keyboard)
+        unsigned int getDeviceID() const { return this->deviceID_; }
+        //! Tells whether the device is in calibration mode
+        bool isCalibrating() const { return bCalibrating_; }
 
     protected:
+        //! To be ovrridden by the subclass
         virtual void calibrationStarted() { }
+        //! To be ovrridden by the subclass
         virtual void calibrationStopped() { }
-        bool isCalibrating() { return bCalibrating_; }
-
-        // InputState handling
+
+        //! List of all input states that receive events from this device
         std::vector<InputState*> inputStates_;
 
     private:
-        InputDevice(const InputDevice& rhs);
-
-        std::vector<InputState*>& getStateListRef()
-        {
-            return this->inputStates_;
-        }
-
-        bool bCalibrating_;
-        const unsigned int id_;
+        InputDevice(const InputDevice& rhs); //!< Don't use!
+
+        bool bCalibrating_;                  //!< Whether the device is in calibration mode
+        const unsigned int deviceID_;        //!< ID of the device (the same as in InputDeviceEnumerator for mouse and keyboard)
     };
 
     /**
     @brief
+        Heavily templated base class for all three input devices.
+
+        The purpose of this class is not to provide an interface but rather
+        to reduce code redundancy. This concerns device creation and destruction
+        as well as common code for button events (press, release, hold).
+
+        In order to derive from this class you have to supply it with a struct
+        as template parameter that contains the necessary type traits.
     */
     template <class Traits>
@@ -110 +124 @@
 
     public:
-        InputDeviceTemplated(unsigned int id)
+        //! Creates the OIS device
+        InputDeviceTemplated(unsigned int id, OIS::InputManager* oisInputManager)
             : InputDevice(id)
-        {
-            OIS::InputManager* system = InputManager::getInstance().getOISInputManager();
-            oisDevice_ = static_cast<OISDeviceClass*>(system->createInputObject(OISDeviceValue, true));
+            , oisInputManager_(oisInputManager)
+        {
+            oisDevice_ = static_cast<OISDeviceClass*>(oisInputManager_->createInputObject(OISDeviceValue, true));
+            // Note: after the static_cast here, the casted this pointer becomes
+            //       invalid right until the subclass has been constructed!
             oisDevice_->setEventCallback(static_cast<DeviceClass*>(this));
             COUT(4) << "Instantiated a " << this->getClassName() << std::endl;
         }
 
+        //! Destroys the OIS device
         virtual ~InputDeviceTemplated()
         {
             try
             {
-                InputManager::getInstance().getOISInputManager()->destroyInputObject(oisDevice_);
+                oisInputManager_->destroyInputObject(oisDevice_);
             }
             catch (...)
@@ -131 +149 @@
         }
 
-        OISDeviceClass* getOISDevice()
-        {
-            return this->oisDevice_;
-        }
-
-        std::string getClassName()
-        {
-            return DeviceClass::getClassNameImpl();
-        }
-
+        //! Captures OIS events (which then get distributed to the derived class) and creates the button held events
         void update(const Clock& time)
         {
             oisDevice_->capture();
 
-            if (!this->isCalibrating())
-            {
-                // Call all the states with the held button event
-                for (unsigned int iB = 0; iB < pressedButtons_.size(); ++iB)
-                    for (unsigned int iS = 0; iS < inputStates_.size(); ++iS)
-                        inputStates_[iS]->buttonEvent<ButtonEvent::THold, Traits>(
-                            this->getDeviceID(), static_cast<DeviceClass*>(this)->getButtonEventArg(pressedButtons_[iB]));
-
-                // Call states with device update events
-                for (unsigned int i = 0; i < inputStates_.size(); ++i)
-                    inputStates_[i]->update(time.getDeltaTime(), this->getDeviceID());
-            }
+            // Call all the states with the held button event
+            for (unsigned int iB = 0; iB < pressedButtons_.size(); ++iB)
+                for (unsigned int iS = 0; iS < inputStates_.size(); ++iS)
+                    inputStates_[iS]->buttonEvent<ButtonEvent::THold, Traits>(
+                        this->getDeviceID(), static_cast<DeviceClass*>(this)->getButtonEventArg(pressedButtons_[iB]));
+
+            // Call states with device update events
+            for (unsigned int i = 0; i < inputStates_.size(); ++i)
+                inputStates_[i]->update(time.getDeltaTime(), this->getDeviceID());
 
             static_cast<DeviceClass*>(this)->updateImpl(time);
         }
 
+        //! Clears the list of pressed buttons and calls the derived class's method
         void clearBuffers()
         {
@@ -167 +174 @@
         }
 
+        // Returns a pointer to the OIS device
+        OISDeviceClass* getOISDevice()   { return this->oisDevice_; }
+        // Returns the name of the derived class as string
+        std::string getClassName() const { return DeviceClass::getClassNameImpl(); }
+
     protected:
+        //! Common code for all button pressed events (updates pressed buttons list and calls the input states)
         void buttonPressed(ButtonTypeParam button)
         {
@@ -184 +197 @@
         }
 
+        //! Common code for all button released events (updates pressed buttons list and calls the input states)
         void buttonReleased(ButtonTypeParam button)
         {
@@ -201 +215 @@
         }
 
+        //! Managed pointer to the OIS device
         OISDeviceClass* oisDevice_;
 
     private:
-        void clearBuffersImpl() { } //!< Fallback dummy function for static polymorphism
-        void updateImpl(const Clock& time) { } //!< Fallback dummy function for static polymorphism
+        //!< Fallback dummy function for static polymorphism
+        void clearBuffersImpl() { }
+        //!< Fallback dummy function for static polymorphism
+        void updateImpl(const Clock& time) { }
         //!< Fallback dummy function for static polymorphism
         ButtonType& getButtonEventArg(ButtonType& button) { return button; }
 
-        std::vector<ButtonType> pressedButtons_;
+        std::vector<ButtonType> pressedButtons_; //!< List of all buttons that are currently pressed down
+        OIS::InputManager* oisInputManager_;     //!< Pointer to the OIS InputManager that can create and destroy devices
     };
 }

code/branches/core4/src/core/input/InputHandler.h

@@ -26 +26 @@
  *
  */
-
-/**
-@file
-@brief
-    Declarations of various interface classes for the input management.
-*/
 
 #ifndef _InputHandler_H__
@@ -100 +94 @@
     /**
     @brief
+        Base class for all input handlers like KeyBinder, InputBuffer, etc.
+
+        Derive from this class if you wish to receive input events.
+        But keep in mind that this is pointless wihtout first having an InputState.
+    @note
+        The definitions for the button events with the weird arguments are simply
+        to avoid redunant code in the input devices.
     */
     class _CoreExport InputHandler
@@ -140 +141 @@
         virtual void allDevicesUpdated(float dt) { }
 
+        //! Use this input handler if you want to occupy a device in an input state.
         static InputHandler EMPTY;
     };

code/branches/core4/src/core/input/InputManager.cc

@@ -201 +201 @@
 
             if (oisInputManager_->getNumberOfDevices(OIS::OISKeyboard) > 0)
-                devices_[InputDeviceEnumerator::Keyboard] = new Keyboard(InputDeviceEnumerator::Keyboard);
+                devices_[InputDeviceEnumerator::Keyboard] = new Keyboard(InputDeviceEnumerator::Keyboard, oisInputManager_);
             else
                 ThrowException(InitialisationFailed, "InputManager: No keyboard found, cannot proceed!");
@@ -232 +232 @@
             try
             {
-                devices_[InputDeviceEnumerator::Mouse] = new Mouse(InputDeviceEnumerator::Mouse, windowWidth, windowHeight);
+                devices_[InputDeviceEnumerator::Mouse] = new Mouse(InputDeviceEnumerator::Mouse, oisInputManager_, windowWidth, windowHeight);
             }
             catch (const OIS::Exception& ex)
@@ -251 +251 @@
             try
             {
-                devices_.push_back(new JoyStick(InputDeviceEnumerator::FirstJoyStick + i));
+                devices_.push_back(new JoyStick(InputDeviceEnumerator::FirstJoyStick + i, oisInputManager_));
             }
             catch (std::exception ex)
@@ -262 +262 @@
         for (ObjectList<JoyStickQuantityListener>::iterator it = ObjectList<JoyStickQuantityListener>::begin(); it; ++it)
             it->JoyStickQuantityChanged(devices_.size() - InputDeviceEnumerator::FirstJoyStick);
-    }
-
-    bool InputManager::checkJoyStickID(const std::string& idString) const
-    {
-        for (unsigned int i = InputDeviceEnumerator::FirstJoyStick; i < devices_.size(); ++i)
-            if (static_cast<JoyStick*>(devices_[i])->getIDString() == idString)
-                return false;
-        return true;
     }
 
@@ -565 +557 @@
         // Clear buffers to prevent button hold events
         this->clearBuffers();
+
+        COUT(0) << "Calibration has been stored." << std::endl;
     }
 

code/branches/core4/src/core/input/InputManager.h

@@ -161 +161 @@
         //! Sets the the name of the command used by the KeyDetector as callback.
         void setKeyDetectorCallback(const std::string& command);
-        /**
-        @brief
-            Checks whether there is already a joy stick with the given ID string.
-        @return
-            Returns true if ID is ok (unique), false otherwise.
-        */
-        bool checkJoyStickID(const std::string& idString) const;
         //! Returns the number of joy stick that have been created since the c'tor or last call to reload().
         unsigned int getJoyStickQuantity() const

code/branches/core4/src/core/input/InputPrereqs.h

@@ -30 +30 @@
 @file
 @brief
-    Declarations of various interface classes for the input management.
+    Declarations of all key/button/axis code enumeration and string literals
+    and an input device enumeration.
 */
 
@@ -52 +53 @@
         const unsigned int numberOfKeys = 0xEE; // 238
 
-        // note: KeyCode comments were directly copied from OISKeyboard.h
+        //! Key codes as enumeration
         enum ByEnum
         {
@@ -202 +203 @@
         };
         
-        // Names as string. Has no real linkage!
+        //! Key codes as strings
         const char* const ByString[] =
         {
@@ -307 +308 @@
         const unsigned int numberOfButtons = 8;
 
+        //! Mouse button codes as enumeration
         enum ByEnum
         {
@@ -319 +321 @@
         };
 
-        // Names as string. Has no real linkage!
+        // Mouse button codes as strings
         const char* const ByString[] =
         {
@@ -337 +339 @@
         const unsigned int numberOfAxes = 2;
 
+        // Mouse axis codes as enumeration
         enum ByEnum
         {
@@ -343 +346 @@
         };
 
-        // Names as string. Has no real linkage!
+        // Mouse axis codes as strings
         const char* const ByString[] =
         {
@@ -356 +359 @@
         const unsigned int numberOfButtons = 64;
 
+        // Joy stick button codes as enumeration
         enum ByEnum
         {
@@ -380 +384 @@
         };
 
-        // Names as string. Has no real linkage!
+        // Joy stick button codes as strings
         const char* const ByString[] =
         {
@@ -406 +410 @@
         const unsigned int numberOfAxes = 24;
 
+        // Joy stick axis codes as enumeration
         enum ByEnum
         {
@@ -416 +421 @@
         };
 
-        // Names as string. Has no real linkage!
+        // Joy stick axis codes as strings
         const char* const ByString[] =
         {
@@ -435 +440 @@
     namespace InputDeviceEnumerator
     {
+        //! Used to access the devices in an array
         enum Value
         {

code/branches/core4/src/core/input/JoyStick.cc

@@ -30 +30 @@
 
 #include <ois/OISJoyStick.h>
-#include <ois/OISInputManager.h>
 #include <boost/foreach.hpp>
 
@@ -38 +37 @@
 #include "util/Convert.h"
 #include "InputState.h"
-#include "InputManager.h"
 
 namespace orxonox
 {
-    /**
-    @brief
-        Helper function that loads the config value vector of one coefficient
-    */
+    //! Helper function that loads the config value vector of one coefficient
     void loadCalibration(std::vector<int>& list, const std::string& sectionName, const std::string& valueName, size_t size, int defaultValue);
 
-    JoyStick::JoyStick(unsigned int id)
-        : super(id)
+    std::vector<std::string> JoyStick::idStrings_s;
+
+    JoyStick::JoyStick(unsigned int id, OIS::InputManager* oisInputManager)
+        : super(id, oisInputManager)
     {
         RegisterRootObject(JoyStick);
@@ -66 +63 @@
         //idString_ += multi_cast<std::string>(oisDevice_->getNumberOfComponents(OIS::OIS_Vector3));
 
-        if (InputManager::getInstance().checkJoyStickID(idString_) == false)
-        {
-            // Make the ID unique for this execution time.
-            idString_ += "_" + multi_cast<std::string>(this->getDeviceID());
+
+        BOOST_FOREACH(std::string& idString, idStrings_s)
+        {
+            if (idString_ == idString)
+            {
+                // Make the ID unique for this execution time.
+                idString_ += "_" + multi_cast<std::string>(this->getDeviceID());
+                break;
+            }
         }
 
@@ -82 +84 @@
     }
 
-    //!< Callback for the joy stick calibration config file.
+    //! Callback for the joy stick calibration config file.
     void JoyStick::calibrationFileCallback()
     {
@@ -173 +175 @@
     }
 
-    // TODO: What do we really need to reset here?
+    //! Resets the pov states
     void JoyStick::clearBuffersImpl()
     {
         for (int j = 0; j < 4; ++j)
-        {
             povStates_[j] = 0;
-            sliderStates_[j][0] = 0;
-            sliderStates_[j][1] = 0;
-        }
     }
 

code/branches/core4/src/core/input/JoyStick.h

@@ -38 +38 @@
 namespace orxonox
 {
+    //! Template parameter collection for the base class
     struct JoyStickTraits
     {
@@ -66 +67 @@
     public:
         //! Assigns a generated ID string and loads the calibration (if present)
-        JoyStick(unsigned int id);
+        JoyStick(unsigned int id, OIS::InputManager* oisInputManager);
         ~JoyStick() { }
         void setConfigValues();
 
-        //! Returns the generated (from the number of knobs and the device name) ID string
+        //! Returns the ID string generated from the number of knobs and the device name
         const std::string& getIDString() const { return this->idString_; }
 
@@ -99 +100 @@
         bool sliderMoved   (const OIS::JoyStickEvent &arg, int id);
         bool povMoved      (const OIS::JoyStickEvent &arg, int id);
-        //!< OIS event handler (don't remove that because of OIS version issues!)
+        //! OIS event handler (don't remove that because of OIS version issues!)
         bool vector3Moved  (const OIS::JoyStickEvent &arg, int id) { return true; }
 
+        //! Returns the class name as string
         static std::string getClassNameImpl() { return "JoyStick"; }
 
@@ -120 +122 @@
         std::string calibrationFilename_;     //!< Joy stick calibration ini filename
 
+        //! Contains a list of all ID strings to avoid duplicates
+        static std::vector<std::string> idStrings_s;
+
         //!< Maximum number of slider axes
         static const unsigned int sliderAxes_s = 8;

code/branches/core4/src/core/input/JoyStickQuantityListener.cc

@@ -27 +27 @@
  */
 
-/**
-@file
-@brief
-    Implementation of the JoyStickQuantityListener class.
-*/
-
 #include "JoyStickQuantityListener.h"
 #include "core/CoreIncludes.h"

code/branches/core4/src/core/input/JoyStickQuantityListener.h

@@ -40 +40 @@
 namespace orxonox
 {
+    //! Derive from this class to get informed when joy sticks get added/removed
     class _CoreExport JoyStickQuantityListener : virtual public OrxonoxClass
     {
@@ -46 +47 @@
         virtual ~JoyStickQuantityListener() { }
 
+        //! Called when joy sticks get added/removed
         virtual void JoyStickQuantityChanged(unsigned int value) = 0;
     };

code/branches/core4/src/core/input/Keyboard.h

@@ -31 +31 @@
 
 #include "InputPrereqs.h"
+
 #include "InputHandler.h"
 #include "InputDevice.h"
@@ -36 +37 @@
 namespace orxonox
 {
+    //! Template parameter collection for the base class
     struct KeyboardTraits
     {
@@ -61 +63 @@
 
     public:
-        Keyboard(unsigned int id) : super(id), modifiers_(0) { }
+        //! Only resets the keyboard modifiers. Initialising is done in the base class.
+        Keyboard(unsigned int id, OIS::InputManager* oisInputManager) : super(id, oisInputManager), modifiers_(0) { }
         ~Keyboard() { }
 
     private:
-        // TODO: Do we need to reset the modifiers?
-        void clearBuffersImpl() { }
+        //! Resets the keyboard modifiers
+        void clearBuffersImpl() { this->modifiers_ = 0; }
         //! Translates the KeyHandle to a KeyEvent
-        KeyEvent& getButtonEventArg(KeyEvent& button) { button.setModifiers(modifiers_); return button; }
+        KeyEvent& getButtonEventArg(KeyEvent& button)
+        {
+            button.setModifiers(modifiers_);
+            return button;
+        }
 
         bool keyPressed(const OIS::KeyEvent& arg);
         bool keyReleased(const OIS::KeyEvent& arg);
 
+        //! Returns the class name as string
         static std::string getClassNameImpl() { return "Keyboard"; }
 

code/branches/core4/src/core/input/Mouse.cc

@@ -30 +30 @@
 
 #include <ois/OISMouse.h>
-#include <boost/foreach.hpp>
 #include "InputState.h"
 #include "core/ConsoleCommand.h"
@@ -41 +40 @@
 namespace orxonox
 {
-    Mouse::Mouse(unsigned int id, unsigned int windowWidth, unsigned int windowHeight)
-        : super(id)
+    Mouse::Mouse(unsigned int id, OIS::InputManager* oisInputManager, unsigned int windowWidth, unsigned int windowHeight)
+        : super(id, oisInputManager)
     {
         this->setMouseClipping(windowWidth, windowHeight);
@@ -74 +73 @@
             IntVector2 rel(e.state.X.rel, e.state.Y.rel);
             IntVector2 clippingSize(e.state.width, e.state.height);
-            BOOST_FOREACH(InputState* state, inputStates_)
-                state->mouseMoved(abs, rel, clippingSize);
+            for (unsigned int i = 0; i < inputStates_.size(); ++i)
+                inputStates_[i]->mouseMoved(abs, rel, clippingSize);
         }
 
@@ -81 +80 @@
         if (e.state.Z.rel != 0)
         {
-            BOOST_FOREACH(InputState* state, inputStates_)
-                state->mouseScrolled(e.state.Z.abs, e.state.Z.rel);
+            for (unsigned int i = 0; i < inputStates_.size(); ++i)
+                inputStates_[i]->mouseScrolled(e.state.Z.abs, e.state.Z.rel);
         }
 

code/branches/core4/src/core/input/Mouse.h

@@ -35 +35 @@
 namespace orxonox
 {
+    //! Template parameter collection for the base class
     struct MouseTraits
     {
@@ -58 +59 @@
 
     public:
-        Mouse(unsigned int id, unsigned int windowWidth, unsigned int windowHeight);
+        //! Only sets the clipping size. Initialising is done in the base class.
+        Mouse(unsigned int id, OIS::InputManager* oisInputManager, unsigned int windowWidth, unsigned int windowHeight);
         ~Mouse() { }
 
@@ -68 +70 @@
         */
         void setMouseClipping(unsigned int width, unsigned int height);
+        // Returns the width of the mouse window
         unsigned int getClippingWidth() const;
+        // Returns the height of the mouse window
         unsigned int getClippingHeight() const;
 
@@ -77 +81 @@
 #ifdef ORXONOX_PLATFORM_LINUX
         // HACK!
+        // TODO: Make this a feature rather than a hack
         static void grabMouse();
         static void ungrabMouse();
@@ -82 +87 @@
 
     private:
-        // TODO: Do we need to reset the mouse position?
-        void clearBuffersImpl() { }
-
         //! OIS event handler
         bool mousePressed(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
@@ -101 +103 @@
         bool mouseMoved(const OIS::MouseEvent &arg);
 
+        // Returns the class name as string
         static std::string getClassNameImpl() { return "Mouse"; }