ruby-ogre 0.0.1-x86-linux

data/deps/include/OGRE/OgreInstanceBatchVTF.h

@@ -0,0 +1,226 @@
+/*
+-----------------------------------------------------------------------------
+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 __BaseInstanceBatchVTF_H__
+#define __BaseInstanceBatchVTF_H__
+
+#include "OgreInstanceBatch.h"
+#include "OgreTexture.h"
+
+namespace Ogre
+{
+	/** \addtogroup Core
+	*  @{
+	*/
+	/** \addtogroup Scene
+	*  @{
+	*/
+
+	/** Instancing implementation using vertex texture through Vertex Texture Fetch (VTF)
+		This implementation has the following advantages:
+		  * Supports huge amount of instances per batch
+		  * Supports skinning even with huge ammounts of instances per batch
+		  * Doesn't need shader constants registers.
+		  * Best suited for skinned entities
+
+		But beware the disadvantages:
+		  * VTF is only fast on modern GPUs (ATI Radeon HD 2000+, GeForce 8+ series onwards)
+		  * On GeForce 6/7 series VTF is too slow
+		  * VTF isn't (controversely) supported on old ATI X1800 hardware
+		  * Only one bone weight per vertex is supported
+		  * GPUs with low memory bandwidth (i.e. laptops and integrated GPUs)
+		  may perform even worse than no instancing
+
+		Whether this performs great or bad depends on the hardware. It improved up to 4x performance on
+		a Intel Core 2 Quad Core X9650 GeForce 8600 GTS, and in an Intel Core 2 Duo P7350 ATI
+		Mobility Radeon HD 4650, but went 0.75x slower on an AthlonX2 5000+ integrated nForce 6150 SE
+		Each BaseInstanceBatchVTF has it's own texture, which occupies memory in VRAM.
+		Approx VRAM usage can be computed by doing 12 bytes * 3 * numInstances * numBones
+		Use flag IM_VTFBESTFIT to avoid wasting VRAM (but may reduce amount of instances per batch).
+		@par
+		The material requires at least a texture unit stage named "InstancingVTF"
+
+        @remarks
+			Design discussion webpage: http://www.ogre3d.org/forums/viewtopic.php?f=4&t=59902
+        @author
+            Matias N. Goldberg ("dark_sylinc")
+        @version
+            1.0
+     */
+	class _OgreExport BaseInstanceBatchVTF : public InstanceBatch
+	{
+	protected:
+		typedef vector<uint8>::type HWBoneIdxVec;
+		typedef vector<float>::type HWBoneWgtVec;
+		typedef vector<Matrix4>::type Matrix4Vec;
+
+		size_t					mMatricesPerInstance; //number of bone matrices per instance
+		size_t					mNumWorldMatrices;	//Num bones * num instances
+		TexturePtr				mMatrixTexture;	//The VTF
+
+		//Used when all matrices from each instance must be in the same row (i.e. HW Instancing).
+		//A few pixels are wasted, but resizing the texture puts the danger of not sampling the
+		//right pixel... (in theory it should work, but in practice doesn't)
+		size_t					mWidthFloatsPadding;
+		size_t					mMaxFloatsPerLine;
+
+		size_t					mRowLength;
+		size_t 					mWeightCount;
+		//Temporary array used to store 3x4 matrices before they are converted to dual quaternions
+		float* 					mTempTransformsArray3x4;
+
+		// The state of the usage of bone matrix lookup
+		bool mUseBoneMatrixLookup;
+		size_t mMaxLookupTableInstances;
+
+		bool mUseBoneDualQuaternions;
+		bool mForceOneWeight;
+		bool mUseOneWeight;
+
+		/** Clones the base material so it can have it's own vertex texture, and also
+			clones it's shadow caster materials, if it has any
+		*/
+		void cloneMaterial( const MaterialPtr &material );
+
+		/** Retrieves bone data from the original sub mesh and puts it into an appropriate buffer,
+			later to be read when creating the vertex semantics.
+			Assumes outBoneIdx has enough space (base submesh vertex count)
+		*/
+		void retrieveBoneIdx( VertexData *baseVertexData, HWBoneIdxVec &outBoneIdx );
+
+		/** @see retrieveBoneIdx()
+			Assumes outBoneIdx has enough space (twice the base submesh vertex count, one for each weight)
+			Assumes outBoneWgt has enough space (twice the base submesh vertex count, one for each weight)
+		*/
+		void retrieveBoneIdxWithWeights(VertexData *baseVertexData, HWBoneIdxVec &outBoneIdx, HWBoneWgtVec &outBoneWgt);
+
+		/** Setups the material to use a vertex texture */
+		void setupMaterialToUseVTF( TextureType textureType, MaterialPtr &material );
+
+		/** Creates the vertex texture */
+		void createVertexTexture( const SubMesh* baseSubMesh );
+
+		/** Creates 2 TEXCOORD semantics that will be used to sample the vertex texture */
+		virtual void createVertexSemantics( VertexData *thisVertexData, VertexData *baseVertexData,
+									const HWBoneIdxVec &hwBoneIdx, const HWBoneWgtVec &hwBoneWgt) = 0;
+
+		size_t convert3x4MatricesToDualQuaternions(float* matrices, size_t numOfMatrices, float* outDualQuaternions);
+									
+		/** Keeps filling the VTF with world matrix data */
+		void updateVertexTexture(void);
+
+		/** Affects VTF texture's width dimension */
+		virtual bool matricesToghetherPerRow() const = 0;
+
+		/** update the lookup numbers for entities with shared transforms */
+		virtual void updateSharedLookupIndexes();
+
+		/** @see InstanceBatch::generateInstancedEntity() */
+		virtual InstancedEntity* generateInstancedEntity(size_t num);
+
+	public:
+		BaseInstanceBatchVTF( InstanceManager *creator, MeshPtr &meshReference, const MaterialPtr &material,
+							size_t instancesPerBatch, const Mesh::IndexMap *indexToBoneMap,
+							const String &batchName);
+		virtual ~BaseInstanceBatchVTF();
+
+		/** @see InstanceBatch::buildFrom */
+		void buildFrom( const SubMesh *baseSubMesh, const RenderOperation &renderOperation );
+
+		//Renderable overloads
+		void getWorldTransforms( Matrix4* xform ) const;
+		unsigned short getNumWorldTransforms(void) const;
+
+		/** Overloaded to be able to updated the vertex texture */
+		void _updateRenderQueue(RenderQueue* queue);
+
+		/** Sets the state of the usage of bone matrix lookup
+		
+		Under default condition each instance entity is assigned a specific area in the vertex 
+		texture for bone matrix data. When turned on the amount of area in the vertex texture 
+		assigned for bone matrix data will be relative to the amount of unique animation states.
+		Instanced entities sharing the same animation state will share the same area in the matrix.
+		The specific position of each entity is placed in the vertex data and added in a second phase
+		in the shader.
+
+		Note this feature only works in VTF_HW for now.
+		This value needs to be set before adding any instanced entities
+		*/
+		void setBoneMatrixLookup(bool enable, size_t maxLookupTableInstances) { assert(mInstancedEntities.empty()); 
+			mUseBoneMatrixLookup = enable; mMaxLookupTableInstances = maxLookupTableInstances; }
+
+		/** Tells whether to use bone matrix lookup
+		@see setBoneMatrixLookup()
+		*/
+		bool useBoneMatrixLookup() const { return mUseBoneMatrixLookup; }
+
+		void setBoneDualQuaternions(bool enable) { assert(mInstancedEntities.empty());
+			mUseBoneDualQuaternions = enable; mRowLength = (mUseBoneDualQuaternions ? 2 : 3); }
+
+		bool useBoneDualQuaternions() const { return mUseBoneDualQuaternions; }
+
+		void setForceOneWeight(bool enable) {  assert(mInstancedEntities.empty());
+			mForceOneWeight = enable; }
+
+		bool forceOneWeight() const { return mForceOneWeight; }
+
+		void setUseOneWeight(bool enable) {  assert(mInstancedEntities.empty());
+			mUseOneWeight = enable; }
+
+		bool useOneWeight() const { return mUseOneWeight; }
+
+		/** @see InstanceBatch::useBoneWorldMatrices()	*/
+		virtual bool useBoneWorldMatrices() const { return !mUseBoneMatrixLookup; }
+
+		/** @return the maximum amount of shared transform entities when using lookup table*/
+		virtual size_t getMaxLookupTableInstances() const { return mMaxLookupTableInstances; }
+		
+	};
+
+	class _OgreExport InstanceBatchVTF : public BaseInstanceBatchVTF
+	{
+		
+		void setupVertices( const SubMesh* baseSubMesh );
+		void setupIndices( const SubMesh* baseSubMesh );
+
+		/** Creates 2 TEXCOORD semantics that will be used to sample the vertex texture */
+		void createVertexSemantics( VertexData *thisVertexData, VertexData *baseVertexData,
+			const HWBoneIdxVec &hwBoneIdx, const HWBoneWgtVec &hwBoneWgt );
+
+		virtual bool matricesToghetherPerRow() const { return false; }
+	public:
+		InstanceBatchVTF( InstanceManager *creator, MeshPtr &meshReference, const MaterialPtr &material,
+							size_t instancesPerBatch, const Mesh::IndexMap *indexToBoneMap,
+							const String &batchName);
+		virtual ~InstanceBatchVTF();
+
+		/** @see InstanceBatch::calculateMaxNumInstances */
+		size_t calculateMaxNumInstances( const SubMesh *baseSubMesh, uint16 flags ) const;
+	};
+}
+
+#endif

