ruby-ogre 0.0.1-x86-linux

data/deps/include/OGRE/OgreResourceManager.h

@@ -0,0 +1,538 @@
+/*
+-----------------------------------------------------------------------------
+This source file is part of OGRE
+    (Object-oriented Graphics Rendering Engine)
+For the latest info, see http://www.ogre3d.org/
+
+Copyright (c) 2000-2012 Torus Knot Software Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-----------------------------------------------------------------------------
+*/
+#ifndef _ResourceManager_H__
+#define _ResourceManager_H__
+
+#include "OgrePrerequisites.h"
+
+#include "OgreResource.h"
+#include "OgreResourceGroupManager.h"
+#include "OgreIteratorWrappers.h"
+#include "OgreCommon.h"
+#include "OgreDataStream.h"
+#include "OgreStringVector.h"
+#include "OgreScriptLoader.h"
+
+namespace Ogre {
+
+	/** \addtogroup Core
+	*  @{
+	*/
+	/** \addtogroup Resources
+	*  @{
+	*/
+	/** Defines a generic resource handler.
+    @remarks
+        A resource manager is responsible for managing a pool of
+        resources of a particular type. It must index them, look
+        them up, load and destroy them. It may also need to stay within
+        a defined memory budget, and temporarily unload some resources
+        if it needs to to stay within this budget.
+    @par
+        Resource managers use a priority system to determine what can
+        be unloaded, and a Least Recently Used (LRU) policy within
+        resources of the same priority.
+	@par
+		Resources can be loaded using the generalised load interface,
+		and they can be unloaded and removed. In addition, each 
+		subclass of ResourceManager will likely define custom 'load' methods
+		which take explicit parameters depending on the kind of resource
+		being created.
+	@note
+		Resources can be loaded and unloaded through the Resource class, 
+		but they can only be removed (and thus eventually destroyed) using
+		their parent ResourceManager.
+    @note
+        If OGRE_THREAD_SUPPORT is 1, this class is thread-safe.
+    */
+	class _OgreExport ResourceManager : public ScriptLoader, public ResourceAlloc
+    {
+    public:
+		OGRE_AUTO_MUTEX // public to allow external locking
+        ResourceManager();
+        virtual ~ResourceManager();
+
+        /** Creates a new blank resource, but does not immediately load it.
+        @remarks
+            Resource managers handle disparate types of resources, so if you want
+			to get at the detailed interface of this resource, you'll have to 
+			cast the result to the subclass you know you're creating. 
+		@param name The unique name of the resource
+		@param group The name of the resource group to attach this new resource to
+		@param isManual Is this resource manually loaded? If so, you should really
+			populate the loader parameter in order that the load process
+			can call the loader back when loading is required. 
+		@param loader Pointer to a ManualLoader implementation which will be called
+			when the Resource wishes to load (should be supplied if you set
+			isManual to true). You can in fact leave this parameter null 
+			if you wish, but the Resource will never be able to reload if 
+			anything ever causes it to unload. Therefore provision of a proper
+			ManualLoader instance is strongly recommended.
+        @param createParams If any parameters are required to create an instance,
+            they should be supplied here as name / value pairs
+        */
+        virtual ResourcePtr create(const String& name, const String& group, 
+            bool isManual = false, ManualResourceLoader* loader = 0, 
+            const NameValuePairList* createParams = 0);
+
+		typedef std::pair<ResourcePtr, bool> ResourceCreateOrRetrieveResult;
+		/** Create a new resource, or retrieve an existing one with the same
+			name if it already exists.
+		@remarks
+			This method performs the same task as calling getByName() followed
+			by create() if that returns null. The advantage is that it does it
+			in one call so there are no race conditions if using multiple
+			threads that could cause getByName() to return null, but create() to
+			fail because another thread created a resource in between.
+		@see ResourceManager::create
+		@see ResourceManager::getByName
+		@return A pair, the first element being the pointer, and the second being 
+			an indicator specifying whether the resource was newly created.
+		*/
+		virtual ResourceCreateOrRetrieveResult createOrRetrieve(const String& name, 
+			const String& group, bool isManual = false, 
+			ManualResourceLoader* loader = 0, 
+			const NameValuePairList* createParams = 0);
+		
+        /** Set a limit on the amount of memory this resource handler may use.
+            @remarks
+                If, when asked to load a new resource, the manager believes it will exceed this memory
+                budget, it will temporarily unload a resource to make room for the new one. This unloading
+                is not permanent and the Resource is not destroyed; it simply needs to be reloaded when
+                next used.
+        */
+        virtual void setMemoryBudget( size_t bytes);
+
+        /** Get the limit on the amount of memory this resource handler may use.
+        */
+        virtual size_t getMemoryBudget(void) const;
+
+		/** Gets the current memory usage, in bytes. */
+		virtual size_t getMemoryUsage(void) const { return mMemoryUsage.get(); }
+
+		/** Unloads a single resource by name.
+		@remarks
+			Unloaded resources are not removed, they simply free up their memory
+			as much as they can and wait to be reloaded.
+			@see ResourceGroupManager for unloading of resource groups.
+		*/
+		virtual void unload(const String& name);
+		
+		/** Unloads a single resource by handle.
+		@remarks
+			Unloaded resources are not removed, they simply free up their memory
+			as much as they can and wait to be reloaded.
+			@see ResourceGroupManager for unloading of resource groups.
+		*/
+		virtual void unload(ResourceHandle handle);
+
+		/** Unloads all resources.
+		@remarks
+			Unloaded resources are not removed, they simply free up their memory
+			as much as they can and wait to be reloaded.
+			@see ResourceGroupManager for unloading of resource groups.
+		@param reloadableOnly If true (the default), only unload the resource that
+            is reloadable. Because some resources isn't reloadable, they will be
+			unloaded but can't load them later. Thus, you might not want to them
+			unloaded. Or, you might unload all of them, and then populate them
+			manually later.
+			@see Resource::isReloadable for resource is reloadable.
+		*/
+		virtual void unloadAll(bool reloadableOnly = true);
+
+		/** Caused all currently loaded resources to be reloaded.
+		@remarks
+			All resources currently being held in this manager which are also
+			marked as currently loaded will be unloaded, then loaded again.
+		@param reloadableOnly If true (the default), only reload the resource that
+            is reloadable. Because some resources isn't reloadable, they will be
+			unloaded but can't loaded again. Thus, you might not want to them
+			unloaded. Or, you might unload all of them, and then populate them
+			manually later.
+			@see Resource::isReloadable for resource is reloadable.
+		*/
+		virtual void reloadAll(bool reloadableOnly = true);
+
+		/** Unload all resources which are not referenced by any other object.
+		@remarks
+			This method behaves like unloadAll, except that it only unloads resources
+            which are not in use, ie not referenced by other objects. This allows you
+            to free up some memory selectively whilst still keeping the group around
+            (and the resources present, just not using much memory).
+        @par
+            Some referenced resource may exists 'weak' pointer to their sub-components
+            (e.g. Entity held pointer to SubMesh), in this case, unload or reload that
+            resource will cause dangerous pointer access. Use this function instead of
+            unloadAll allows you avoid fail in those situations.
+		@param reloadableOnly If true (the default), only unloads resources
+			which can be subsequently automatically reloaded.
+		*/
+		virtual void unloadUnreferencedResources(bool reloadableOnly = true);
+
+		/** Caused all currently loaded but not referenced by any other object
+            resources to be reloaded.
+		@remarks
+			This method behaves like reloadAll, except that it only reloads resources
+            which are not in use, i.e. not referenced by other objects.
+        @par
+            Some referenced resource may exists 'weak' pointer to their sub-components
+            (e.g. Entity held pointer to SubMesh), in this case, unload or reload that
+            resource will cause dangerous pointer access. Use this function instead of
+            reloadAll allows you avoid fail in those situations.
+		@param reloadableOnly If true (the default), only reloads resources
+			which can be subsequently automatically reloaded.
+		*/
+		virtual void reloadUnreferencedResources(bool reloadableOnly = true);
+
+		/** Remove a single resource.
+		@remarks
+			Removes a single resource, meaning it will be removed from the list
+			of valid resources in this manager, also causing it to be unloaded. 
+		@note
+			The word 'Destroy' is not used here, since
+			if any other pointers are referring to this resource, it will persist
+			until they have finished with it; however to all intents and purposes
+			it no longer exists and will likely get destroyed imminently.
+        @note
+            If you do have shared pointers to resources hanging around after the 
+            ResourceManager is destroyed, you may get problems on destruction of
+            these resources if they were relying on the manager (especially if
+            it is a plugin). If you find you get problems on shutdown in the
+            destruction of resources, try making sure you release all your
+            shared pointers before you shutdown OGRE.
+		*/
+		virtual void remove(ResourcePtr& r);
+
+        /** Remove a single resource by name.
+		@remarks
+			Removes a single resource, meaning it will be removed from the list
+			of valid resources in this manager, also causing it to be unloaded. 
+		@note
+			The word 'Destroy' is not used here, since
+			if any other pointers are referring to this resource, it will persist
+			until they have finished with it; however to all intents and purposes
+			it no longer exists and will likely get destroyed imminently.
+        @note
+            If you do have shared pointers to resources hanging around after the 
+            ResourceManager is destroyed, you may get problems on destruction of
+            these resources if they were relying on the manager (especially if
+            it is a plugin). If you find you get problems on shutdown in the
+            destruction of resources, try making sure you release all your
+            shared pointers before you shutdown OGRE.
+		*/
+		virtual void remove(const String& name);
+		
+		/** Remove a single resource by handle.
+		@remarks
+			Removes a single resource, meaning it will be removed from the list
+			of valid resources in this manager, also causing it to be unloaded. 
+		@note
+			The word 'Destroy' is not used here, since
+			if any other pointers are referring to this resource, it will persist
+			until they have finished with it; however to all intents and purposes
+			it no longer exists and will likely get destroyed imminently.
+        @note
+            If you do have shared pointers to resources hanging around after the 
+            ResourceManager is destroyed, you may get problems on destruction of
+            these resources if they were relying on the manager (especially if
+            it is a plugin). If you find you get problems on shutdown in the
+            destruction of resources, try making sure you release all your
+            shared pointers before you shutdown OGRE.
+		*/
+		virtual void remove(ResourceHandle handle);
+		/** Removes all resources.
+		@note
+			The word 'Destroy' is not used here, since
+			if any other pointers are referring to these resources, they will persist
+			until they have been finished with; however to all intents and purposes
+			the resources no longer exist and will get destroyed imminently.
+        @note
+            If you do have shared pointers to resources hanging around after the 
+            ResourceManager is destroyed, you may get problems on destruction of
+            these resources if they were relying on the manager (especially if
+            it is a plugin). If you find you get problems on shutdown in the
+            destruction of resources, try making sure you release all your
+            shared pointers before you shutdown OGRE.
+        */
+        virtual void removeAll(void);
+
+		/** Remove all resources which are not referenced by any other object.
+		@remarks
+			This method behaves like removeAll, except that it only removes resources
+            which are not in use, ie not referenced by other objects. This allows you
+            to free up some memory selectively whilst still keeping the group around
+            (and the resources present, just not using much memory).
+        @par
+            Some referenced resource may exists 'weak' pointer to their sub-components
+            (e.g. Entity held pointer to SubMesh), in this case, remove or reload that
+            resource will cause dangerous pointer access. Use this function instead of
+            removeAll allows you avoid fail in those situations.
+		@param reloadableOnly If true (the default), only removes resources
+			which can be subsequently automatically reloaded.
+		*/
+		virtual void removeUnreferencedResources(bool reloadableOnly = true);
+
+        /** Retrieves a pointer to a resource by name, or null if the resource does not exist.
+        */
+        virtual ResourcePtr getByName(const String& name, const String& groupName = ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME);
+        /** Retrieves a pointer to a resource by handle, or null if the resource does not exist.
+        */
+        virtual ResourcePtr getByHandle(ResourceHandle handle);
+		
+		/// Returns whether the named resource exists in this manager
+		virtual bool resourceExists(const String& name)
+		{
+			return !getByName(name).isNull();
+		}
+		/// Returns whether a resource with the given handle exists in this manager
+		virtual bool resourceExists(ResourceHandle handle)
+		{
+			return !getByHandle(handle).isNull();
+		}
+
+		/** Notify this manager that a resource which it manages has been 
+			'touched', i.e. used. 
+		*/
+		virtual void _notifyResourceTouched(Resource* res);
+
+		/** Notify this manager that a resource which it manages has been 
+			loaded. 
+		*/
+		virtual void _notifyResourceLoaded(Resource* res);
+
+		/** Notify this manager that a resource which it manages has been 
+			unloaded.
+		*/
+		virtual void _notifyResourceUnloaded(Resource* res);
+
+		/** Generic prepare method, used to create a Resource specific to this 
+			ResourceManager without using one of the specialised 'prepare' methods
+			(containing per-Resource-type parameters).
+		@param name The name of the Resource
+		@param group The resource group to which this resource will belong
+		@param isManual Is the resource to be manually loaded? If so, you should
+			provide a value for the loader parameter
+		@param loader The manual loader which is to perform the required actions
+			when this resource is loaded; only applicable when you specify true
+			for the previous parameter
+        @param loadParams Optional pointer to a list of name/value pairs 
+            containing loading parameters for this type of resource.
+		@param backgroundThread Optional boolean which lets the load routine know if it
+			is being run on the background resource loading thread
+		*/
+		virtual ResourcePtr prepare(const String& name, 
+            const String& group, bool isManual = false, 
+			ManualResourceLoader* loader = 0, const NameValuePairList* loadParams = 0,
+			bool backgroundThread = false);
+
+		/** Generic load method, used to create a Resource specific to this 
+			ResourceManager without using one of the specialised 'load' methods
+			(containing per-Resource-type parameters).
+		@param name The name of the Resource
+		@param group The resource group to which this resource will belong
+		@param isManual Is the resource to be manually loaded? If so, you should
+			provide a value for the loader parameter
+		@param loader The manual loader which is to perform the required actions
+			when this resource is loaded; only applicable when you specify true
+			for the previous parameter
+        @param loadParams Optional pointer to a list of name/value pairs 
+            containing loading parameters for this type of resource.
+		@param backgroundThread Optional boolean which lets the load routine know if it
+			is being run on the background resource loading thread
+		*/
+		virtual ResourcePtr load(const String& name, 
+            const String& group, bool isManual = false, 
+			ManualResourceLoader* loader = 0, const NameValuePairList* loadParams = 0,
+			bool backgroundThread = false);
+
+		/** Gets the file patterns which should be used to find scripts for this
+			ResourceManager.
+		@remarks
+			Some resource managers can read script files in order to define
+			resources ahead of time. These resources are added to the available
+			list inside the manager, but none are loaded initially. This allows
+			you to load the items that are used on demand, or to load them all 
+			as a group if you wish (through ResourceGroupManager).
+		@par
+			This method lets you determine the file pattern which will be used
+			to identify scripts intended for this manager.
+		@return
+			A list of file patterns, in the order they should be searched in.
+		@see isScriptingSupported, parseScript
+		*/
+		virtual const StringVector& getScriptPatterns(void) const { return mScriptPatterns; }
+
+		/** Parse the definition of a set of resources from a script file.
+		@remarks
+			Some resource managers can read script files in order to define
+			resources ahead of time. These resources are added to the available
+			list inside the manager, but none are loaded initially. This allows
+			you to load the items that are used on demand, or to load them all 
+			as a group if you wish (through ResourceGroupManager).
+		@param stream Weak reference to a data stream which is the source of the script
+		@param groupName The name of the resource group that resources which are
+			parsed are to become a member of. If this group is loaded or unloaded, 
+			then the resources discovered in this script will be loaded / unloaded
+			with it.
+		*/
+		virtual void parseScript(DataStreamPtr& stream, const String& groupName)
+                { (void)stream; (void)groupName; }
+
+		/** Gets the relative loading order of resources of this type.
+		@remarks
+			There are dependencies between some kinds of resource in terms of loading
+			order, and this value enumerates that. Higher values load later during
+			bulk loading tasks.
+		*/
+		virtual Real getLoadingOrder(void) const { return mLoadOrder; }
+
+		/** Gets a string identifying the type of resource this manager handles. */
+		const String& getResourceType(void) const { return mResourceType; }
+
+        /** Sets whether this manager and its resources habitually produce log output */
+        virtual void setVerbose(bool v) { mVerbose = v; }
+
+        /** Gets whether this manager and its resources habitually produce log output */
+        virtual bool getVerbose(void) { return mVerbose; }
+
+		/** Definition of a pool of resources, which users can use to reuse similar
+			resources many times without destroying and recreating them.
+		@remarks
+			This is a simple utility class which allows the reuse of resources
+			between code which has a changing need for them. For example, 
+		*/
+		class _OgreExport ResourcePool : public Pool<ResourcePtr>, public ResourceAlloc
+		{
+		protected:
+			String mName;
+		public:
+			ResourcePool(const String& name);
+			~ResourcePool();
+			/// Get the name of the pool
+			const String& getName() const;
+			void clear();
+		};
+		
+		/// Create a resource pool, or reuse one that already exists
+		ResourcePool* getResourcePool(const String& name);
+		/// Destroy a resource pool
+		void destroyResourcePool(ResourcePool* pool);
+		/// Destroy a resource pool
+		void destroyResourcePool(const String& name);
+		/// destroy all pools
+		void destroyAllResourcePools();
+
+
+
+
+    protected:
+
+        /** Allocates the next handle. */
+        ResourceHandle getNextHandle(void);
+
+		/** Create a new resource instance compatible with this manager (no custom 
+			parameters are populated at this point). 
+		@remarks
+			Subclasses must override this method and create a subclass of Resource.
+		@param name The unique name of the resource
+		@param group The name of the resource group to attach this new resource to
+		@param isManual Is this resource manually loaded? If so, you should really
+			populate the loader parameter in order that the load process
+			can call the loader back when loading is required. 
+		@param loader Pointer to a ManualLoader implementation which will be called
+			when the Resource wishes to load (should be supplied if you set
+			isManual to true). You can in fact leave this parameter null 
+			if you wish, but the Resource will never be able to reload if 
+			anything ever causes it to unload. Therefore provision of a proper
+			ManualLoader instance is strongly recommended.
+        @param createParams If any parameters are required to create an instance,
+            they should be supplied here as name / value pairs. These do not need 
+            to be set on the instance (handled elsewhere), just used if required
+            to differentiate which concrete class is created.
+
+		*/
+		virtual Resource* createImpl(const String& name, ResourceHandle handle, 
+			const String& group, bool isManual, ManualResourceLoader* loader, 
+            const NameValuePairList* createParams) = 0;
+		/** Add a newly created resource to the manager (note weak reference) */
+		virtual void addImpl( ResourcePtr& res );
+		/** Remove a resource from this manager; remove it from the lists. */
+		virtual void removeImpl( ResourcePtr& res );
+		/** Checks memory usage and pages out if required.
+		*/
+		virtual void checkUsage(void);
+
+
+    public:
+		typedef HashMap< String, ResourcePtr > ResourceMap;
+		typedef HashMap< String, ResourceMap > ResourceWithGroupMap;
+		typedef map<ResourceHandle, ResourcePtr>::type ResourceHandleMap;
+    protected:
+        ResourceHandleMap mResourcesByHandle;
+        ResourceMap mResources;
+		ResourceWithGroupMap mResourcesWithGroup;
+        ResourceHandle mNextHandle;
+        size_t mMemoryBudget; // In bytes
+        AtomicScalar<size_t> mMemoryUsage; // In bytes
+
+        bool mVerbose;
+
+		// IMPORTANT - all subclasses must populate the fields below
+
+		/// Patterns to use to look for scripts if supported (e.g. *.overlay)
+		StringVector mScriptPatterns; 
+		/// Loading order relative to other managers, higher is later
+		Real mLoadOrder; 
+		/// String identifying the resource type this manager handles
+		String mResourceType; 
+
+    public:
+        typedef MapIterator<ResourceHandleMap> ResourceMapIterator;
+        /** Returns an iterator over all resources in this manager. 
+        @note
+            Use of this iterator is NOT thread safe!
+        */
+        ResourceMapIterator getResourceIterator(void) 
+        {
+            return ResourceMapIterator(mResourcesByHandle.begin(), mResourcesByHandle.end());
+        }
+
+	protected:
+		typedef map<String, ResourcePool*>::type ResourcePoolMap;
+		ResourcePoolMap mResourcePoolMap;
+
+
+    
+
+    };
+	/** @} */
+	/** @} */
+
+}
+
+#endif