Changeset 7494 for code/trunk/src/orxonox

Timestamp:

Sep 28, 2010, 5:31:59 PM (14 years ago)

Author:

dafrick

Message:

Some documenting and cleaning up/re-organization in pickups module.

Location:

code/trunk/src/orxonox

Files:

• interfaces/CMakeLists.txt (modified) (1 diff)
• interfaces/InterfaceCompilation.cc (modified) (2 diffs)
• interfaces/PickupCarrier.cc (added)
• interfaces/PickupCarrier.h (modified) (7 diffs)
• interfaces/Pickupable.cc (modified) (4 diffs)
• interfaces/Pickupable.h (modified) (7 diffs)
• pickup/PickupIdentifier.cc (modified) (3 diffs)
• pickup/PickupIdentifier.h (modified) (3 diffs)

code/trunk/src/orxonox/interfaces/CMakeLists.txt

@@ -2 +2 @@
   InterfaceCompilation.cc
   Pickupable.cc
+  PickupCarrier.cc
   RadarViewable.cc
 )

code/trunk/src/orxonox/interfaces/InterfaceCompilation.cc

@@ -34 +34 @@
 
 #include "GametypeMessageListener.h"
-#include "PickupCarrier.h"
 #include "PlayerTrigger.h"
 #include "RadarListener.h"
@@ -51 +50 @@
     {
         RegisterRootObject(GametypeMessageListener);
-    }
-
-    //----------------------------
-    // PickupCarrier
-    //----------------------------
-    PickupCarrier::PickupCarrier()
-    {
-        RegisterRootObject(PickupCarrier);
-    }
-
-    PickupCarrier::~PickupCarrier()
-    {
-
-    }
-
-    void PickupCarrier::preDestroy(void)
-    {
-        std::set<Pickupable*>::iterator it = this->pickups_.begin();
-        std::set<Pickupable*>::iterator temp;
-        while(it != this->pickups_.end())
-        {
-            (*it)->carrierDestroyed();
-            temp = it;
-            it = this->pickups_.begin();
-            if(it == temp) // Infinite loop avoidance, in case the pickup wasn't removed from the carrier somewhere in the carrierDestroy() procedure.
-            {
-                COUT(2) << "Oops. In a PickupCarrier, while cleaning up, a Pickupable (&" << (*temp) << ") didn't unregister itself as it should have." << std::endl;;
-                it++;
-            }
-        }
-
-        this->pickups_.clear();
     }
 

code/trunk/src/orxonox/interfaces/PickupCarrier.h

@@ -38 +38 @@
 #include "OrxonoxPrereqs.h"
 
-#include <list>
 #include <set>
-#include "Pickupable.h"
-#include "core/Identifier.h"
-#include "core/WeakPtr.h"
+#include <vector>
 
 #include "core/OrxonoxClass.h"
