Debian Codegraph @

engine/core/audio/soundclipmanager.h

raw
1 /***************************************************************************
2 * Copyright (C) 2005-2019 by the FIFE team *
3 * http://www.fifengine.net *
4 * This file is part of FIFE. *
5 * *
6 * FIFE is free software; you can redistribute it and/or *
7 * modify it under the terms of the GNU Lesser General Public *
8 * License as published by the Free Software Foundation; either *
9 * version 2.1 of the License, or (at your option) any later version. *
10 * *
11 * This library is distributed in the hope that it will be useful, *
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the *
18 * Free Software Foundation, Inc., *
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *
20 ***************************************************************************/
21
22 #ifndef FIFE_SOUNDCLIP_MANAGER_H
23 #define FIFE_SOUNDCLIP_MANAGER_H
24
25 // Standard C++ library includes
26 #include <map>
27 #include <string>
28 #include <vector>
29
30 // 3rd party library includes
31
32 // FIFE includes
33 // These includes are split up in two parts, separated by one empty line
34 // First block: files included from the FIFE root src directory
35 // Second block: files included from the same folder
36 #include "util/base/singleton.h"
37 #include "util/resource/resource.h"
38 #include "util/resource/resourcemanager.h"
39
40 #include "soundclip.h"
41
42 namespace FIFE {
43
44 /** SoundClipManager
45 *
46 * An interface for managing images.
47 *
48 * @see IResource
49 * @see IResourceLoader
50 * @see IResourceManager
51 *
52 */
53
54 class SoundClipManager : public IResourceManager, public DynamicSingleton<SoundClipManager> {
55 public:
56
57 /** Default constructor.
58 */
59 SoundClipManager() : IResourceManager() { }
60
61 /** Destructor.
62 */
63 virtual ~SoundClipManager();
64
65 virtual size_t getMemoryUsed() const;
66 virtual size_t getTotalResourcesCreated() const;
67 virtual size_t getTotalResourcesLoaded() const;
68 virtual size_t getTotalResources() const;
69
70 /** Creates a blank SoundClip but does not load it immediately
71 *
72 * @param loader A pointer to the custom resource loader. The
73 * default is NULL. If this parameter is present the resource
74 * will use the loader to load instead of the default built in
75 * functions.
76 * @return A SoundClipPtr to the newly created SoundClip
77 *
78 * @see SoundClip
79 * @see OggLoader
80 * @see IResourceLoader
81 *
82 */
83 virtual SoundClipPtr create(IResourceLoader* loader = 0);
84
85 /** Creates a blank SoundClip but does not load it immediately
86 *
87 * @param name The resource name. Typically a filename.
88 * @param loader A pointer to the custom resource loader. The
89 * default is NULL. If this parameter is present the resource
90 * will use the loader to load instead of the default built in
91 * functions.
92 * @return A SoundClipPtr to the newly created SoundClip
93 *
94 * @see SoundClip
95 * @see OggLoader
96 * @see IResourceLoader
97 *
98 */
99 virtual SoundClipPtr create(const std::string& name, IResourceLoader* loader = 0);
100
101 /** Creates a blank resource and loads it from disk
102 *
103 * This function will create the SoundClip if necessary and load
104 * the clip from disk. If the SoundClip is not defined it
105 * will call SoundClipManager::create() before loading.
106 *
107 * @param name The resource name. Typically a filename.
108 * @param loader A pointer to the custom resource loader. The
109 * default is NULL. If this parameter is present the resource
110 * will use the loader to load instead of the default built in
111 * functions.
112 * @return A SoundClipPtr to the loaded SoundClip
113 *
114 * @see SoundClip
115 * @see OggLoader
116 * @see IResourceLoader
117 *
118 */
119 virtual SoundClipPtr load(const std::string& name, IResourceLoader* loader = 0);
120
121 /** Add an Image to the manager
122 *
123 * This function will create a SoundClipPtr and add the SoundClip
124 * to the manager. The manager assumes ownership of the SoundClip
125 * so DO NOT delete it.
126 *
127 * @param res A pointer to the SoundClip
128 * @return A SoundClipPtr to the added resource
129 *
130 * @see SoundClip
131 *
132 */
133 virtual SoundClipPtr add(SoundClip* res);
134
135 /** Checks to see if a SoundClip exists
136 *
137 * This function will search the manager for SoundClips
138 * that match the parameter
139 *
140 * @param name The name of the SoundClip
141 * @return True if the SoundClip exists. False otherwise.
142 *
143 */
144 virtual bool exists(const std::string& name);
145
146 /** Checks to see if a SoundClip exists
147 *
148 * This function will search the manager for SoundClips
149 * that match the parameter
150 *
151 * @param handle The handle of the SoundClip
152 * @return True if the SoundClip exists. False otherwise.
153 *
154 */
155 virtual bool exists(ResourceHandle handle);
156
157 /** Reloads a SoundClip
158 *
159 * This function will reload a SoundClip if it is managed
160 * by the manager. If not it creates an entry in the log
161 * specifying that the SoundClip could not be found. It will
162 * load the SoundClip if it is not already loaded.
163 *
164 * @param name The name of the resource
165 *
166 */
167 virtual void reload(const std::string& name);
168
169 /** Reloads a resource
170 *
171 * This function will reload a SoundClip if it is managed
172 * by the manager. If not it creates an entry in the log
173 * specifying that the SoundClip could not be found. It will
174 * load the SoundClip if it is not already loaded.
175 *
176 * @param handle The handle of the resource
177 *
178 */
179 virtual void reload(ResourceHandle handle);
180
181 /** Reloads all SoundClips
182 *
183 * This function will reload all SoundClips managed by the
184 * manager. It will load a SoundClip if it is not already loaded.
185 *
186 * @todo It might be beneficial to supply a parameter to
187 * only reload resources that are already loaded
188 *
189 */
190 virtual void reloadAll();
191
192 /** Loads all unreferenced SoundClips
193 *
194 * All SoundClips that have no external references will be
195 * loaded into memory.
196 *
197 */
198 virtual void loadUnreferenced();
199
200 /** Frees a SoundClip from memory
201 *
202 * The SoundClip is not deleted but it's data is freed.
203 * This calls the SoundClip::free() function and it is
204 * up to the resource to properly free it's memory. The
205 * manager keeps a reference to the SoundClip in case
206 * its required in the future.
207 *
208 * @param name The name of the SoundClip
209 *
210 * @see SoundClip
211 *
212 */
213 virtual void free(const std::string& name);
214
215 /** Frees a SoundClip from memory
216 *
217 * The SoundClip is not deleted but it's data is freed.
218 * This calls the SoundClip::free() function and it is
219 * up to the resource to properly free it's memory. The
220 * manager keeps a reference to the SoundClip in case
221 * its required in the future.
222 *
223 * @param handle The handle of the SoundClip
224 *
225 * @see SoundClip
226 *
227 */
228 virtual void free(ResourceHandle handle);
229
230 /** Frees all SoundClips
231 *
232 * This calls the SoundClip::free() function for every
233 * Image the manager is managing. It does not remove
234 * them from the manager.
235 *
236 * @see SoundClip
237 *
238 */
239 virtual void freeAll();
240
241 /** Frees all unreferenced SoundClip
242 *
243 * This calls the SoundClip::free() function for SoundClips
244 * that have no external references to them. It does not
245 * remove them from the manager.
246 *
247 * @see SoundClip
248 *
249 */
250 virtual void freeUnreferenced();
251
252 /** Removes a SoundClip from the manager
253 *
254 * This removes all references to the SoundClip from the
255 * manager. It does not however guarantee that the resource's
256 * destructor is called. If the client has any left over
257 * references to the resource it will not be freed.
258 *
259 * @param resource A SoundClipPtr to the image to be removed
260 * from the manager
261 *
262 * @note This is useful if you want to remove ownership of a resource
263 * from the manager
264 *
265 * @see SoundClip
266 *
267 */
268 virtual void remove(SoundClipPtr& resource);
269
270 /** Removes a SoundClip from the manager
271 *
272 * This removes all references to the SoundClip from the
273 * manager. It does not however guarantee that the resource's
274 * destructor is called. If the client has any left over
275 * references to the resource it will not be freed.
276 *
277 * @param name The name of the SoundClip
278 *
279 * @see SoundClip
280 *
281 */
282 virtual void remove(const std::string& name);
283
284 /** Removes a SoundClip from the manager
285 *
286 * This removes all references to the SoundClip from the
287 * manager. It does not however guarantee that the resource's
288 * destructor is called. If the client has any left over
289 * references to the resource it will not be freed.
290 *
291 * @param handle The handle of the SoundClip
292 *
293 * @see SoundClip
294 *
295 */
296 virtual void remove(ResourceHandle handle);
297
298 /** Removes all SoundClips from the manager
299 *
300 * This effectively removes all references to all SoundClips from
301 * the manager. If there are left over shared pointers to
302 * any resources they will not be deleted.
303 *
304 * @see SoundClip
305 *
306 */
307 virtual void removeAll();
308
309 /** Removes all unreferenced SoundClips
310 *
311 * This effectively removes all SoundClips that dont have an
312 * external reference. The resources will be deleted.
313 *
314 * @see SoundClip
315 *
316 */
317 virtual void removeUnreferenced();
318
319 /** Gets a shared pointer to the SoundClip
320 *
321 * If the SoundClip is not defined it will attempt to create
322 * and load the SoundClip based on the name (it assumes the name
323 * is a filename)
324 *
325 * @param name The name of the SoundClip
326 * @return A SoundClipPtr to the SoundClip
327 *
328 */
329 virtual SoundClipPtr get(const std::string& name);
330
331 /** Gets a shared pointer to the SoundClip
332 *
333 * If the resource is not defined it returns an empty
334 * (or invalid) SoundClipPtr and makes an entry in the log.
335 *
336 * @param handle The handle of the resource
337 * @return A SoundClipPtr to the resource
338 *
339 * @todo This should throw an exception instead of an
340 * empty SoundClipPtr
341 *
342 */
343 virtual SoundClipPtr get(ResourceHandle handle);
344
345 /** Gets a SoundClip handle by name
346 *
347 * Returns the SoundClip handle associated with the name
348 *
349 * @param name The name of the SoundClip
350 * @return 0 if the resource name is invalid
351 *
352 */
353 virtual ResourceHandle getResourceHandle(const std::string& name);
354
355 private:
356 typedef std::map< ResourceHandle, SoundClipPtr > SoundClipHandleMap;
357 typedef std::map< ResourceHandle, SoundClipPtr >::iterator SoundClipHandleMapIterator;
358 typedef std::map< ResourceHandle, SoundClipPtr >::const_iterator SoundClipHandleMapConstIterator;
359 typedef std::pair< ResourceHandle, SoundClipPtr > SoundClipHandleMapPair;
360
361 typedef std::map< std::string, SoundClipPtr > SoundClipNameMap;
362 typedef std::map< std::string, SoundClipPtr >::iterator SoundClipNameMapIterator;
363 typedef std::map< std::string, SoundClipPtr >::const_iterator SoundClipNameMapConstIterator;
364 typedef std::pair< std::string, SoundClipPtr > SoundClipNameMapPair;
365
366 SoundClipHandleMap m_sclipHandleMap;
367
368 SoundClipNameMap m_sclipNameMap;
369 };
370
371 } //FIFE
372
373 #endif //FIFE_SOUNDCLIP_MANAGER_H