Changeset 6475 for code/branches/pickup3/src/orxonox

Timestamp:

Mar 5, 2010, 6:26:54 PM (15 years ago)

Author:

dafrick

Message:

Additional documentation, code niceifying and potential bug fixing. Also: Renamed DroppedItem to DroppedPickup.

Location:

code/branches/pickup3/src/orxonox

Files:

• interfaces/PickupCarrier.h (modified) (4 diffs)
• interfaces/Pickupable.cc (modified) (4 diffs)
• interfaces/Pickupable.h (modified) (4 diffs)
• pickup/PickupIdentifier.cc (modified) (4 diffs)
• pickup/PickupIdentifier.h (modified) (1 diff)
• worldentities/pawns/Pawn.h (modified) (1 diff)

code/branches/pickup3/src/orxonox/interfaces/PickupCarrier.h

@@ -65 +65 @@
             @return Returns true if the Pickupable was picked up, false if not.
             */
-            inline bool pickup(Pickupable* pickup)
+            bool pickup(Pickupable* pickup)
                 {
                     bool pickedUp = this->pickups_.insert(pickup).second;
@@ -78 +78 @@
             @return Returns true if the Pickupable has been dropped, false if not.
             */
-            inline bool drop(Pickupable* pickup)
+            bool drop(Pickupable* pickup)
                 { 
                    bool dropped = this->pickups_.erase(pickup) == 1;
@@ -84 +84 @@
                    {
                        pickup->dropped();
-                        //TODO: Create Spawner.
                    }
                    return dropped;
                 }
                 
-            inline bool isTarget(Pickupable* pickup)
+            /**
+            @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.
+            */
+            //TODO: Use?
+            bool isTarget(const Pickupable* pickup)
                 {
-                    if(pickup->isTarget(this))
+                    if(pickup->isTarget(this)) //!< If the PickupCarrier itself is a target.
                         return true;
-                    const std::list<PickupCarrier*>* children = this->getChildren();
+                    
+                    //! Go recursively through all children to check whether they are a target.
+                    std::list<PickupCarrier*>* children = this->getCarrierChildren();
                     for(std::list<PickupCarrier*>::const_iterator it = children->begin(); it != children->end(); it++)
                     {
@@ -100 +107 @@
                     }
                     
+                    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::list<PickupCarrier*>* children = this->getCarrierChildren();
+                    for(std::list<PickupCarrier*>::iterator it = children->begin(); it != children->end(); it++)
+                    {
+                        if(pickup->isTarget(*it))
+                            return *it;
+                    }
+                    
+                    children->clear();
+                    delete children;
+                    
+                    return NULL;
+                }
             
-        protected:            
-            //TODO: Good return type?
-            virtual const std::list<PickupCarrier*>* getChildren(void) = 0;
-            virtual PickupCarrier* getParent(void) = 0;
+        protected:        
+            /**
+            @brief Get all direct children of this PickupSpawner.
+                   This method needs to be implemented by any direct derivative class of PickupCarrier.
+            @return Returns a pointer to a list of all direct children. 
+            */
+            //TODO: Good return type? Maybe not const and destroyed in isTarget...
+            virtual std::list<PickupCarrier*>* getCarrierChildren(void) = 0;
+            /**
+            @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.
+            */
+            virtual PickupCarrier* getCarrierParent(void) = 0;
+            /**
+            @brief Get the (absolute) position of the PickupCarrier.
+                   This method needs to be implemented by any direct derivative class of PickupCarrier.
+            @return Returns the position as a Vector3.
+            */
+            virtual const Vector3& getCarrierPosition(void) = 0;
         
         private:
-            std::set<Pickupable*> pickups_;
+            std::set<Pickupable*> pickups_; //!< The list of Pickupables carried by this PickupCarrier.
             
-        
     };
-    
 }
 

code/branches/pickup3/src/orxonox/interfaces/Pickupable.cc

@@ -36 +36 @@
 #include "core/Identifier.h"
 #include "core/CoreIncludes.h"
+#include "pickup/PickupIdentifier.h"
 #include "PickupCarrier.h"
 
