Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Dec 28, 2008, 7:42:30 PM (16 years ago)
Author:
rgrieder
Message:

Added comments to the WorldEntity except for the non physics section of the header file (going to do that some time later).

Location:
code/branches/presentation/src/orxonox/objects/worldentities
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.cc

    r2535 r2540  
    5252    const Vector3 WorldEntity::UP    = Vector3::UNIT_Y;
    5353
     54    /**
     55    @brief
     56        Creates a new WorldEntity that may immediately be used.
     57        All the default values are being set here.
     58    */
    5459    WorldEntity::WorldEntity(BaseObject* creator) : BaseObject(creator), Synchronisable(creator), collisionShape_(0)
    55 
    5660    {
    5761        RegisterObject(WorldEntity);
    … …  
    9296    }
    9397
     98    /**
     99    @brief
     100        Destroys the WorldEntity AND ALL its children with it.
     101    */
    94102    WorldEntity::~WorldEntity()
    95103    {
    … …  
    172180    }
    173181
     182    /**
     183    @brief
     184        Network function that object this instance to its correct parent.
     185    */
    174186    void WorldEntity::parentChanged()
    175187    {
    … …  
    182194    }
    183195
     196    /**
     197    @brief
     198        Attaches this object to a parent SceneNode.
     199    @Remarks
     200        Only use this method if you know exactly what you're doing!
     201        Normally, attaching works internally by attaching WE's.
     202    */
    184203    void WorldEntity::attachToNode(Ogre::SceneNode* node)
    185204    {
    … …  
    190209    }
    191210
     211    /**
     212    @brief
     213        Detaches this object from a parent SceneNode.
     214    @Remarks
     215        Only use this method if you know exactly what you're doing!
     216        Normally, attaching works internally by attaching WE's.
     217    */
    192218    void WorldEntity::detachFromNode(Ogre::SceneNode* node)
    193219    {
    … …  
    196222    }
    197223
     224    /**
     225    @brief
     226        Network callback for the collision type. Only change the type if it was valid.
     227    */
    198228    void WorldEntity::collisionTypeChanged()
    199229    {
    … …  
    214244    }
    215245
     246    //! Network callback for this->bPhysicsActive_
    216247    void WorldEntity::physicsActivityChanged()
    217248    {
    … …  
    222253    }
    223254
     255    //! Function is called to set the right flags in Bullet (if there is physics at all)
    224256    void WorldEntity::collisionCallbackActivityChanged()
    225257    {
    … …  
    235267    }
    236268
     269    /**
     270    @brief
     271        Attaches a child WorldEntity to this object. This calls notifyBeingAttached()
     272        of the child WE.
     273    @Note
     274        The collision shape of the child object gets attached nevertheless. That also means
     275        that you can change the collision shape of the child and it correctly cascadeds the changes to this instance.
     276        Be aware of this implication: When implementing attaching of kinematic objects to others, you have to change
     277        this behaviour because you then might not want to merge the collision shapes.
     278    */
    237279    void WorldEntity::attach(WorldEntity* object)
    238280    {
    … …  
    255297    }
    256298
     299    /**
     300    @brief
     301        Function gets called when this object is being attached to a new parent.
     302
     303        This operation is only allowed if the collision types "like" each other.
     304        - You cannot a attach a non physical object to a physical one.
     305        - Dynamic object can NOT be attached at all.
     306        - It is also not possible to attach a kinematic to a dynamic one.
     307        - Attaching of kinematic objects otherwise is not yet supported.
     308    */
    257309    bool WorldEntity::notifyBeingAttached(WorldEntity* newParent)
    258310    {
    … …  
    300352    }
    301353
     354    /**
     355    @brief
     356        Detaches a child WorldEntity from this instance.
     357    */
    302358    void WorldEntity::detach(WorldEntity* object)
    303359    {
    … …  
    324380    }
    325381
     382    /**
     383    @brief
     384        Function gets called when the object has been detached from its parent.
     385    */
    326386    void WorldEntity::notifyDetached()
    327387    {
    … …  
    341401    }
    342402
     403    //! Returns an attached object (merely for XMLPort).
    343404    WorldEntity* WorldEntity::getAttachedObject(unsigned int index)
    344405    {
    … …  
    353414    }
    354415
     416    //! Attaches an Ogre::SceneNode to this WorldEntity.
    355417    void WorldEntity::attachNode(Ogre::SceneNode* node)
    356418    {
    … …  
    361423    }
    362424
     425    //! Detaches an Ogre::SceneNode from this WorldEntity.
    363426    void WorldEntity::detachNode(Ogre::SceneNode* node)
    364427    {
    … …  
    367430    }
    368431
     432    //! Attaches an Ogre::MovableObject to this WorldEntity.
    369433    void WorldEntity::attachOgreObject(Ogre::MovableObject* object)
    370434    {
    … …  
    372436    }
    373437
     438    //! Detaches an Ogre::MovableObject from this WorldEntity.
    374439    void WorldEntity::detachOgreObject(Ogre::MovableObject* object)
    375440    {
    … …  
    377442    }
    378443
     444    //! Detaches an Ogre::MovableObject (by string) from this WorldEntity.
    379445    Ogre::MovableObject* WorldEntity::detachOgreObject(const Ogre::String& name)
    380446    {
    … …  
    382448    }
    383449
     450    //! Attaches a collision Shape to this object (delegated to the internal CompoundCollisionShape)
    384451    void WorldEntity::attachCollisionShape(CollisionShape* shape)
    385452    {
    … …  
    388455    }
    389456
     457    //! Detaches a collision Shape from this object (delegated to the internal CompoundCollisionShape)
    390458    void WorldEntity::detachCollisionShape(CollisionShape* shape)
    391459    {
    … …  
    394462    }
    395463
    396     CollisionShape* WorldEntity::getAttachedCollisionShape(unsigned int index) const
     464    //! Returns an attached collision Shape of this object (delegated to the internal CompoundCollisionShape)
     465    CollisionShape* WorldEntity::getAttachedCollisionShape(unsigned int index)
    397466    {
    398467        return this->collisionShape_.getAttachedShape(index);
    … …  
    417486#endif
    418487
     488    //! Returns the position relative to the root space
    419489    const Vector3& WorldEntity::getWorldPosition() const
    420490    {
    … …  
    422492    }
    423493
     494    //! Returns the orientation relative to the root space
    424495    const Quaternion& WorldEntity::getWorldOrientation() const
    425496    {
    … …  
    427498    }
    428499
     500    //! Returns the scaling applied relative to the root space in 3 coordinates
    429501    const Vector3& WorldEntity::getWorldScale3D() const
    430502    {
    … …  
    432504    }
    433505
     506    /**
     507    @brief
     508        Returns the scaling applied relative to the root space in 3 coordinates
     509    @return
     510        Returns the scaling if it is uniform, 1.0f otherwise.
     511    */
    434512    float WorldEntity::getWorldScale() const
    435513    {
    … …  
    438516    }
    439517
     518    /**
     519    @brief
     520        Sets the three dimensional scaling of this object.
     521    @Note
     522        Scaling physical objects has not yet been implemented and is therefore forbidden.
     523    */
    440524    void WorldEntity::setScale3D(const Vector3& scale)
    441525    {
    … …  
    454538    }
    455539
     540    /**
     541    @brief
     542        Translates this WorldEntity by a vector.
     543    @param relativeTo
     544        @see TransformSpace::Enum
     545    */
    456546    void WorldEntity::translate(const Vector3& distance, TransformSpace::Enum relativeTo)
    457547    {
    … …  
    476566    }
    477567
    478     void WorldEntity::rotate(const Quaternion& rotation, TransformSpace::Space relativeTo)
     568    /**
     569    @brief
     570        Rotates this WorldEntity by a quaternion.
     571    @param relativeTo
     572        @see TransformSpace::Enum
     573    */
    479574    void WorldEntity::rotate(const Quaternion& rotation, TransformSpace::Enum relativeTo)
    480575    {
    … …  
    496591    }
    497592
    498     void WorldEntity::lookAt(const Vector3& target, TransformSpace::Space relativeTo, const Vector3& localDirectionVector)
     593    /**
     594    @brief
     595        Makes this WorldEntity look a specific target location.
     596    @param relativeTo
     597        @see TransformSpace::Enum
     598    @param localDirectionVector
     599        The vector which normally describes the natural direction of the object, usually -Z.
     600    */
    499601    void WorldEntity::lookAt(const Vector3& target, TransformSpace::Enum relativeTo, const Vector3& localDirectionVector)
    500602    {
    … …  
    515617    }
    516618
    517     void WorldEntity::setDirection(const Vector3& direction, TransformSpace::Space relativeTo, const Vector3& localDirectionVector)
     619    /**
     620    @brief
     621        Makes this WorldEntity look in specific direction.
     622    @param relativeTo
     623        @see TransformSpace::Enum
     624    @param localDirectionVector
     625        The vector which normally describes the natural direction of the object, usually -Z.
     626    */
    518627    void WorldEntity::setDirection(const Vector3& direction, TransformSpace::Enum relativeTo, const Vector3& localDirectionVector)
    519628    {
    … …  
    535644    }
    536645
     646    //! Activates physics if the CollisionType is not None.
    537647    void WorldEntity::activatePhysics()
    538648    {
    … …  
    544654    }
    545655
     656    //! Deactivates physics but the CollisionType does not change.
    546657    void WorldEntity::deactivatePhysics()
    547658    {
    … …  
    553664    }
    554665
     666    //! Tells whether the object has already been added to the Bullet physics World.
    555667    bool WorldEntity::addedToPhysicalWorld() const
    556668    {
    … …  
    558670    }
    559671
     672    /**
     673    @brief
     674        Sets the CollisionType. This alters the object significantly! @see CollisionType.
     675    @Note
     676        Operation does not work on attached WorldEntities.
     677    */
    560678    void WorldEntity::setCollisionType(CollisionType type)
    561679    {
    … …  
    647765    }
    648766
     767    //! Sets the CollisionType by string (used for the XMLPort)
    649768    void WorldEntity::setCollisionTypeStr(const std::string& typeStr)
    650769    {
    … …  
    664783    }
    665784
     785    //! Gets the CollisionType by string (used for the XMLPort)
    666786    std::string WorldEntity::getCollisionTypeStr() const
    667787    {
    … …  
    695815    }
    696816
     817    /**
     818    @brief
     819        Recalculates the accumulated child mass and calls recalculateMassProps()
     820        and notifies the parent of the change.
     821    @Note
     822        Called by a child WE
     823    */
    697824    void WorldEntity::notifyChildMassChanged()
    698825    {
    … …  
    708835    }
    709836
     837    /**
     838    @brief
     839        Undertakes the necessary steps to change the collision shape in Bullet, even at runtime.
     840    @Note
     841        - called by this->collisionShape_
     842        - May have a REALLY big overhead when called continuously at runtime, because then we need
     843          to remove the physical body from Bullet and add it again.
     844    */
    710845    void WorldEntity::notifyCollisionShapeChanged()
    711846    {
    … …  
    725860    }
    726861
     862    //! Updates all mass dependent parameters (mass, inertia tensor and child mass)
    727863    void WorldEntity::recalculateMassProps()
    728864    {
    … …  
    740876            {
    741877                // Use default values to avoid very large or very small values
    742                 CCOUT(4) << "Warning: Setting the internal physical mass to 1.0 because mass_ is 0.0." << std::endl;
     878                CCOUT(4) << "Warning: Setting the internal physical mass to 1.0 because mass_ is 0.0" << std::endl;
    743879                btVector3 inertia(0, 0, 0);
    744880                this->collisionShape_.calculateLocalInertia(1.0f, inertia);
    … …  
    752888    }
    753889
     890    //! Copies our own parameters for restitution, angular factor, dampings and friction to the bullet rigid body.
    754891    void WorldEntity::internalSetPhysicsProps()
    755892    {

  • code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.h

    r2535 r2540  
    4747namespace orxonox
    4848{
     49    /**
     50    @brief
     51        The WorldEntity represents everything that can be put in a Scene at a certain location.
     52
     53        It is supposed to be the base class of everything you would call an 'object' in a Scene.
     54        The class itself is abstract which means you cannot use it directly. You may use StaticEntity
     55        as the simplest derivative or (derived from MobileEntity) MovableEntity and ControllableEntity
     56        as more advanced ones.
     57
     58        The basic task of the WorldEntity is provide a location, a direction and a scaling and the possibility
     59        to create an entire hierarchy of derivated objects.
     60        It is also the basis for the physics interface to the Bullet physics engine.
     61        Every WorldEntity can have a specific collision type: @see CollisionType
     62        This would then imply that every scene object could have any collision type. To limit this, you can always
     63        override this->isCollisionTypeLegal(CollisionType). Return false if the collision type is not supported
     64        for a specific object.
     65        There is also support for attaching WorldEntities with physics to each other. Currently, the collision shape
     66        of both objects simply get merged into one larger shape (for static collision type).
     67        The phyiscal body that is internally stored and administrated has the following supported properties:
     68        - Restitution, angular factor, linear damping, angular damping, fricition, mass and collision shape.
     69        You can get more information at the corresponding set function.
     70
     71        Collision shapes: These are controlled by the internal CompoundCollisionShape. @see CompoundCollisionShape.
     72    */
    4973    class _OrxonoxExport WorldEntity : public BaseObject, public Synchronisable, public btMotionState
    5074    {
    … …  
    182206
    183207        public:
     208            /**
     209            @brief
     210                Denotes the possible types of physical objects in a Scene.
     211
     212                Dynamic:   The object is influenced by its physical environment, like for instance little ball.
     213                Kinematic: The object can only influence other dynamic objects. It's movement is coordinated by your own saying.
     214                Static:    Like kinematic but the object is not allowed to move during the simulation.
     215                None:      The object has no physics at all.
     216            */
    184217            enum CollisionType
    185218            {
    … …  
    190223            };
    191224
     225            //! Tells whether the object has any connection to the Bullet physics engine. If hasPhysics() is false, the object may still have a velocity.
    192226            bool hasPhysics()       const { return getCollisionType() != None     ; }
     227            //! @see CollisionType
    193228            bool isStatic()         const { return getCollisionType() == Static   ; }
     229            //! @see CollisionType
    194230            bool isKinematic()      const { return getCollisionType() == Kinematic; }
     231            //! @see CollisionType
    195232            bool isDynamic()        const { return getCollisionType() == Dynamic  ; }
     233            //! Tells whether physics has been activated (you can temporarily deactivate it)
    196234            bool isPhysicsActive()  const { return this->bPhysicsActive_; }
    197235            bool addedToPhysicalWorld() const;
    … …  
    200238            void deactivatePhysics();
    201239
     240            //! Returns the CollisionType. @see CollisionType.
    202241            inline CollisionType getCollisionType() const
    203242                { return this->collisionType_; }
    … …  
    207246            std::string getCollisionTypeStr() const;
    208247
     248            //! Sets the mass of this object. Note that the total mass may be influenced by attached objects!
    209249            inline void setMass(float mass)
    210250                { this->mass_ = mass; recalculateMassProps(); }
     251            //! Returns the mass of this object without its children.
    211252            inline float getMass() const
    212253                { return this->mass_; }
    213254
     255            //! Returns the total mass of this object with all its attached children.
    214256            inline float getTotalMass() const
    215257                { return this->mass_ + this->childrenMass_; }
    216258
     259            /**
     260            @brief
     261                Returns the diagonal elements of the inertia tensor when calculated in local coordinates.
     262            @Note
     263                The local inertia tensor cannot be set, but is calculated by Bullet according to the collisionShape.
     264                With compound collision shapes, an approximation is used.
     265            */
    217266            inline const btVector3& getLocalInertia() const
    218267                { return this->localInertia_; }
    219268
     269            /**
     270            @brief
     271                Sets how much reaction is applied in a collision.
     272               
     273                Consider two equal spheres colliding with equal velocities:
     274                Restitution 1 means that both spheres simply reverse their velocity (no loss of energy)
     275                Restitution 0 means that both spheres will immediately stop moving
     276                (maximum loss of energy without violating of the preservation of momentum)
     277            */
    220278            inline void setRestitution(float restitution)
    221279                { this->restitution_ = restitution; internalSetPhysicsProps(); }
     280            //! Returns the restitution parameter. @see setRestitution.
    222281            inline float getRestitution() const
    223282                { return this->restitution_; }
    224283
     284            /**
     285            @brief
     286                Sets an artificial parameter that tells how much torque is applied when you apply a non-central force.
     287
     288                Normally the angular factor is 1, which means it's physically 'correct'. Howerver if you have a player
     289                character that should not rotate when hit sideways, you can set the angular factor to 0.
     290            */
    225291            inline void setAngularFactor(float angularFactor)
    226292                { this->angularFactor_ = angularFactor; internalSetPhysicsProps(); }
     293            //! Returns the angular factor. @see setAngularFactor.
    227294            inline float getAngularFactor() const
    228295                { return this->angularFactor_; }
    229296
     297            //! Applies a mass independent damping. Velocities will simply diminish exponentially.
    230298            inline void setLinearDamping(float linearDamping)
    231299                { this->linearDamping_ = linearDamping; internalSetPhysicsProps(); }
     300            //! Returns the linear damping. @see setLinearDamping.
    232301            inline float getLinearDamping() const
    233302                { return this->linearDamping_; }
    234303
     304            //! Applies a tensor independent rotation damping. Angular velocities will simply diminish exponentially.
    235305            inline void setAngularDamping(float angularDamping)
    236306                { this->angularDamping_ = angularDamping; internalSetPhysicsProps(); }
     307            //! Returns the angular damping. @see setAngularDamping.
    237308            inline float getAngularDamping() const
    238309                { return this->angularDamping_; }
    239310
     311            //! Applies friction to the object. Friction occurs when two objects collide.
    240312            inline void setFriction(float friction)
    241313                { this->friction_ = friction; internalSetPhysicsProps(); }
     314            //! Returns the amount of friction applied to the object.
    242315            inline float getFriction() const
    243316                { return this->friction_; }
    … …  
    250323            void notifyChildMassChanged();
    251324
     325            /**
     326            @brief
     327                Virtual function that gets called when this object collides with another.
     328            @param otherObject
     329                The object this one has collided into.
     330            @pram contactPoint
     331                Contact point provided by Bullet. Holds more information and can me modified. See return value.
     332            @Return
     333                Returning false means that no modification to the contactPoint has been made. Return true otherwise!
     334            @Note
     335                Condition is that enableCollisionCallback() was called.
     336            */
    252337            virtual inline bool collidesAgainst(WorldEntity* otherObject, btManifoldPoint& contactPoint)
    253338                { return false; } /* With false, Bullet assumes no modification to the collision objects. */
    254339
     340            //! Enables the collidesAgainst(.) function. The object doesn't respond to collision otherwise!
    255341            inline void enableCollisionCallback()
    256342                { this->bCollisionCallbackActive_ = true; this->collisionCallbackActivityChanged(); }
     343            //! Disables the collidesAgainst(.) function. @see enableCollisionCallback()
    257344            inline void disableCollisionCallback()
    258345                { this->bCollisionCallbackActive_ = false; this->collisionCallbackActivityChanged(); }
     346            //! Tells whether there could be a collision response via collidesAgainst(.)
    259347            inline bool isCollisionCallbackActive() const
    260348                { return this->bCollisionCallbackActive_; }
    261349
    262350        protected:
     351            /**
     352            @brief
     353                Function checks whether the requested collision type is legal to this object.
     354
     355                You can override this function in a derived class to constrain the collision to e.g. None or Dynamic.
     356                A projectile may not prove very useful if there is no physical body. Simply set the CollisionType
     357                in its constructor and override this method. But be careful that a derived classe's virtual functions
     358                don't yet exist in the constructor if a base class.
     359            */
    263360            virtual bool isCollisionTypeLegal(CollisionType type) const = 0;
    264361
    265             btRigidBody* physicalBody_;
     362            btRigidBody*  physicalBody_; //!< Bullet rigid body. Everything physical is applied to this instance.
    266363
    267364        private:
    … …  
    277374            void physicsActivityChanged();
    278375            void collisionCallbackActivityChanged();
     376            //! Network callback workaround to call a function when the value changes.
    279377            inline void massChanged()
    280378                { this->setMass(this->mass_); }
     379            //! Network callback workaround to call a function when the value changes.
    281380            inline void restitutionChanged()
    282381                { this->setRestitution(this->restitution_); }
     382            //! Network callback workaround to call a function when the value changes.
    283383            inline void angularFactorChanged()
    284384                { this->setAngularFactor(this->angularFactor_); }
     385            //! Network callback workaround to call a function when the value changes.
    285386            inline void linearDampingChanged()
    286387                { this->setLinearDamping(this->linearDamping_); }
     388            //! Network callback workaround to call a function when the value changes.
    287389            inline void angularDampingChanged()
    288390                { this->setAngularDamping(this->angularDamping_); }
     391            //! Network callback workaround to call a function when the value changes.
    289392            inline void frictionChanged()
    290393                { this->setFriction(this->friction_); }
    291394
    292             CollisionType                collisionType_;
    293             CollisionType                collisionTypeSynchronised_;
    294             bool                         bPhysicsActive_;
    295             bool                         bPhysicsActiveSynchronised_;
     395            CollisionType                collisionType_;                 //!< @see setCollisionType
     396            CollisionType                collisionTypeSynchronised_;     //!< Network synchronised variable for collisionType_
     397            bool                         bPhysicsActive_;                //!< @see isPhysicsActive
     398            bool                         bPhysicsActiveSynchronised_;    //!< Network synchronised variable for bPhysicsActive_
     399            //! When attaching objects hierarchically this variable tells this object (as child) whether physics was activated before attaching (because the deactivate physics while being attached).
    296400            bool                         bPhysicsActiveBeforeAttaching_;
    297             CompoundCollisionShape       collisionShape_;
    298             btScalar                     mass_;
    299             btVector3                    localInertia_;
    300             btScalar                     restitution_;
    301             btScalar                     angularFactor_;
    302             btScalar                     linearDamping_;
    303             btScalar                     angularDamping_;
    304             btScalar                     friction_;
    305             btScalar                     childrenMass_;
    306             bool                         bCollisionCallbackActive_;
     401            CompoundCollisionShape       collisionShape_;                //!< Attached collision shapes go here
     402            btScalar                     mass_;                          //!< @see setMass
     403            btVector3                    localInertia_;                  //!< @see getLocalInertia
     404            btScalar                     restitution_;                   //!< @see setRestitution
     405            btScalar                     angularFactor_;                 //!< @see setAngularFactor
     406            btScalar                     linearDamping_;                 //!< @see setLinearDamping
     407            btScalar                     angularDamping_;                //!< @see setAngularDamping
     408            btScalar                     friction_;                      //!< @see setFriction
     409            btScalar                     childrenMass_;                  //!< Sum of all the children's masses
     410            bool                         bCollisionCallbackActive_;      //!< @see enableCollisionCallback
    307411    };
    308412
Note: See TracChangeset for help on using the changeset viewer.