@@ -49 +46 @@
 {
 
-    //! Forward-declarations.
+    // Forward-declarations.
     class PickupManager;
     class Pickup;
@@ -60 +57 @@
     /**
     @brief
-        The PickupCarrier interface provides the means, for any class implementing it, to possess Pickupables.
+        The PickupCarrier interface provides the means, for any class implementing it, to possess @ref orxonox::Pickupable "Pickupables".
+
+        For a class to use the PickupCarrier interface it must implement the follwing three methods:
+        - <b>getCarrierPosition()</b> The getCarrierPosition() method returns the absolute position (in space) of the PickupCarrier.
+
+        Different PickupCarriers are structured hierarchically, a pickup can be picked up by a PickupCarrier that can't really carry that particular pickup but one of its children (or one of their children) can, and thus it gets "handed down" until it is at the right place.
+        But this structure has to be established first.
+        - <b>getCarrierChildren()</b> To this end a PickupCarrier needs to implement getCarrierChildren() which returns a list of its direct PickupCarrier children. If you need an example, have a look at @ref orxonox::Pawn "Pawn" and @ref orxonx::Engine "Engine".
+        - <b>getCarrierParent()</b> This is the method in the other direction. It returns the parent of this PickupCarrier, or NULL if the PickupCarrier is a root node in this hierarchy.
+
     @author
         Damian 'Mozork' Frick
@@ -66 +72 @@
     class _OrxonoxExport PickupCarrier : virtual public OrxonoxClass
     {
-        //! So that the different Pickupables have full access to their PickupCarrier.
+        // So that the different Pickupables have full access to their PickupCarrier.
         friend class Pickupable;
         friend class PickupManager;
-        //! Friends.
+        // Friends.
         friend class Pickup;
         friend class HealthPickup;
@@ -80 +86 @@
             PickupCarrier(); //!< Constructor.
             virtual ~PickupCarrier(); //!< Destructor.
-            void preDestroy(void);
+            void preDestroy(void); //!< Is called before the PickupCarrier is effectively destroyed.
 
-            /**
-            @brief Can be used to check whether the PickupCarrier or a child of his is a target ot the input Pickupable.
-            @param pickup A pointer to the Pickupable.
-            @return Returns true if the PickupCarrier or one of its children is a target, false if not.
-            */
-            bool isTarget(const Pickupable* pickup)
-                {
-                    if(pickup->isTarget(this)) //!< If the PickupCarrier itself is a target.
-                        return true;
-
-                    //! Go recursively through all children to check whether they are a target.
-                    std::vector<PickupCarrier*>* children = this->getCarrierChildren();
-                    for(std::vector<PickupCarrier*>::const_iterator it = children->begin(); it != children->end(); it++)
-                    {
-                        if((*it)->isTarget(pickup))
-                            return true;
-                    }
-
-                    children->clear();
-                    delete children;
-
-                    return false;
-                }
-
-            /**
-            @brief Get the carrier that is both a child of the PickupCarrier (or the PickupCarrier itself) and a target of the input Pickupable.
-            @param pickup A pounter to the Pickupable.
-            @return Returns a pointer to the PickupCarrier that is the target of the input Pickupable.
-            */
-            PickupCarrier* getTarget(const Pickupable* pickup)
-                {
-                    if(!this->isTarget(pickup))
-                        return NULL;
-
-                    if(pickup->isTarget(this)) //!< If the PickupCarrier itself is a target.
-                        return this;
-
-                    //! Go recursively through all children to check whether they are the target.
-                    std::vector<PickupCarrier*>* children = this->getCarrierChildren();
-                    for(std::vector<PickupCarrier*>::iterator it = children->begin(); it != children->end(); it++)
-                    {
-                        if(pickup->isTarget(*it))
-                            return *it;
-                    }
-
-                    children->clear();
-                    delete children;
-
-                    return NULL;
-                }
+            bool isTarget(const Pickupable* pickup); //!< Can be used to check whether the PickupCarrier or a child of his is a target ot the input Pickupable.
+            PickupCarrier* getTarget(const Pickupable* pickup); //!< Get the carrier that is both a child of the PickupCarrier (or the PickupCarrier itself) and a target of the input Pickupable.
 
             /**
@@ -149 +107 @@
             virtual std::vector<PickupCarrier*>* getCarrierChildren(void) = 0;
             /**
-            @brief Get the parent of this PickupSpawner
+            @brief Get the parent of this PickupSpawner.
                    This method needs to be implemented by any direct derivative class of PickupCarrier.
             @return Returns a pointer to the parent.
@@ -165 +123 @@
             std::set<Pickupable*> pickups_; //!< The list of Pickupables carried by this PickupCarrier.
 
-            /**
-            @brief Adds a Pickupable to the list of pickups that are carried by this PickupCarrier.
-            @param pickup A pointer to the pickup to be added.
-            @return Returns true if successfull, false if the Pickupable was already present.
-            */
-            bool addPickup(Pickupable* pickup)
-                {
-                    COUT(4) << "Adding Pickupable (&" << pickup << ") to PickupCarrier (&" << this << ")" << std::endl;
-                    return this->pickups_.insert(pickup).second;
-                }
-
-            /**
-            @brief Removes a Pickupable from the list of pickups that are carried by thsi PickupCarrier.
-            @param pickup A pointer to the pickup to be removed.
-            @return Returns true if successfull, false if the Pickupable was not present in the list.
-            */
-            bool removePickup(Pickupable* pickup)
-                {
-                    COUT(4) << "Removing Pickupable (&" << pickup << ") from PickupCarrier (&" << this << ")" << std::endl;
-                    return this->pickups_.erase(pickup) == 1;
-                }
+            bool addPickup(Pickupable* pickup); //!< Adds a Pickupable to the list of pickups that are carried by this PickupCarrier.
+            bool removePickup(Pickupable* pickup); //!< Removes a Pickupable from the list of pickups that are carried by this PickupCarrier.
 
     };

