1 /***********************************************************************
2     created:    7/8/2010
3     author:     Martin Preisler
4 
5     purpose:    Defines the interface for the AnimationManager object
6 *************************************************************************/
7 /***************************************************************************
8  *   Copyright (C) 2004 - 2010 Paul D Turner & The CEGUI Development Team
9  *
10  *   Permission is hereby granted, free of charge, to any person obtaining
11  *   a copy of this software and associated documentation files (the
12  *   "Software"), to deal in the Software without restriction, including
13  *   without limitation the rights to use, copy, modify, merge, publish,
14  *   distribute, sublicense, and/or sell copies of the Software, and to
15  *   permit persons to whom the Software is furnished to do so, subject to
16  *   the following conditions:
17  *
18  *   The above copyright notice and this permission notice shall be
19  *   included in all copies or substantial portions of the Software.
20  *
21  *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22  *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23  *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24  *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
25  *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
26  *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
27  *   OTHER DEALINGS IN THE SOFTWARE.
28  ***************************************************************************/
29 #ifndef _CEGUIAnimationManager_h_
30 #define _CEGUIAnimationManager_h_
31 
32 #include "CEGUI/Singleton.h"
33 #include "CEGUI/String.h"
34 #include <map>
35 #include <vector>
36 
37 #if defined(_MSC_VER)
38 #   pragma warning(push)
39 #   pragma warning(disable : 4251)
40 #endif
41 
42 // Start of CEGUI namespace section
43 namespace CEGUI
44 {
45 
46 class CEGUIEXPORT AnimationManager :
47     public Singleton<AnimationManager>,
48     public AllocatedObject<AnimationManager>
49 {
50 public:
51     //! Name of the schema used for loading animation xml files.
52     static const String XMLSchemaName;
53 
54     /*************************************************************************
55         Construction and Destruction
56     *************************************************************************/
57     /*!
58     \brief
59         Constructs a new AnimationManager object.
60 
61         NB: Client code should not create AnimationManager objects - they are of
62         limited use to you!  The intended pattern of access is to get a pointer
63         to the GUI system's AnimationManager via the System object, and use
64         that.
65     */
66     AnimationManager(void);
67 
68 
69     /*!
70     \brief
71         Destructor for AnimationManager objects
72 
73         This will properly destroy all remaining AnimationInstance and Animation
74         objects.
75     */
76     ~AnimationManager(void);
77 
78     /*!
79     \brief
80         Adds interpolator to be available for Affectors
81 
82     \par
83         CEGUI ships with several basic interpolators that are always available,
84         float, bool, colour, UDim, UVector2, ... but you can add your own
85         custom interpolator if needed! just note that AnimationManager only
86         deletes inbuilt interpolators. It will remove your interpolator if you
87         don't do it yourself, but you definitely have to delete it yourself!
88     */
89     void addInterpolator(Interpolator* interpolator);
90 
91     /*!
92     \brief
93         Removes interpolator
94     */
95     void removeInterpolator(Interpolator* interpolator);
96 
97     /*!
98     \brief
99         Retrieves interpolator by type
100     */
101     Interpolator* getInterpolator(const String& type) const;
102 
103     /*!
104     \brief
105         Creates a new Animation definition
106 
107     \see
108         Animation
109     */
110     Animation* createAnimation(const String& name = "");
111 
112     /*!
113     \brief
114         Destroys given animation definition
115     */
116     void destroyAnimation(Animation* animation);
117 
118     /*!
119     \brief
120         Destroys given animation definition by name
121     */
122     void destroyAnimation(const String& name);
123 
124     /*!
125     \brief
126         Destroys all animations in existence!
127     */
128     void destroyAllAnimations();
129 
130     /*!
131     \brief
132         Retrieves animation by name
133     */
134     Animation* getAnimation(const String& name) const;
135 
136     /*!
137     \brief
138         Examines the list of Animations to see if one exists with the given name
139 
140     \param name
141         String holding the name of the Animation to look for.
142 
143     \return
144         true if an Animation was found with a name matching \a name.  false if
145         no matching Animation was found.
146     */
147     bool isAnimationPresent(const String& name) const;
148 
149     /*!
150     \brief
151         Retrieves animation by index
152     */
153     Animation* getAnimationAtIdx(size_t index) const;
154 
155     /*!
156     \brief
157         Retrieves number of defined animations
158     */
159     size_t getNumAnimations() const;
160 
161     /*!
162     \brief
163         Instantiates given animation
164 
165     \see
166         AnimationInstance
167     */
168     AnimationInstance* instantiateAnimation(Animation* animation);
169 
170     /*!
171     \brief
172         Instantiates given animation by name
173 
174     \see
175         AnimationInstance
176     */
177     AnimationInstance* instantiateAnimation(const String& name);
178 
179     /*!
180     \brief
181         Destroys given animation instance
182     */
183     void destroyAnimationInstance(AnimationInstance* instance);
184 
185     /*!
186     \brief
187         Destroys all instances of given animation
188     */
189     void destroyAllInstancesOfAnimation(Animation* animation);
190 
191     /*!
192     \brief
193         Destroys all instances of all animations
194     */
195     void destroyAllAnimationInstances();
196 
197     /*!
198     \brief
199         Retrieves animation instance at given index
200     */
201     AnimationInstance* getAnimationInstanceAtIdx(size_t index) const;
202 
203     /*!
204     \brief
205         Retrieves number of animation instances, number of times any animation
206         was instantiated.
207     */
208     size_t getNumAnimationInstances() const;
209 
210     /*!
211     \brief
212         Internal method, gets called by CEGUI::System automatically.
213 
214         Only use if you know what you're doing!
215 
216     \par
217     	Steps animation instances with auto stepping enabled forward
218     	by given delta.
219     */
220     void autoStepInstances(float delta);
221 
222     /*!
223     \brief
224         Parses an XML file containing animation specifications to create
225         and initialise Animation objects.
226 
227     \param filename
228         String object holding the filename of the XML file to be processed.
229 
230     \param resourceGroup
231         Resource group identifier to be passed to the resource provider when
232         loading the XML file.
233     */
234     void loadAnimationsFromXML(const String& filename,
235                                const String& resourceGroup = "");
236 
237     /*!
238     \brief
239         Parses XML source containing animation specifications to create
240         and initialise Animation objects.
241 
242     \param source
243         String object holding the XML source to be processed.
244     */
245     void loadAnimationsFromString(const String& source);
246 
247     /*!
248     \brief
249         Writes given animation definition to the given OutStream.
250 
251     \param animation
252         Animation definition to write
253 
254     \param out_stream
255         OutStream (std::ostream based) object where data is to be sent.
256     */
257     void writeAnimationDefinitionToStream(const Animation& animation, OutStream& out_stream) const;
258 
259     /*!
260     \brief
261         Writes given animation definition and returns the result as String
262 
263     \param animation
264         Animation definition to write
265 
266     \warning
267         This is a convenience function and isn't designed to be fast at all! Use the other alternatives
268         if you want performance.
269 
270     \return
271         String containing the resulting XML
272     */
273     String getAnimationDefinitionAsString(const Animation& animation) const;
274 
275     /*!
276     \brief
277         Sets the default resource group to be used when loading animation xml
278         data
279 
280     \param resourceGroup
281         String describing the default resource group identifier to be used.
282     */
setDefaultResourceGroup(const String & resourceGroup)283     static void setDefaultResourceGroup(const String& resourceGroup)
284     {
285         s_defaultResourceGroup = resourceGroup;
286     }
287 
288     /*!
289     \brief
290         Returns the default resource group currently set for loading animation
291         xml data.
292 
293     \return
294         String describing the default resource group identifier that will be
295         used when loading Animation xml data.
296     */
getDefaultResourceGroup()297     static const String& getDefaultResourceGroup()
298     {
299         return s_defaultResourceGroup;
300     }
301 
302 private:
303     typedef std::map<String, Interpolator*, std::less<String>
304         CEGUI_MAP_ALLOC(String, Interpolator*)> InterpolatorMap;
305     String generateUniqueAnimationName();
306 
307     //! stores available interpolators
308     InterpolatorMap d_interpolators;
309     typedef std::vector<Interpolator*
310         CEGUI_VECTOR_ALLOC(Interpolator*)> BasicInterpolatorList;
311     //! stores interpolators that are inbuilt in CEGUI
312     BasicInterpolatorList d_basicInterpolators;
313 
314     typedef std::map<String, Animation*> AnimationMap;
315     //! all defined animations
316     AnimationMap d_animations;
317 
318     typedef std::multimap<Animation*, AnimationInstance*, std::less<Animation*>
319         CEGUI_MULTIMAP_ALLOC(Animation*, AnimationInstance*)> AnimationInstanceMap;
320     //! all instances of animations
321     AnimationInstanceMap d_animationInstances;
322     //! Default resource group used when loading animation xml files.
323     static String s_defaultResourceGroup;
324     //! Base name to use for generated window names.
325     static const String GeneratedAnimationNameBase;
326     //! Counter used to generate unique animation names.
327     unsigned long d_uid_counter;
328 };
329 
330 } // End of  CEGUI namespace section
331 
332 #if defined(_MSC_VER)
333 #   pragma warning(pop)
334 #endif
335 
336 #endif  // end of guard _CEGUIAnimationManager_h_
337 
338