include/IAnimatedMeshSceneNode.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_ANIMATED_MESH_SCENE_NODE_H_INCLUDED__\r
   6 #define __I_ANIMATED_MESH_SCENE_NODE_H_INCLUDED__\r
   7 \r
   8 #include "ISceneNode.h"\r
   9 #include "IBoneSceneNode.h"\r
  10 #include "IAnimatedMeshMD2.h"\r
  11 #include "IAnimatedMeshMD3.h"\r
  12 \r
  13 namespace irr\r
  14 {\r
  15 namespace scene\r
  16 {\r
  17         class IShadowVolumeSceneNode;\r
  18 \r
  19         enum E_JOINT_UPDATE_ON_RENDER\r
  20         {\r
  21                 //! do nothing\r
  22                 EJUOR_NONE = 0,\r
  23 \r
  24                 //! get joints positions from the mesh (for attached nodes, etc)\r
  25                 EJUOR_READ,\r
  26 \r
  27                 //! control joint positions in the mesh (eg. ragdolls, or set the animation from animateJoints() )\r
  28                 EJUOR_CONTROL\r
  29         };\r
  30 \r
  31 \r
  32         class IAnimatedMeshSceneNode;\r
  33 \r
  34         //! Callback interface for catching events of ended animations.\r
  35         /** Implement this interface and use\r
  36         IAnimatedMeshSceneNode::setAnimationEndCallback to be able to\r
  37         be notified if an animation playback has ended.\r
  38         **/\r
  39         class IAnimationEndCallBack : public virtual IReferenceCounted\r
  40         {\r
  41         public:\r
  42 \r
  43                 //! Will be called when the animation playback has ended.\r
  44                 /** See IAnimatedMeshSceneNode::setAnimationEndCallback for\r
  45                 more information.\r
  46                 \param node: Node of which the animation has ended. */\r
  47                 virtual void OnAnimationEnd(IAnimatedMeshSceneNode* node) = 0;\r
  48         };\r
  49 \r
  50         //! Scene node capable of displaying an animated mesh.\r
  51         class IAnimatedMeshSceneNode : public ISceneNode\r
  52         {\r
  53         public:\r
  54 \r
  55                 //! Constructor\r
  56                 IAnimatedMeshSceneNode(ISceneNode* parent, ISceneManager* mgr, s32 id,\r
  57                         const core::vector3df& position = core::vector3df(0,0,0),\r
  58                         const core::vector3df& rotation = core::vector3df(0,0,0),\r
  59                         const core::vector3df& scale = core::vector3df(1.0f, 1.0f, 1.0f))\r
  60                         : ISceneNode(parent, mgr, id, position, rotation, scale) {}\r
  61 \r
  62                 //! Destructor\r
  63                 virtual ~IAnimatedMeshSceneNode() {}\r
  64 \r
  65                 //! Sets the current frame number.\r
  66                 /** From now on the animation is played from this frame.\r
  67                 \param frame: Number of the frame to let the animation be started from.\r
  68                 The frame number must be a valid frame number of the IMesh used by this\r
  69                 scene node. Set IAnimatedMesh::getMesh() for details. */\r
  70                 virtual void setCurrentFrame(f32 frame) = 0;\r
  71 \r
  72                 //! Sets the frame numbers between the animation is looped.\r
  73                 /** The default is 0 to getFrameCount()-1 of the mesh.\r
  74                 Number of played frames is end-start.\r
  75                 It interpolates toward the last frame but stops when it is reached.\r
  76                 It does not interpolate back to start even when looping.\r
  77                 Looping animations should ensure last and first frame-key are identical.\r
  78                 \param begin: Start frame number of the loop.\r
  79                 \param end: End frame number of the loop.\r
  80                 \return True if successful, false if not. */\r
  81                 virtual bool setFrameLoop(s32 begin, s32 end) = 0;\r
  82 \r
  83                 //! Sets the speed with which the animation is played.\r
  84                 /** \param framesPerSecond: Frames per second played. */\r
  85                 virtual void setAnimationSpeed(f32 framesPerSecond) = 0;\r
  86 \r
  87                 //! Gets the speed with which the animation is played.\r
  88                 /** \return Frames per second played. */\r
  89                 virtual f32 getAnimationSpeed() const =0;\r
  90 \r
  91                 /** The shadow can be rendered using the ZPass or the zfail\r
  92                 method. ZPass is a little bit faster because the shadow volume\r
  93                 creation is easier, but with this method there occur ugly\r
  94                 looking artifacts when the camera is inside the shadow volume.\r
  95                 These error do not occur with the ZFail method, but it can \r
  96                 have trouble with clipping to the far-plane (it usually works \r
  97                 well in OpenGL and fails with other drivers).\r
  98                 \param shadowMesh: Optional custom mesh for shadow volume.\r
  99                 \param id: Id of the shadow scene node. This id can be used to\r
 100                 identify the node later.\r
 101                 \param zfailmethod: If set to true, the shadow will use the\r
 102                 zfail method, if not, zpass is used.\r
 103                 \param infinity: Value used by the shadow volume algorithm to\r
 104                 scale the shadow volume. For zfail shadow volumes on some drivers \r
 105                 only suppport finite shadows, so camera zfar must be larger than \r
 106                 shadow back cap,which is depending on the infinity parameter).\r
 107                 Infinity value also scales by the scaling factors of the model.\r
 108                 If shadows don't show up with zfail then try reducing infinity.\r
 109                 If shadows are cut-off then try increasing infinity.\r
 110                 \return Pointer to the created shadow scene node. This pointer\r
 111                 should not be dropped. See IReferenceCounted::drop() for more\r
 112                 information. */\r
 113                 virtual IShadowVolumeSceneNode* addShadowVolumeSceneNode(const IMesh* shadowMesh=0,\r
 114                         s32 id=-1, bool zfailmethod=true, f32 infinity=1000.0f) = 0;\r
 115 \r
 116                 //! Get a pointer to a joint in the mesh (if the mesh is a bone based mesh).\r
 117                 /** With this method it is possible to attach scene nodes to\r
 118                 joints for example possible to attach a weapon to the left hand\r
 119                 of an animated model. This example shows how:\r
 120                 \code\r
 121                 ISceneNode* hand =\r
 122                         yourAnimatedMeshSceneNode->getJointNode("LeftHand");\r
 123                 hand->addChild(weaponSceneNode);\r
 124                 \endcode\r
 125                 Please note that the joint returned by this method may not exist\r
 126                 before this call and the joints in the node were created by it.\r
 127                 \param jointName: Name of the joint.\r
 128                 \return Pointer to the scene node which represents the joint\r
 129                 with the specified name. Returns 0 if the contained mesh is not\r
 130                 an skinned mesh or the name of the joint could not be found. */\r
 131                 virtual IBoneSceneNode* getJointNode(const c8* jointName)=0;\r
 132 \r
 133                 //! same as getJointNode(const c8* jointName), but based on id\r
 134                 virtual IBoneSceneNode* getJointNode(u32 jointID) = 0;\r
 135 \r
 136                 //! Gets joint count.\r
 137                 /** \return Amount of joints in the mesh. */\r
 138                 virtual u32 getJointCount() const = 0;\r
 139 \r
 140                 //! Starts a default MD2 animation.\r
 141                 /** With this method it is easily possible to start a Run,\r
 142                 Attack, Die or whatever animation, if the mesh contained in\r
 143                 this scene node is an md2 mesh. Otherwise, nothing happens.\r
 144                 \param anim: An MD2 animation type, which should be played, for\r
 145                 example EMAT_STAND for the standing animation.\r
 146                 \return True if successful, and false if not, for example if\r
 147                 the mesh in the scene node is not a md2 mesh. */\r
 148                 virtual bool setMD2Animation(EMD2_ANIMATION_TYPE anim) = 0;\r
 149 \r
 150                 //! Starts a special MD2 animation.\r
 151                 /** With this method it is easily possible to start a Run,\r
 152                 Attack, Die or whatever animation, if the mesh contained in\r
 153                 this scene node is an md2 mesh. Otherwise, nothing happens.\r
 154                 This method uses a character string to identify the animation.\r
 155                 If the animation is a standard md2 animation, you might want to\r
 156                 start this animation with the EMD2_ANIMATION_TYPE enumeration\r
 157                 instead.\r
 158                 \param animationName: Name of the animation which should be\r
 159                 played.\r
 160                 \return Returns true if successful, and false if not, for\r
 161                 example if the mesh in the scene node is not an md2 mesh, or no\r
 162                 animation with this name could be found. */\r
 163                 virtual bool setMD2Animation(const c8* animationName) = 0;\r
 164 \r
 165                 //! Returns the currently displayed frame number.\r
 166                 virtual f32 getFrameNr() const = 0;\r
 167                 //! Returns the current start frame number.\r
 168                 virtual s32 getStartFrame() const = 0;\r
 169                 //! Returns the current end frame number.\r
 170                 virtual s32 getEndFrame() const = 0;\r
 171 \r
 172                 //! Sets looping mode which is on by default.\r
 173                 /** If set to false, animations will not be played looped. */\r
 174                 virtual void setLoopMode(bool playAnimationLooped) = 0;\r
 175 \r
 176                 //! returns the current loop mode\r
 177                 /** When true the animations are played looped */\r
 178                 virtual bool getLoopMode() const = 0;\r
 179 \r
 180                 //! Sets a callback interface which will be called if an animation playback has ended.\r
 181                 /** Set this to 0 to disable the callback again.\r
 182                 Please note that this will only be called when in non looped\r
 183                 mode, see IAnimatedMeshSceneNode::setLoopMode(). */\r
 184                 virtual void setAnimationEndCallback(IAnimationEndCallBack* callback=0) = 0;\r
 185 \r
 186                 //! Sets if the scene node should not copy the materials of the mesh but use them in a read only style.\r
 187                 /** In this way it is possible to change the materials a mesh\r
 188                 causing all mesh scene nodes referencing this mesh to change\r
 189                 too. */\r
 190                 virtual void setReadOnlyMaterials(bool readonly) = 0;\r
 191 \r
 192                 //! Returns if the scene node should not copy the materials of the mesh but use them in a read only style\r
 193                 virtual bool isReadOnlyMaterials() const = 0;\r
 194 \r
 195                 //! Sets a new mesh\r
 196                 virtual void setMesh(IAnimatedMesh* mesh) = 0;\r
 197 \r
 198                 //! Returns the current mesh\r
 199                 virtual IAnimatedMesh* getMesh(void) = 0;\r
 200 \r
 201                 //! Get the absolute transformation for a special MD3 Tag if the mesh is a md3 mesh, or the absolutetransformation if it's a normal scenenode\r
 202                 virtual const SMD3QuaternionTag* getMD3TagTransformation( const core::stringc & tagname) = 0;\r
 203 \r
 204                 //! Set how the joints should be updated on render\r
 205                 virtual void setJointMode(E_JOINT_UPDATE_ON_RENDER mode)=0;\r
 206 \r
 207                 //! Sets the transition time in seconds\r
 208                 /** Note: This needs to enable joints, and setJointmode set to\r
 209                 EJUOR_CONTROL. You must call animateJoints(), or the mesh will\r
 210                 not animate. */\r
 211                 virtual void setTransitionTime(f32 Time) =0;\r
 212 \r
 213                 //! animates the joints in the mesh based on the current frame.\r
 214                 /** Also takes in to account transitions. */\r
 215                 virtual void animateJoints(bool CalculateAbsolutePositions=true) = 0;\r
 216 \r
 217                 //! render mesh ignoring its transformation.\r
 218                 /** Culling is unaffected. */\r
 219                 virtual void setRenderFromIdentity( bool On )=0;\r
 220 \r
 221                 //! Creates a clone of this scene node and its children.\r
 222                 /** \param newParent An optional new parent.\r
 223                 \param newManager An optional new scene manager.\r
 224                 \return The newly created clone of this node. */\r
 225                 virtual ISceneNode* clone(ISceneNode* newParent=0, ISceneManager* newManager=0) = 0;\r
 226 \r
 227         };\r
 228 \r
 229 } // end namespace scene\r
 230 } // end namespace irr\r
 231 \r
 232 #endif\r
 233 \r