include/ISceneNodeAnimatorCollisionResponse.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_SCENE_NODE_ANIMATOR_COLLISION_RESPONSE_H_INCLUDED__\r
   6 #define __I_SCENE_NODE_ANIMATOR_COLLISION_RESPONSE_H_INCLUDED__\r
   7 \r
   8 #include "ISceneNode.h"\r
   9 \r
  10 namespace irr\r
  11 {\r
  12 namespace scene\r
  13 {\r
  14 \r
  15         class ISceneNodeAnimatorCollisionResponse;\r
  16 \r
  17         //! Callback interface for catching events of collisions.\r
  18         /** Implement this interface and use\r
  19         ISceneNodeAnimatorCollisionResponse::setCollisionCallback to be able to\r
  20         be notified if a collision has occurred.\r
  21         **/\r
  22         class ICollisionCallback : public virtual IReferenceCounted\r
  23         {\r
  24         public:\r
  25 \r
  26                 //! Will be called when a collision occurs.\r
  27                 /** See ISceneNodeAnimatorCollisionResponse::setCollisionCallback for more information.\r
  28                 \param animator: Collision response animator in which the collision occurred. You can call\r
  29                 this animator's methods to find the node, collisionPoint and/or collision triangle.\r
  30                 \retval true if the collision was handled in the animator. The animator's target\r
  31                 node will *not* be stopped at the collision point, but will instead move fully\r
  32                 to the location that triggered the collision check.\r
  33                 \retval false if the collision was not handled in the animator. The animator's\r
  34                 target node will be moved to the collision position.\r
  35                 */\r
  36                 virtual bool onCollision(const ISceneNodeAnimatorCollisionResponse& animator) = 0;\r
  37         };\r
  38 \r
  39         //! Special scene node animator for doing automatic collision detection and response.\r
  40         /** This scene node animator can be attached to any single scene node\r
  41         and will then prevent it from moving through specified collision geometry\r
  42         (e.g. walls and floors of the) world, as well as having it fall under gravity.\r
  43         This animator provides a simple implementation of first person shooter cameras.\r
  44         Attach it to a camera, and the camera will behave as the player control in a\r
  45         first person shooter game: The camera stops and slides at walls, walks up stairs,\r
  46         falls down if there is no floor under it, and so on.\r
  47 \r
  48         The animator will treat any change in the position of its target scene\r
  49         node as movement, including a setPosition(), as movement.  If you want to\r
  50         teleport the target scene node manually to a location without it being effected\r
  51         by collision geometry, then call setTargetNode(node) after calling node->setPosition().\r
  52         */\r
  53         class ISceneNodeAnimatorCollisionResponse : public ISceneNodeAnimator\r
  54         {\r
  55         public:\r
  56 \r
  57                 //! Destructor\r
  58                 virtual ~ISceneNodeAnimatorCollisionResponse() {}\r
  59 \r
  60                 //! Check if the attached scene node is falling.\r
  61                 /** Falling means that there is no blocking wall from the scene\r
  62                 node in the direction of the gravity. The implementation of\r
  63                 this method is very fast, no collision detection is done when\r
  64                 invoking it.\r
  65                 \return True if the scene node is falling, false if not. */\r
  66                 virtual bool isFalling() const = 0;\r
  67 \r
  68                 //! Sets the radius of the ellipsoid for collision detection and response.\r
  69                 /** If you have a scene node, and you are unsure about how big\r
  70                 the radius should be, you could use the following code to\r
  71                 determine it:\r
  72                 \code\r
  73                 core::aabbox<f32> box = yourSceneNode->getBoundingBox();\r
  74                 core::vector3df radius = box.MaxEdge - box.getCenter();\r
  75                 \endcode\r
  76                 \param radius: New radius of the ellipsoid. */\r
  77                 virtual void setEllipsoidRadius(const core::vector3df& radius) = 0;\r
  78 \r
  79                 //! Returns the radius of the ellipsoid for collision detection and response.\r
  80                 /** \return Radius of the ellipsoid. */\r
  81                 virtual core::vector3df getEllipsoidRadius() const = 0;\r
  82 \r
  83                 //! Sets the gravity of the environment.\r
  84                 /** A good example value would be core::vector3df(0,-100.0f,0)\r
  85                 for letting gravity affect all object to fall down. For bigger\r
  86                 gravity, make increase the length of the vector. You can\r
  87                 disable gravity by setting it to core::vector3df(0,0,0);\r
  88                 \param gravity: New gravity vector. */\r
  89                 virtual void setGravity(const core::vector3df& gravity) = 0;\r
  90 \r
  91                 //! Get current vector of gravity.\r
  92                 //! \return Gravity vector. */\r
  93                 virtual core::vector3df getGravity() const = 0;\r
  94 \r
  95                 //! 'Jump' the animator, by adding a jump speed opposite to its gravity\r
  96                 /** \param jumpSpeed The initial speed of the jump; the velocity will be opposite\r
  97                 to this animator's gravity vector. */\r
  98                 virtual void jump(f32 jumpSpeed) = 0;\r
  99 \r
 100                 //! Should the Target react on collision ( default = true )\r
 101                 virtual void setAnimateTarget ( bool enable ) = 0;\r
 102                 virtual bool getAnimateTarget () const = 0;\r
 103 \r
 104                 //! Set translation of the collision ellipsoid.\r
 105                 /** By default, the ellipsoid for collision detection is\r
 106                 created around the center of the scene node, which means that\r
 107                 the ellipsoid surrounds it completely. If this is not what you\r
 108                 want, you may specify a translation for the ellipsoid.\r
 109                 \param translation: Translation of the ellipsoid relative\r
 110                 to the position of the scene node. */\r
 111                 virtual void setEllipsoidTranslation(const core::vector3df &translation) = 0;\r
 112 \r
 113                 //! Get the translation of the ellipsoid for collision detection.\r
 114                 /** See\r
 115                 ISceneNodeAnimatorCollisionResponse::setEllipsoidTranslation()\r
 116                 for more details.\r
 117                 \return Translation of the ellipsoid relative to the position\r
 118                 of the scene node. */\r
 119                 virtual core::vector3df getEllipsoidTranslation() const = 0;\r
 120 \r
 121                 //! Sets a triangle selector holding all triangles of the world with which the scene node may collide.\r
 122                 /** \param newWorld: New triangle selector containing triangles\r
 123                 to let the scene node collide with. */\r
 124                 virtual void setWorld(ITriangleSelector* newWorld) = 0;\r
 125 \r
 126                 //! Get the current triangle selector containing all triangles for collision detection.\r
 127                 virtual ITriangleSelector* getWorld() const = 0;\r
 128 \r
 129                 //! Set the single node that this animator will act on.\r
 130                 /** \param node The new target node. Setting this will force the animator to update\r
 131                                         its last target position for the node, allowing setPosition() to teleport\r
 132                                         the node through collision geometry. */\r
 133                 virtual void setTargetNode(ISceneNode * node) = 0;\r
 134 \r
 135                 //! Gets the single node that this animator is acting on.\r
 136                 /** \return The node that this animator is acting on. */\r
 137                 virtual ISceneNode* getTargetNode(void) const = 0;\r
 138 \r
 139                 //! Returns true if a collision occurred during the last animateNode()\r
 140                 virtual bool collisionOccurred() const = 0;\r
 141 \r
 142                 //! Returns the last point of collision.\r
 143                 virtual const core::vector3df & getCollisionPoint() const = 0;\r
 144 \r
 145                 //! Returns the last triangle that caused a collision\r
 146                 virtual const core::triangle3df & getCollisionTriangle() const = 0;\r
 147 \r
 148                 //! Returns the position that the target node will be moved to, unless the collision is consumed in a callback.\r
 149                 /**\r
 150                 If you have a collision callback registered, and it consumes the collision, then the\r
 151                 node will ignore the collision and will not stop at this position. Instead, it will\r
 152                 move fully to the position that caused the collision to occur. */\r
 153                 virtual const core::vector3df & getCollisionResultPosition(void) const = 0;\r
 154 \r
 155                 //! Returns the node that was collided with.\r
 156                 virtual ISceneNode* getCollisionNode(void) const = 0;\r
 157 \r
 158                 //! Sets a callback interface which will be called if a collision occurs.\r
 159                 /** \param callback: collision callback handler that will be called when a collision\r
 160                 occurs. Set this to 0 to disable the callback.\r
 161                 */\r
 162                 virtual void setCollisionCallback(ICollisionCallback* callback) = 0;\r
 163 \r
 164         };\r
 165 \r
 166 \r
 167 } // end namespace scene\r
 168 } // end namespace irr\r
 169 \r
 170 #endif\r
 171 \r