/*
-----------------------------------------------------------------------------
This source file is part of OGRE
    (Object-oriented Graphics Rendering Engine)
For the latest info, see http://www.ogre3d.org/

 Copyright (c) 2000-2014 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 __RenderQueueInvocation_H__
#define __RenderQueueInvocation_H__

#include "OgrePrerequisites.h"
#include "OgreRenderQueueSortingGrouping.h"
#include "OgreHeaderPrefix.h"

namespace Ogre {

    /** \addtogroup Core
    *  @{
    */
    /** \addtogroup RenderSystem
    *  @{
    */
    /** 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 : public RenderQueueAlloc
    {
    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 = BLANKSTRING);
        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<RenderQueueInvocation*> RenderQueueInvocationList;
    typedef VectorIterator<RenderQueueInvocationList> 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 shutdown, 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 : public RenderQueueAlloc
    {
    protected:
        String mName;
        RenderQueueInvocationList mInvocations;
    public:
        RenderQueueInvocationSequence(const String& name);
        ~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
        @return 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);


    };
    /** @} */
    /** @} */

}

#include "OgreHeaderSuffix.h"

#endif