@@ -52 +53 @@
         this->pickedUp_ = false;
         this->carrier_ = NULL;
+        
+        this->pickupIdentifier_ = new PickupIdentifier();
     }
     
@@ -91 +94 @@
         Returns true if the given PickupCarrier is a target.
     */
-    bool Pickupable::isTarget(PickupCarrier* carrier)
+    bool Pickupable::isTarget(const PickupCarrier* carrier) const
     {
         Identifier* identifier = carrier->getIdentifier();
@@ -156 +159 @@
         this->setUsed(false);
         this->setPickedUp(false);
+        
+        bool created = this->createSpawner(this->getCarrier()->getCarrierPosition());
+        
         this->setCarrier(NULL);
+        if(!created)
+            this->destroy();
+        
         return true;
     }

code/branches/pickup3/src/orxonox/interfaces/Pickupable.h

@@ -39 +39 @@
 #include <list>
 #include "core/Super.h"
-#include "pickup/PickupIdentifier.h"
 
 #include "core/OrxonoxClass.h"
@@ -83 +82 @@
             bool dropped(void); //!< Sets the Pickupable to not picked up or dropped.
             
-            bool isTarget(PickupCarrier* carrier); //!< Get whether the given PickupCarrier is a target of this pickup.
+            bool isTarget(const PickupCarrier* carrier) const; //!< Get whether the given PickupCarrier is a target of this pickup.
             bool addTarget(PickupCarrier* target); //!< Add a PickupCarrier as target of this pickup.
             
@@ -108 +107 @@
             */
             virtual const PickupIdentifier* getPickupIdentifier(void)
-                { return &this->pickupIdentifier_; }
+                { return this->pickupIdentifier_; }
                 
             virtual void destroy(void)
@@ -120 +119 @@
             void initializeIdentifier(void) {}
             
+            /**
+            @brief Facilitates the creation of a PickupSpawner upon dropping of the Pickupable.
+                   This method must be implemented by any class directly inheriting from Pickupable. It is most easily done by just creating a new DroppedPickup, e.g.:
+                   DroppedPickup(BaseObject* creator, Pickupable* pickup, const Vector3& position, float triggerDistance);
+            @param position The position at which the PickupSpawner should be placed.
+            @return Returns true if a spawner was created, false if not.
+            */
+            virtual bool createSpawner(const Vector3& position) = 0;
+            
             //TODO: Move to private and create get method in protected.
-            PickupIdentifier pickupIdentifier_; //!< The PickupIdentifier of this Pickupable.
+            PickupIdentifier* pickupIdentifier_; //!< The PickupIdentifier of this Pickupable.
             
         private:

code/branches/pickup3/src/orxonox/pickup/PickupIdentifier.cc

@@ -34 +34 @@
 {
     
+    /**
+    @brief
+        Constructor. Registers the object and initializes member variables.
+    */
     PickupIdentifier::PickupIdentifier()
     {
         RegisterRootObject(PickupIdentifier);
         
-        
+        this->classIdentifier_ = NULL;
     }
     
@@ -52 +56 @@
         Pointer to the second PickupIdentifier, b.
     @return
-        Returns an int.
+        Returns an integer. 0 if the two compared PickupIdentifiers are the same, <0 if a < b and >0 if a > b.
     */
-    int PickupIdentifier::compare(const PickupIdentifier& identifier) const
+    int PickupIdentifier::compare(const PickupIdentifier* identifier) const
     {
-        if(!identifier.classIdentifier_->isExactlyA(this->classIdentifier_))
-            return this->classIdentifier_->getName().compare(identifier.classIdentifier_->getName());
+        //! 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->classIdentifier_->isExactlyA(this->classIdentifier_))
+            return this->classIdentifier_->getName().compare(identifier->classIdentifier_->getName());
         
-        if(!(this->parameters_.size() == identifier.parameters_.size()))
+        //! 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(!(this->parameters_.size() == identifier->parameters_.size()))
         {
             COUT(1) << "Something went wrong in PickupIdentifier!" << std::endl;
-            return this->parameters_.size()-identifier.parameters_.size();
+            return this->parameters_.size()-identifier->parameters_.size();
         }
         
+        //! We iterate through all parameters and compar 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(identifier.parameters_.find(it->first) == identifier.parameters_.end())
+            //!< 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())
             {
                 COUT(1) << "Something went wrong in PickupIdentifier!" << std::endl;
                 return -1;
             }
-            if(identifier.parameters_.find(it->first)->second != it->second)
-                return it->second.compare(identifier.parameters_.find(it->first)->second);
+            if(identifier->parameters_.find(it->first)->second != it->second)
+                return it->second.compare(identifier->parameters_.find(it->first)->second);
         }
             
@@ -79 +88 @@
     }
     