code/trunk/src/orxonox/interfaces/Pickupable.cc

@@ -39 +39 @@
 #include "core/CoreIncludes.h"
 #include "util/Convert.h"
+
 #include "infos/PlayerInfo.h"
 #include "pickup/PickupIdentifier.h"
 #include "worldentities/pawns/Pawn.h"
+
 #include "PickupCarrier.h"
 
@@ -130 +132 @@
         this->changedUsed();
 
+        //TODO: Synchronize & make safe for dedicated server.
         GUIManager::getInstance().getLuaState()->doString("PickupInventory.update()");
         return true;
@@ -277 +280 @@
             this->getCarrier()->removePickup(this);
         this->changedPickedUp();
+
+        //TODO: Synchronize & make safe for dedicated server.
         GUIManager::getInstance().getLuaState()->doString("PickupInventory.update()");
         return true;
@@ -303 +308 @@
                 return false;
         }
-        
+
         this->carrier_ = carrier;
         this->changedCarrier();

code/trunk/src/orxonox/interfaces/Pickupable.h

@@ -50 +50 @@
     @brief
         An Interface (or more precisely an abstract class) to model and represent different (all kinds of) pickups.
+
+        Pickups (@ref orxonox:Pickupable "Pickupables") are objects that (quite unsurprisingly) can be picked up. Additionally they can be used and unused (transition from used to not used), and also dropped.
+
+        A class of Pickups can incorporate many different types of pickups (see @ref orxonox::PickupIdentifier "PickupIdentifier"), each type is uniquely defined by a @ref orxonox::PickupIdentifier "PickupIdentifier". Each pickup has such an identifier identiying its type. This means that two pickups of the same type have identifiers which are equal.
+
     @author
         Damian 'Mozork' Frick
@@ -63 +68 @@
 
             /**
-            @brief Get whether the pickup is currently in use or not.
-            @return Returns true if the pickup is currently in use.
+            @brief Get whether the Pickupable is currently in use or not.
+            @return Returns true if the Pickupable is currently in use.
             */
             inline bool isUsed(void) { return this->used_; }  // tolua_export
             /**
-            @brief  Should be called when the pickup has transited from used to unused or the other way around.
+            @brief  Should be called when the Pickupable has transited from used to unused or the other way around.
                     Any Class overwriting this method must call its SUPER function by adding SUPER(Classname, changedUsed); to their changdeUsed method.
             */
@@ -74 +79 @@
 
             /**
-            @brief Get the carrier of the pickup.
-            @return Returns a pointer to the carrier of the pickup.
+            @brief Get the carrier of the Pickupable.
+            @return Returns a pointer to the carrier of the Pickupable.
             */
             inline PickupCarrier* getCarrier(void)
                 { return this->carrier_; }
             /**
-            @brief Should be called when the pickup has changed its PickupCarrier.
+            @brief Should be called when the Pickupable has changed its PickupCarrier.
                    Any Class overwriting this method must call its SUPER function by adding SUPER(Classname, changedCarrier); to their changedCarrier method.
             */
