/* ----------------------------------------------------------------------------- This source file is part of OGRE (Object-oriented Graphics Rendering Engine) For the latest info, see http://www.ogre3d.org/ Copyright (c) 2000-2005 The OGRE Team Also see acknowledgements in Readme.html This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, or go to http://www.gnu.org/copyleft/lesser.txt. You may alternatively use this source under the terms of a specific version of the OGRE Unrestricted License provided you have obtained such a license from Torus Knot Software Ltd. ----------------------------------------------------------------------------- */ #ifndef __RenderQueueInvocation_H__ #define __RenderQueueInvocation_H__ #include "OgrePrerequisites.h" #include "OgreRenderQueueSortingGrouping.h" #include "OgreIteratorWrappers.h" namespace Ogre { /** Class representing the invocation of queue groups in a RenderQueue. @remarks The default behaviour for OGRE's render queue is to render each queue group in turn, dealing with shadows automatically, and rendering solids in grouped passes, followed by transparent objects in descending order. This class, together with RenderQueueInvocationSequence and the ability to associate one with a Viewport, allows you to change that behaviour and render queue groups in arbitrary sequence, repeatedly, and to skip shadows, change the ordering of solids, or even prevent OGRE controlling the render state during a particular invocation for special effects. @par Note that whilst you can change the ordering of rendering solids, you can't change the ordering on transparent objects, since to do this would cause them to render incorrectly. @par As well as using this class directly and using the options it provides you with, you can also provide subclasses of it to a RenderQueueInvocationSequence instance if you want to gain ultimate control. @note Invocations will be skipped if there are scene-level options preventing them being rendered - for example special-case render queues and render queue listeners that dictate this. */ class _OgreExport RenderQueueInvocation { protected: /// Target queue group uint8 mRenderQueueGroupID; /// Invocation identifier - used in listeners String mInvocationName; /// Solids ordering mode QueuedRenderableCollection::OrganisationMode mSolidsOrganisation; /// Suppress shadows processing in this invocation? bool mSuppressShadows; /// Suppress OGRE's render state management? bool mSuppressRenderStateChanges; public: /** Constructor @param renderQueueGroupID ID of the queue this will target @param invocationName Optional name to uniquely identify this invocation from others in a RenderQueueListener */ RenderQueueInvocation(uint8 renderQueueGroupID, const String& invocationName = StringUtil::BLANK); virtual ~RenderQueueInvocation(); /// Get the render queue group id virtual uint8 getRenderQueueGroupID(void) const { return mRenderQueueGroupID; } /// Get the invocation name (may be blank if not set by creator) virtual const String& getInvocationName(void) const { return mInvocationName; } /** Set the organisation mode being used for solids in this queue group invocation. */ virtual void setSolidsOrganisation( QueuedRenderableCollection::OrganisationMode org) { mSolidsOrganisation = org; } /** Get the organisation mode being used for solids in this queue group invocation. */ virtual QueuedRenderableCollection::OrganisationMode getSolidsOrganisation(void) const { return mSolidsOrganisation; } /** Sets whether shadows are suppressed when invoking this queue. @remarks When doing effects you often will want to suppress shadow processing if shadows will already have been done by a previous render. */ virtual void setSuppressShadows(bool suppress) { mSuppressShadows = suppress; } /** Gets whether shadows are suppressed when invoking this queue. */ virtual bool getSuppressShadows(void) const { return mSuppressShadows; } /** Sets whether render state changes are suppressed when invoking this queue. @remarks When doing special effects you may want to set up render state yourself and have it apply for the entire rendering of a queue. In that case, you should call this method with a parameter of 'true', and use a RenderQueueListener to set the render state directly on RenderSystem yourself before the invocation. @par Suppressing render state changes is only intended for advanced use, don't use it if you're unsure of the effect. The only RenderSystem calls made are to set the world matrix for each object (note - view an projection matrices are NOT SET - they are under your control) and to render the object; it is up to the caller to do everything else, including enabling any vertex / fragment programs and updating their parameter state, and binding parameters to the RenderSystem. We advise you use a RenderQueueListener in order to get a notification when this invocation is going to happen (use an invocation name to identify it if you like), at which point you can set the state you need to apply before the objects are rendered. */ virtual void setSuppressRenderStateChanges(bool suppress) { mSuppressRenderStateChanges = suppress; } /** Gets whether shadows are suppressed when invoking this queue. */ virtual bool getSuppressRenderStateChanges(void) const { return mSuppressRenderStateChanges; } /** Invoke this class on a concrete queue group. @remarks Implementation will send the queue group to the target scene manager after doing what it needs to do. */ virtual void invoke(RenderQueueGroup* group, SceneManager* targetSceneManager); /// Invocation identifier for shadows static String RENDER_QUEUE_INVOCATION_SHADOWS; }; /// List of RenderQueueInvocations typedef std::vector RenderQueueInvocationList; typedef VectorIterator RenderQueueInvocationIterator; /** Class to hold a linear sequence of RenderQueueInvocation objects. @remarks This is just a simple data holder class which contains a list of RenderQueueInvocation objects representing the sequence of invocations made for a viewport. It's only real purpose is to ensure that RenderQueueInvocation instances are deleted on shudown, since you can provide your own subclass instances on RenderQueueInvocation. Remember that any invocation instances you give to this class will be deleted by it when it is cleared / destroyed. */ class _OgreExport RenderQueueInvocationSequence { protected: String mName; RenderQueueInvocationList mInvocations; public: RenderQueueInvocationSequence(const String& name); virtual ~RenderQueueInvocationSequence(); /** Get the name of this sequence. */ const String& getName(void) const { return mName; } /** Add a standard invocation to the sequence. @param renderQueueGroupID The ID of the render queue group @param invocationName Optional name to identify the invocation, useful for listeners if a single queue group is invoked more than once @returns A new RenderQueueInvocatin instance which you may customise */ RenderQueueInvocation* add(uint8 renderQueueGroupID, const String& invocationName); /** Add a custom invocation to the sequence. @remarks Use this to add your own custom subclasses of RenderQueueInvocation to the sequence; just remember that this class takes ownership of deleting this pointer when it is cleared / destroyed. */ void add(RenderQueueInvocation* i); /** Get the number of invocations in this sequence. */ size_t size(void) const { return mInvocations.size(); } /** Clear and delete all invocations in this sequence. */ void clear(void); /** Gets the details of an invocation at a given index. */ RenderQueueInvocation* get(size_t index); /** Removes (and deletes) an invocation by index. */ void remove(size_t index); /** Get an iterator over the invocations. */ RenderQueueInvocationIterator iterator(void); }; } #endif