libogre-1.8-dev 1.8.1+dfsg-0ubuntu3 / usr / include / OGRE / OgreInstanceBatch.h

/*
-----------------------------------------------------------------------------
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 __InstanceBatch_H__
#define __InstanceBatch_H__

#include "OgrePrerequisites.h"
#include "OgreRenderOperation.h"
#include "OgreRenderable.h"
#include "OgreMovableObject.h"
#include "OgreMesh.h"

namespace Ogre
{
	/** \addtogroup Core
	*  @{
	*/
	/** \addtogroup Scene
	*  @{
	*/

	/** InstanceBatch forms part of the new Instancing system
		This is an abstract class that must be derived to implement different instancing techniques
		(@see InstanceManager::InstancingTechnique)
		OGRE wasn't truly thought for instancing. OGRE assumes that either:
			a. One MovableObject -> No Renderable
			b. One MovableObject -> One Renderable
			c. One MovableObject -> Many Renderable.
		However, instances work on reverse: Many MovableObject have the same Renderable.
		<b>Instancing is already difficult to cull by a CPU</b>, but the main drawback from this assumption
		is that it makes it even harder to take advantage from OGRE's culling capabilities
		(i.e. @see OctreeSceneManager)
		@par
		To workaround this problem, InstanceBatch updates on almost every frame,
		growing the bounding box to fit all instances that are not being culled individually.
		This helps by avoiding a huge bbox that may cover the whole scene, which decreases shadow
		quality considerably (as it is seen as large shadow receiver)
		Furthermore, if no individual instance is visible, the InstanceBatch switches it's visibility
		(@see MovableObject::setVisible) to avoid sending this Renderable to the GPU. This happens because
		even when no individual instance is visible, their merged bounding box may cause OGRE to think
		the batch is visible (i.e. the camera is looking between object A & B, but A & B aren't visible)
		@par
		<b>As it happens with instancing in general, all instanced entities from the same batch will share
		the same textures and materials</b>
		@par
		Each InstanceBatch preallocates a fixed amount of mInstancesPerBatch instances once it's been
		built (@see build, @see buildFrom).
		@see createInstancedEntity and @see removeInstancedEntity on how to retrieve those instances
		remove them from scene.
		Note that, on GPU side, removing an instance from scene doesn't save GPU cycles on what
		respects vertex shaders, but saves a little fillrate and pixel shaders; unless all instances
		are removed, which saves GPU.
		For more information, @see InstancedEntity
		For information on how Ogre manages multiple Instance batches, @see InstanceManager

        @remarks
			Design discussion webpage
        @author
            Matias N. Goldberg ("dark_sylinc")
        @version
            1.0
     */
	class _OgreExport InstanceBatch : public Renderable, public MovableObject
	{
	public:
		typedef vector<InstancedEntity*>::type InstancedEntityVec;
	protected:
		RenderOperation		mRenderOperation;
		size_t				mInstancesPerBatch;

		InstanceManager		*mCreator;

		MaterialPtr			mMaterial;

		MeshPtr				 mMeshReference;
		Mesh::IndexMap const *mIndexToBoneMap;

		//InstancedEntities are all allocated at build time and kept as "unused"
		//when they're requested, they're removed from there when requested,
		//and put back again when they're no longer needed
		//Note each InstancedEntity has a unique ID ranging from [0; mInstancesPerBatch)
		InstancedEntityVec	mInstancedEntities;
		InstancedEntityVec	mUnusedEntities;

		/// This bbox contains all (visible) instanced entities
		AxisAlignedBox		mFullBoundingBox;
		Real				mBoundingRadius;
		bool				mBoundsDirty;
        /// Set to false by derived classes that need it
		bool				mBoundsUpdated;
		Camera				*mCurrentCamera;

		unsigned short		mMaterialLodIndex;

        /// Set to false at start of each _updateRenderQueue
		bool				mDirtyAnimation;

		/// False if a technique doesn't support skeletal animation
		bool				mTechnSupportsSkeletal;

		/// Cached distance to last camera for getSquaredViewDepth
		mutable Real mCachedCameraDist;
		/// The camera for which the cached distance is valid
		mutable const Camera *mCachedCamera;

		/// Tells that the list of entity instances with shared transforms has changed
		bool mTransformSharingDirty;

		/// When true remove the memory of the VertexData we've created because no one else will
		bool mRemoveOwnVertexData;
		/// When true remove the memory of the IndexData we've created because no one else will
		bool mRemoveOwnIndexData;

		virtual void setupVertices( const SubMesh* baseSubMesh ) = 0;
		virtual void setupIndices( const SubMesh* baseSubMesh ) = 0;
		virtual void createAllInstancedEntities(void);
		virtual void deleteAllInstancedEntities(void);
		virtual void deleteUnusedInstancedEntities(void);
		/// Creates a new InstancedEntity instance
		virtual InstancedEntity* generateInstancedEntity(size_t num);

		/** Takes an array of 3x4 matrices and makes it camera relative. Note the second argument
			takes number of floats in the array, not number of matrices. Assumes mCachedCamera
			contains the camera which is about to be rendered to.
		*/
		void makeMatrixCameraRelative3x4( float *mat3x4, size_t numFloats );

		/// Returns false on errors that would prevent building this batch from the given submesh
		virtual bool checkSubMeshCompatibility( const SubMesh* baseSubMesh );

		void updateVisibility(void);

		/** @see _defragmentBatch */
		void defragmentBatchNoCull( InstancedEntityVec &usedEntities );

		/** @see _defragmentBatch
			This one takes the entity closest to the minimum corner of the bbox, then starts
			gathering entities closest to this entity. There might be much better algorithms (i.e.
			involving space partition), but this one is simple and works well enough
		*/
		void defragmentBatchDoCull( InstancedEntityVec &usedEntities );

	public:
		InstanceBatch( InstanceManager *creator, MeshPtr &meshReference, const MaterialPtr &material,
						size_t instancesPerBatch, const Mesh::IndexMap *indexToBoneMap,
						const String &batchName );
		virtual ~InstanceBatch();

		MeshPtr& _getMeshRef() { return mMeshReference; }

		/** Raises an exception if trying to change it after being built
		*/
		void _setInstancesPerBatch( size_t instancesPerBatch );

		const Mesh::IndexMap* _getIndexToBoneMap() const { return mIndexToBoneMap; }

		/** Returns true if this technique supports skeletal animation
		@remarks
			A virtual function could have been used, but using a simple variable overriden
			by the derived class is faster than virtual call overhead. And both are clean
			ways of implementing it.
		*/
		bool _supportsSkeletalAnimation() const { return mTechnSupportsSkeletal; }

		/** @see InstanceManager::updateDirtyBatches */
		void _updateBounds(void);

		/** Some techniques have a limit on how many instances can be done.
			Sometimes even depends on the material being used.
			@par
			Note this is a helper function, as such it takes a submesh base to compute
			the parameters, instead of using the object's own. This allows
			querying for a technique without requiering to actually build it.
			@param baseSubMesh The base submesh that will be using to build it.
			@param flags @see InstanceManagerFlags
			@return The max instances limit
		*/
		virtual size_t calculateMaxNumInstances( const SubMesh *baseSubMesh, uint16 flags ) const = 0;

		/** Constructs all the data needed to use this batch, as well as the
			InstanceEntities. Placed here because in the constructor virtual
			tables may not have been yet filled.
			@param baseSubMesh A sub mesh which the instances will be based upon from.
			@remarks
				Call this only ONCE. This is done automatically by Ogre::InstanceManager
				Caller is responsable for freeing buffers in this RenderOperation
				Buffers inside the RenderOp may be null if the built failed.
			@return
				A render operation which is very useful to pass to other InstanceBatches
				(@see buildFrom) so that they share the same vertex buffers and indices,
				when possible
        */
		virtual RenderOperation build( const SubMesh* baseSubMesh );

		/** Instancing consumes significantly more GPU memory than regular rendering
			methods. However, multiple batches can share most, if not all, of the
			vertex & index buffers to save memory.
			Derived classes are free to overload this method to manipulate what to
			reference from Render Op.
			For example, Hardware based instancing uses it's own vertex buffer for the
			last source binding, but shares the other sources.
			@param renderOperation The RenderOp to reference.
			@remarks
				Caller is responsable for freeing buffers passed as input arguments
				This function replaces the need to call build()
        */
		virtual void buildFrom( const SubMesh *baseSubMesh, const RenderOperation &renderOperation );

		const Ogre::MeshPtr& _getMeshReference(void) const { return mMeshReference; }

		/** @return true if it can not create more InstancedEntities
			(Num InstancedEntities == mInstancesPerBatch)
		*/
		bool isBatchFull(void) const { return mUnusedEntities.empty(); }

		/** Returns true if it no instanced entity has been requested or all of them have been removed
		*/
		bool isBatchUnused(void) const { return mUnusedEntities.size() == mInstancedEntities.size(); }

		/** Fills the input vector with the instances that are currently being used or were requested
			Used for defragmentation, @see InstanceManager::defragmentBatches
		*/
		void getInstancedEntitiesInUse( InstancedEntityVec &outEntities );

		/** @see InstanceManager::defragmentBatches
			This function takes InstancedEntities and pushes back all entities it can fit here
			Extra entities in mUnusedEntities are destroyed
			(so that used + unused = mInstancedEntities.size())
			@param optimizeCulling true will call the DoCull version, false the NoCull
			@param Array of InstancedEntities to parent with this batch. Those reparented
			are removed from this input vector
			@remarks:
			This function assumes caller holds data to mInstancedEntities! Otherwise
			you can get memory leaks. Don't call this directly if you don't know what you're doing!
		*/
		void _defragmentBatch( bool optimizeCulling, InstancedEntityVec &usedEntities );

		/** @see InstanceManager::_defragmentBatchDiscard
			Destroys unused entities and clears the mInstancedEntity container which avoids leaving
			dangling pointers from reparented InstancedEntities
			Usually called before deleting this pointer. Don't call directly!
		*/
		void _defragmentBatchDiscard(void);

		/** Called by InstancedEntity(s) to tell us we need to update the bounds
			(we touch the SceneNode so the SceneManager aknowledges such change)
        */
		virtual void _boundsDirty(void);

		/** Tells this batch to stop updating animations, positions, rotations, and display
			all it's active instances. Currently only InstanceBatchHW & InstanceBatchHW_VTF support it.
			This option makes the batch behave pretty much like Static Geometry, but with the GPU RAM
			memory advantages (less VRAM, less bandwidth) and not LOD support. Very useful for
			billboards of trees, repeating vegetation, etc.
			@remarks
				This function moves a lot of processing time from the CPU to the GPU. If the GPU
				is already a bottleneck, you may see a decrease in performance instead!
				Call this function again (with bStatic=true) if you've made a change to an
				InstancedEntity and wish this change to take effect.
				Be sure to call this after you've set all your instances
				@see InstanceBatchHW::setStaticAndUpdate
		*/
		virtual void setStaticAndUpdate( bool bStatic )		{}

		/** Returns true if this batch was set as static. @see setStaticAndUpdate
		*/
		virtual bool isStatic() const						{ return false; }

		/** Returns a pointer to a new InstancedEntity ready to use
			Note it's actually preallocated, so no memory allocation happens at
			this point.
			@remarks
				Returns NULL if all instances are being used
        */
		InstancedEntity* createInstancedEntity();

		/** Removes an InstancedEntity from the scene retrieved with
			getNewInstancedEntity, putting back into a queue
			@remarks
				Throws an exception if the instanced entity wasn't created by this batch
				Removed instanced entities save little CPU time, but _not_ GPU
        */
		void removeInstancedEntity( InstancedEntity *instancedEntity );

		/** Tells whether world bone matrices need to be calculated.
			This does not include bone matrices which are calculated regardless
        */
		virtual bool useBoneWorldMatrices() const { return true; }

		/** Tells that the list of entity instances with shared transforms has changed */
		void _markTransformSharingDirty() { mTransformSharingDirty = true; }

		//Renderable overloads
        /** @copydoc Renderable::getMaterial. */
		const MaterialPtr& getMaterial(void) const		{ return mMaterial; }
        /** @copydoc Renderable::getRenderOperation. */
		void getRenderOperation( RenderOperation& op )	{ op = mRenderOperation; }

        /** @copydoc Renderable::getSquaredViewDepth. */
		Real getSquaredViewDepth( const Camera* cam ) const;
        /** @copydoc Renderable::getLights. */
        const LightList& getLights( void ) const;
        /** @copydoc Renderable::getTechnique. */
		Technique* getTechnique(void) const;

        /** @copydoc MovableObject::getMovableType. */
		const String& getMovableType(void) const;
        /** @copydoc MovableObject::_notifyCurrentCamera. */
		void _notifyCurrentCamera( Camera* cam );
        /** @copydoc MovableObject::getBoundingBox. */
		const AxisAlignedBox& getBoundingBox(void) const;
        /** @copydoc MovableObject::getBoundingRadius. */
		Real getBoundingRadius(void) const;

		virtual void _updateRenderQueue(RenderQueue* queue);
		void visitRenderables( Renderable::Visitor* visitor, bool debugRenderables = false );

        // resolve ambiguity of get/setUserAny due to inheriting from Renderable and MovableObject
        using Renderable::getUserAny;
        using Renderable::setUserAny;
	};
}

#endif