@@ -91 +96 @@
             inline bool isPickedUp(void) { return this->pickedUp_; }  // tolua_export
             /**
-            @brief  Should be called when the pickup has transited from picked up to dropped or the other way around.
+            @brief  Should be called when the Pickupable has transited from picked up to dropped or the other way around.
                     Any Class overwriting this method must call its SUPER function by adding SUPER(Classname, changedPickedUp); to their changedPickedUp method.
             */
@@ -119 +124 @@
             bool drop(bool createSpawner = true); //!< Can be called to drop a Pickupable.
 
-            virtual bool isTarget(PickupCarrier* carrier) const; //!< Get whether the given PickupCarrier is a target of this pickup.
+            virtual bool isTarget(PickupCarrier* carrier) const; //!< Get whether the given PickupCarrier is a target of this Pickupable.
             bool isTarget(const Identifier* identifier) const; //!< Get whether a given class, represented by the input Identifier, is a target of this Pickupable.
-            bool addTarget(PickupCarrier* target); //!< Add a PickupCarrier as target of this pickup.
-            bool addTarget(Identifier* identifier); //!< Add a class, representetd by the input Identifier, as target of this pickup.
+            bool addTarget(PickupCarrier* target); //!< Add a PickupCarrier as target of this Pickupable.
+            bool addTarget(Identifier* identifier); //!< Add a class, representetd by the input Identifier, as target of this Pickupable.
 
             Pickupable* clone(void); //!< Creates a duplicate of the Pickupable.
@@ -137 +142 @@
             bool setPickedUp(bool pickedUp); //!< Helper method to set the Pickupable to either picked up or not picked up.
             //TODO: private?
-            bool setCarrier(PickupCarrier* carrier, bool tell = true); //!< Sets the carrier of the pickup.
+            bool setCarrier(PickupCarrier* carrier, bool tell = true); //!< Sets the carrier of the Pickupable.
 
             //TODO: private?
             virtual void carrierDestroyed(void); //!< Is called by the PickupCarrier when it is being destroyed.
 
-            void destroy(void); //!< Is called internally within the pickup module to destroy pickups.
+            void destroy(void); //!< Is called internally within the Pickupable module to destroy pickups.
 
         protected:
@@ -187 +192 @@
     };  // tolua_export
 
+    //! SUPER functions.
     SUPER_FUNCTION(10, Pickupable, changedUsed, false);
     SUPER_FUNCTION(12, Pickupable, changedCarrier, false);

code/trunk/src/orxonox/pickup/PickupIdentifier.cc

@@ -35 +35 @@
 
 #include "core/CoreIncludes.h"
+#include "core/Identifier.h"
+
 #include "interfaces/Pickupable.h"
 
