Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Dec 28, 2008, 7:42:30 PM (15 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).

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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.