+    /**
+    @brief
+        Add the class of the Pickupable to its PickupIdentifier.
+    @param identifier
+        A pointer to the Identifier of the class.
+    */
     void PickupIdentifier::addClass(Identifier* identifier)
     {
@@ -84 +99 @@
     }
     
+    /**
+    @brief
+        Add a parameter to the PickupIdentifier.
+    @param name
+        The name of the parameter.
+    @param value
+        The value of the parameter.
+    @return
+        Returns false if the parameter already existed, true if not.
+    */
     bool PickupIdentifier::addParameter(std::string & name, std::string & value)
     {

code/branches/pickup3/src/orxonox/pickup/PickupIdentifier.h

@@ -32 +32 @@
 #include "OrxonoxPrereqs.h"
 
-#include "core/OrxonoxClass.h" 
-#include "core/Identifier.h"
 #include <map>
 #include <string>
+#include "core/Identifier.h"
+
+#include "core/OrxonoxClass.h" 
 
 namespace orxonox
 {
     
+    /**
+    @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).
+    @author
+        Damian 'Mozork' Frick
+    */
     class _OrxonoxExport PickupIdentifier : virtual public OrxonoxClass
     {
         
         public:
-            PickupIdentifier(void);
-            ~PickupIdentifier();
+            PickupIdentifier(void); //!< Constructor.
+            ~PickupIdentifier(); //!< Destructor.
             
-            virtual int compare(const PickupIdentifier& identifier) const;
+            virtual int compare(const PickupIdentifier* identifier) const; //!< Compares two PickupIdentifiers and returns 0 if a == b, <0 if a < b and >0 if a > b for a.compare(b).
             
-            void addClass(Identifier* identifier);
-            bool addParameter(std::string & name, std::string & value);
+            void addClass(Identifier* identifier); //!< Add the class of the Pickupable to its PickupIdentifier.
+            bool addParameter(std::string & name, std::string & value); //!< Add a parameter to the PickupIdentifier.
             
         private:
-            Identifier* classIdentifier_;
-            std::map<std::string, std::string> parameters_;
-            
+            Identifier* classIdentifier_; //!< The Identifier of the class.
+            std::map<std::string, std::string> parameters_; //!< The parameters identifying the type of the pickup beyond the class.
             
     };
     
-    //TODO: Needed?
+    /**
+    @brief
+        Struct that overloads the compare operation between two PickupIdentifier pointers.
+    */
     struct PickupIdentifierCompare
     {
-        bool operator() (const PickupIdentifier& lhs, const PickupIdentifier& rhs) const
-            { return lhs.compare(rhs) < 0; }
-    };
-    
-    struct PickupIdentifierPtrCompare
-    {
         bool operator() (const PickupIdentifier* lhs, const PickupIdentifier* rhs) const
-            { return lhs->compare(*rhs) < 0; }
+            { return lhs->compare(rhs) < 0; }
     };
     

code/branches/pickup3/src/orxonox/worldentities/pawns/Pawn.h

@@ -138 +138 @@
             //TODO: Remove.
             //PickupCollection pickups_;
-            virtual const std::list<PickupCarrier*>* getChildren(void)
+            virtual std::list<PickupCarrier*>* getCarrierChildren(void)
                 { return new std::list<PickupCarrier*>(); }
-            virtual PickupCarrier* getParent(void)
+            virtual PickupCarrier* getCarrierParent(void)
                 { return NULL; }
+            virtual const Vector3& getCarrierPosition(void)
+                { return this->getWorldPosition(); };
 
             float health_;