@@ -69 +71 @@
     int PickupIdentifier::compare(const PickupIdentifier* identifier) const
     {
-        if(identifier == NULL)
-        {
-            return 1;
-            COUT(1) << "Error in PickupIdentifier::compare: Input Identifier is NULL." << std::endl;
-        }
+        assert(identifier);
+        assert(identifier->pickup_);
+        assert(this->pickup_);
 
-        if(identifier->pickup_ == NULL && this->pickup_ == NULL)
-        {
-            return 0;
-            COUT(1) << "Error in PickupIdentifier::compare: Pickup stored by Identifier is NULL." << std::endl;
-        }
-
-        if(identifier->pickup_ == NULL)
-        {
-            return 1;
-            COUT(1) << "Error in PickupIdentifier::compare: Pickup stored by Identifier is NULL." << std::endl;
-        }
-
-        if(this->pickup_ == NULL)
-        {
-            return -1;
-            COUT(1) << "Error in PickupIdentifier::compare: Pickup stored by Identifier is NULL." << std::endl;
-        }
-
-        //! If the classIdentifiers are not the same (meaning the PickupIdentifiers identify different classes), the obviously the two Pickupables identified by the PickupIdentifiers cannot be the same. An ordering is established through the alphabetical ordering of the respective classnames.
+        // If the classIdentifiers are not the same (meaning the PickupIdentifiers identify different classes), the obviously the two Pickupables identified by the PickupIdentifiers cannot be the same. An ordering is established through the alphabetical ordering of the respective classnames.
         if(!identifier->pickup_->getIdentifier()->isExactlyA(this->pickup_->getIdentifier()))
             return this->pickup_->getIdentifier()->getName().compare(identifier->pickup_->getIdentifier()->getName());
 
-        //! If the class is the same for both PickupIdentifiers we go on to check the parameters of the class.
-        //! If the two have a different number of parameters then obviusly something is very wrong.
+        // If the class is the same for both PickupIdentifiers we go on to check the parameters of the class.
+        // If the two have a different number of parameters then obviously something is very wrong.
         if(!(this->parameters_.size() == identifier->parameters_.size()))
         {
@@ -105 +87 @@
         }
 
-        //! We iterate through all parameters and compare their values (which are strings). The first parameter is the most significant. The ordering is once again established by the alphabetical comparison of the two value strings.
+        // We iterate through all parameters and compare their values (which are strings). The first parameter is the most significant. The ordering is once again established by the alphabetical comparison of the two value strings.
         for(std::map<std::string, std::string>::const_iterator it = this->parameters_.begin(); it != this->parameters_.end(); it++)
         {
-            //!< If a parameter present in one of the identifiers is not found in the other, once again, something is very wrong.
+            // If a parameter present in one of the identifiers is not found in the other, once again, something is very wrong.
             if(identifier->parameters_.find(it->first) == identifier->parameters_.end())
             {

code/trunk/src/orxonox/pickup/PickupIdentifier.h

@@ -40 +40 @@
 #include <map>
 #include <string>
-#include "core/Identifier.h"
 
 #include "core/OrxonoxClass.h"
@@ -49 +48 @@
     /**
     @brief
-        The purpose of the PickupIdentifier class is to identify different types of pickups allthough they are of the same class.
-        This allows for more generic classes (or pickups in this case) that can be a number of different pickup types and can be identified as such without the need for a lot of different classes. An example is the HealthPickup class that encompasses a wide variety of different types of health pickups, e.g a HealthPickup that adds 10 health every second for 10 seconds or a HealthPickup that adds 100 health as soon as it is picked up, a.s.o.
-        To that purpose this class provides functionality to compare two PickupIdentifier (and since all Pickupables have an Identifier through that Pickupables can be compared). It als provides functionality to add parameters that distinguish between different types of pickups in the same pickup class.
-        Lastly a struct is provided that can be used in stl containers to establish a strictly lesser ordering between PickupIdentifiers (and thus Pickupables).
+        The purpose of the PickupIdentifier class is to identify (or differentiate between) different types of pickups although they are of the same class.
+
+        This allows for more generic classes (or pickups in this case) that can be a number of different pickup types and can be identified as such without the need for a lot of different classes.
+
+        An example is the @ref orxonox::HealthPickup "HealthPickup" class that encompasses a wide variety of different types of health pickups, e.g a @ref orxonox::HealthPickup "HealthPickup" that adds 10 health every second for 10 seconds or a @ref orxonox::HealthPickup "HealthPickup" that adds 100 health as soon as it is picked up, a.s.o.
+
+        To that purpose this class provides functionality to compare two @ref orxonox::PickupIdentifier "PickupIdentifiers" (and since all @ref orxonox::Pickupable "Pickupables" have an identifier, we can use it to compare pickups). It als provides functionality to add parameters that distinguish between different types of pickups in the same pickup class.
+
+        Lastly a struct (@ref orxonox::PickupIdentifierCompare "PickupIdentifierCompare") is provided that can be used in stl containers to establish a strictly lesser ordering between @ref orxonox::PickupIdentifier "PickupIdentifiers" (and thus @ref orxonox::Pickupable "Pickupables").
     @author
         Damian 'Mozork' Frick
@@ -75 +79 @@
     /**
     @brief
-        Struct that overloads the compare operation between two PickupIdentifier pointers.
+        Struct that overloads the compare operation between two @ref orxonox::PickupIdentifier "PickupIdentifier" pointers.
     */
     struct PickupIdentifierCompare