data/deps/include/OGRE/OgreInstanceManager.h

@@ -0,0 +1,280 @@
+/*
+-----------------------------------------------------------------------------
+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 __InstanceManager_H__
+#define __InstanceManager_H__
+
+#include "OgrePrerequisites.h"
+#include "OgreMesh.h"
+#include "OgreRenderOperation.h"
+
+namespace Ogre
+{
+	/** \addtogroup Core
+	*  @{
+	*/
+	/** \addtogroup Scene
+	*  @{
+	*/
+
+	/** This is the main starting point for the new instancing system.
+		Each InstanceManager can control one technique and one mesh, but it can manage
+		multiple materials at the same time.
+		@see SceneManager::createInstanceManager, which creates this InstanceManager. Each one
+		must have a unique name. It's wasteless to create two InstanceManagers with the same
+		mesh reference, instancing technique and instances per batch count.
+		This class takes care of managing batches automatically, so that more are created when
+		needed, and reuse existing ones as much as posible; thus the user doesn't have to worry
+		of managing all those low level issues.
+		@see InstanceBatch & @see InstanceEntity for more information.
+
+        @remarks
+			Design discussion webpage: http://www.ogre3d.org/forums/viewtopic.php?f=4&t=59902
+        @author
+            Matias N. Goldberg ("dark_sylinc")
+        @version
+            1.0
+     */
+	class _OgreExport InstanceManager : public FactoryAlloc
+	{
+	public:
+		enum InstancingTechnique
+		{
+			ShaderBased,			//Any SM 2.0+ @See InstanceBatchShader
+			TextureVTF,				//Needs Vertex Texture Fetch & SM 3.0+ @See InstanceBatchVTF
+			HWInstancingBasic,		//Needs SM 3.0+ and HW instancing support @See InstanceBatchHW
+			HWInstancingVTF,		//Needs SM 3.0+, HW instancing support & VTF @See InstanceBatchHW_VTF
+			InstancingTechniquesCount
+		};
+
+		/** Values to be used in setSetting() & BatchSettings::setting */
+		enum BatchSettingId
+		{
+			/// Makes all batches from same material cast shadows
+			CAST_SHADOWS		= 0,
+			/// Makes each batch to display it's bounding box. Useful for debugging or profiling
+			SHOW_BOUNDINGBOX,
+
+			NUM_SETTINGS
+		};
+
+	private:
+		struct BatchSettings
+		{
+			//These are all per material
+			bool				setting[NUM_SETTINGS];
+
+			BatchSettings()
+			{
+				setting[CAST_SHADOWS]				= true;
+				setting[SHOW_BOUNDINGBOX]			= false;
+			}
+		};
+
+		typedef vector<InstanceBatch*>::type		InstanceBatchVec;	//vec[batchN] = Batch
+		typedef map<String, InstanceBatchVec>::type	InstanceBatchMap;	//map[materialName] = Vec
+
+		typedef map<String, BatchSettings>::type	BatchSettingsMap;
+
+		const String			mName;					//Not the name of the mesh
+		MeshPtr					mMeshReference;
+		InstanceBatchMap		mInstanceBatches;
+		size_t					mIdCount;
+
+		InstanceBatchVec		mDirtyBatches;
+
+		RenderOperation			mSharedRenderOperation;
+
+		size_t					mInstancesPerBatch;
+		InstancingTechnique		mInstancingTechnique;
+		uint16					mInstancingFlags;		//@see InstanceManagerFlags
+		unsigned short			mSubMeshIdx;
+		
+		BatchSettingsMap		mBatchSettings;
+		SceneManager*			mSceneManager;
+
+		size_t					mMaxLookupTableInstances;
+		/** Finds a batch with at least one free instanced entity we can use.
+			If none found, creates one.
+		*/
+		inline InstanceBatch* getFreeBatch( const String &materialName );
+
+		/** Called when batches are fully exhausted (can't return more instances) so a new batch
+			is created.
+			For the first time use, it can take big build time.
+			It takes care of getting the render operation which will be shared by further batches,
+			which decreases their build time, and prevents GPU RAM from skyrocketing.
+			@param materialName The material name, to know where to put this batch in the map
+			@param firstTime True if this is the first time it is called
+			@return The created InstancedManager for convenience
+        */
+		InstanceBatch* buildNewBatch( const String &materialName, bool firstTime );
+
+		/** @see defragmentBatches overload, this takes care of an array of batches
+			for a specific material */
+		void defragmentBatches( bool optimizeCull, vector<InstancedEntity*>::type &entities,
+								InstanceBatchVec &fragmentedBatches );
+
+		/** @see setSetting. This function helps it by setting the given parameter to all batches
+			in container.
+		*/
+		void applySettingToBatches( BatchSettingId id, bool value, const InstanceBatchVec &container );
+
+	public:
+		InstanceManager( const String &customName, SceneManager *sceneManager,
+						 const String &meshName, const String &groupName,
+						 InstancingTechnique instancingTechnique, uint16 instancingFlags,
+						 size_t instancesPerBatch, unsigned short subMeshIdx, bool useBoneMatrixLookup = false);
+		virtual ~InstanceManager();
+
+		const String& getName() const { return mName; }
+
+		/** Raises an exception if trying to change it after creating the first InstancedEntity
+			@remarks The actual value may be less if the technique doesn't support having so much
+			@see getMaxOrBestNumInstancesPerBatches for the usefulness of this function
+			@param instancesPerBatch New instances per batch number
+		*/
+		void setInstancesPerBatch( size_t instancesPerBatch );
+
+		/** Sets the size of the lookup table for techniques supporting bone lookup table.
+			Raises an exception if trying to change it after creating the first InstancedEntity.
+			Setting this value below the number of unique (non-sharing) entity instance animations
+			will produce a crash during runtime. Setting this value above will increase memory
+			consumption and reduce framerate.
+			@remarks The value should be as close but not below the actual value. 
+			@param maxLookupTableInstances New size of the lookup table
+		*/
+		void setMaxLookupTableInstances( size_t maxLookupTableInstances );
+
+		/**	Calculates the maximum (or the best amount, depending on flags) of instances
+			per batch given the suggested size for the technique this manager was created for.
+			@remarks
+			This is done automatically when creating an instanced entity, but this function in conjunction
+			with @see setInstancesPerBatch allows more flexible control over the amount of instances
+			per batch
+			@param materialName Name of the material to base on
+			@param suggestedSize Suggested amount of instances per batch
+			@param flags @see InstanceManagerFlags
+			@return The max/best amount of instances per batch given the suggested size and flags
+		*/
+		size_t getMaxOrBestNumInstancesPerBatch( String materialName, size_t suggestedSize, uint16 flags );
+
+		/** @copydoc SceneManager::createInstancedEntity */
+		InstancedEntity* createInstancedEntity( const String &materialName );
+
+		/** This function can be useful to improve CPU speed after having too many instances
+			created, which where now removed, thus freeing many batches with zero used Instanced Entities
+			However the batches aren't automatically removed from memory until the InstanceManager is
+			destroyed, or this function is called. This function removes those batches which are completely
+			unused (only wasting memory).
+        */
+		void cleanupEmptyBatches(void);
+
+		/** After creating many entities (which turns in many batches) and then removing entities that
+			are in the middle of these batches, there might be many batches with many free entities.
+			Worst case scenario, there could be left one batch per entity. Imagine there can be
+			80 entities per batch, there are 80 batches, making a total of 6400 entities. Then
+			6320 of those entities are removed in a very specific way, which leads to having
+			80 batches, 80 entities, and GPU vertex shader still needs to process 6400!
+			This is called fragmentation. This function reparents the InstancedEntities
+			to fewer batches, in this case leaving only one batch with 80 entities
+
+			@remarks
+			This function takes time. Make sure to call this only when you're sure there's
+			too much of fragmentation and you won't be creating more InstancedEntities soon
+			Also in many cases cleanupEmptyBatches() ought to be enough
+			Defragmentation is done per material
+			Static batches won't be defragmented. If you want to degragment them, set them
+			to dynamic again, and switch back to static after calling this function.
+
+			@param optimizeCulling When true, entities close together will be reorganized
+			in the same batch for more efficient CPU culling. This can take more CPU
+			time. You want this to be false if you now you're entities are moving very
+			randomly which tends them to get separated and spread all over the scene
+			(which nullifies any CPU culling)
+        */
+		void defragmentBatches( bool optimizeCulling );
+
+		/** Applies a setting for all batches using the same material_ existing ones and
+			those that will be created in the future.
+		@par
+			For example setSetting( BatchSetting::CAST_SHADOWS, false ) disables shadow
+			casting for all instanced entities (@see MovableObject::setCastShadow)
+		@par
+			For example setSetting( BatchSetting::SHOW_BOUNDINGBOX, true, "MyMat" )
+			will display the bounding box of the batch (not individual InstancedEntities)
+			from all batches using material "MyMat"
+		@note If the material name hasn't been used, the settings are still stored
+		This allows setting up batches before they get even created.
+		@param id Setting Id to setup, @see BatchSettings::BatchSettingId
+		@param enabled Boolean value. It's meaning depends on the id.
+		@param materialName When Blank, the setting is applied to all existing materials
+		*/
+		void setSetting( BatchSettingId id, bool value, const String &materialName = StringUtil::BLANK );
+
+		/// If settings for the given material didn't exist, default value is returned
+		bool getSetting( BatchSettingId id, const String &materialName ) const;
+
+		/** Returns true if settings were already created for the given material name.
+			If false is returned, it means getSetting will return default settings.
+		*/
+		bool hasSettings( const String &materialName ) const
+		{ return mBatchSettings.find( materialName ) != mBatchSettings.end(); }
+
+		/**	@copydoc InstanceBatch::setStaticAndUpdate */
+		void setBatchesAsStaticAndUpdate( bool bStatic );
+
+		/** Called by an InstanceBatch when it requests their bounds to be updated for proper culling
+			@param dirtyBatch The batch which is dirty, usually same as caller.
+		*/
+		void _addDirtyBatch( InstanceBatch *dirtyBatch );
+
+		/** Called by SceneManager when we told it we have at least one dirty batch */
+		void _updateDirtyBatches(void);
+
+		typedef ConstMapIterator<InstanceBatchMap> InstanceBatchMapIterator;
+		typedef ConstVectorIterator<InstanceBatchVec> InstanceBatchIterator;
+
+		/// Get non-updateable iterator over instance batches per material
+		InstanceBatchMapIterator getInstanceBatchMapIterator(void) const
+		{ return InstanceBatchMapIterator( mInstanceBatches.begin(), mInstanceBatches.end() ); }
+
+		/** Get non-updateable iterator over instance batches for given material
+			@remarks
+			Each InstanceBatch pointer may be modified for low level usage (i.e.
+			setCustomParameter), but there's no synchronization mechanism when
+			multithreading or creating more instances, that's up to the user.
+		*/
+		InstanceBatchIterator getInstanceBatchIterator( const String &materialName ) const
+		{
+			InstanceBatchMap::const_iterator it = mInstanceBatches.find( materialName );
+			return InstanceBatchIterator( it->second.begin(), it->second.end() );
+		}
+	};
+}
+
+#endif