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

#include "OgrePrerequisites.h"
#include "OgreSphere.h"
#include "OgreRay.h"
#include "OgreHeaderPrefix.h"

namespace Ogre {
    /** \addtogroup Core
    *  @{
    */
    /** \addtogroup Scene
    *  @{
    */
    struct WorldFragment;

    /** A class for performing queries on a scene.

        This is an abstract class for performing a query on a scene, i.e. to retrieve
        a list of objects and/or world geometry sections which are potentially intersecting a
        given region. Note the use of the word 'potentially': the results of a scene query
        are generated based on bounding volumes, and as such are not correct at a triangle
        level; the user of the SceneQuery is expected to filter the results further if
        greater accuracy is required.

        Different SceneManagers will implement these queries in different ways to
        exploit their particular scene organisation, and thus will provide their own
        concrete subclasses. In fact, these subclasses will be derived from subclasses
        of this class rather than directly because there will be region-type classes
        in between.

        These queries could have just been implemented as methods on the SceneManager,
        however, they are wrapped up as objects to allow 'compilation' of queries
        if deemed appropriate by the implementation; i.e. each concrete subclass may
        precalculate information (such as fixed scene partitions involved in the query)
        to speed up the repeated use of the query.

        You should never try to create a SceneQuery object yourself, they should be created
        using the SceneManager interfaces for the type of query required, e.g.
        @ref SceneManager::createSphereQuery.
    */
    class _OgreExport SceneQuery : public SceneMgtAlloc
    {
    protected:
        SceneManager* mParentSceneMgr;
        uint32 mQueryMask;
        uint32 mQueryTypeMask;
    
    public:
        /** Standard constructor, should be called by SceneManager. */
        SceneQuery(SceneManager* mgr);
        virtual ~SceneQuery();

        /** Sets the mask for results of this query.

            This method allows you to set a 'mask' to limit the results of this
            query to certain types of result. The actual meaning of this value is
            up to the application; basically MovableObject instances will only be returned
            from this query if a bitwise AND operation between this mask value and the
            MovableObject::getQueryFlags value is non-zero. The application will
            have to decide what each of the bits means.
        */
        virtual void setQueryMask(uint32 mask);
        /** Returns the current mask for this query. */
        virtual uint32 getQueryMask(void) const;

        /** Sets the type mask for results of this query.

            This method allows you to set a 'type mask' to limit the results of this
            query to certain types of objects. Whilst setQueryMask deals with flags
            set per instance of object, this method deals with setting a mask on 
            flags set per type of object. Both may exclude an object from query
            results.
        */
        virtual void setQueryTypeMask(uint32 mask);
        /** Returns the current mask for this query. */
        virtual uint32 getQueryTypeMask(void) const;

        typedef Ogre::WorldFragment WorldFragment;
    };

    /** This optional class allows you to receive per-result callbacks from
        SceneQuery executions instead of a single set of consolidated results.

        You should override this with your own subclass. Note that certain query
        classes may refine this listener interface.
    */
    class _OgreExport SceneQueryListener
    {
    public:
        virtual ~SceneQueryListener() { }
        /** Called when a MovableObject is returned by a query.

            The implementor should return 'true' to continue returning objects,
            or 'false' to abandon any further results from this query.
        */
        virtual bool queryResult(MovableObject* object) = 0;
        /** Called when a WorldFragment is returned by a query.

            The implementor should return 'true' to continue returning objects,
            or 'false' to abandon any further results from this query.
        */
        virtual bool queryResult(SceneQuery::WorldFragment* fragment) { return false; }

    };

    typedef std::list<MovableObject*> SceneQueryResultMovableList;
    typedef std::list<SceneQuery::WorldFragment*> SceneQueryResultWorldFragmentList;
    /** Holds the results of a scene query. */
    struct _OgreExport SceneQueryResult : public SceneMgtAlloc
    {
        /// List of movable objects in the query (entities, particle systems etc)
        SceneQueryResultMovableList movables;
        /// Only relevant for the BSP Scene Manager. List of world fragments
        SceneQueryResultWorldFragmentList worldFragments;
    };

    /** Abstract class defining a query which returns single results from a region. 

        This class is simply a generalisation of the subtypes of query that return 
        a set of individual results in a region. See the SceneQuery class for abstract
        information, and subclasses for the detail of each query type.
    */
    class _OgreExport RegionSceneQuery
        : public SceneQuery, public SceneQueryListener
    {
        SceneQueryResult mLastResult;
    public:
        /** Standard constructor, should be called by SceneManager. */
        RegionSceneQuery(SceneManager* mgr);
        virtual ~RegionSceneQuery();
        /** Executes the query, returning the results back in one list.

            This method executes the scene query as configured, gathers the results
            into one structure and returns a reference to that structure. These
            results will also persist in this query object until the next query is
            executed, or clearResults() is called. An more lightweight version of
            this method that returns results through a listener is also available.
        */
        virtual SceneQueryResult& execute(void);

        /** Executes the query and returns each match through a listener interface. 

            Note that this method does not store the results of the query internally 
            so does not update the 'last result' value. This means that this version of
            execute is more lightweight and therefore more efficient than the version 
            which returns the results as a collection.
        */
        virtual void execute(SceneQueryListener* listener) = 0;
        
        /** Gets the results of the last query that was run using this object, provided
            the query was executed using the collection-returning version of execute. 
        */
        const SceneQueryResult& getLastResults(void) const;
        /** Clears the results of the last query execution.

            You only need to call this if you specifically want to free up the memory
            used by this object to hold the last query results. This object clears the
            results itself when executing and when destroying itself.
        */
        void clearResults(void);

        /** Self-callback in order to deal with execute which returns collection. */
        bool queryResult(MovableObject* first) override;
        /** Self-callback in order to deal with execute which returns collection. */
        bool queryResult(SceneQuery::WorldFragment* fragment) override;
    };

    /** Specialises the SceneQuery class for querying within an axis aligned box. */
    class _OgreExport AxisAlignedBoxSceneQuery : public RegionSceneQuery
    {
    protected:
        AxisAlignedBox mAABB;
    public:
        AxisAlignedBoxSceneQuery(SceneManager* mgr);
        virtual ~AxisAlignedBoxSceneQuery();

        /** Sets the size of the box you wish to query. */
        void setBox(const AxisAlignedBox& box);

        /** Gets the box which is being used for this query. */
        const AxisAlignedBox& getBox(void) const;

    };

    /** Specialises the SceneQuery class for querying within a sphere. */
    class _OgreExport SphereSceneQuery : public RegionSceneQuery
    {
    protected:
        Sphere mSphere;
    public:
        SphereSceneQuery(SceneManager* mgr);
        virtual ~SphereSceneQuery();
        /** Sets the sphere which is to be used for this query. */
        void setSphere(const Sphere& sphere);

        /** Gets the sphere which is being used for this query. */
        const Sphere& getSphere() const;

    };

    /** Specialises the SceneQuery class for querying within a plane-bounded volume. 
    */
    class _OgreExport PlaneBoundedVolumeListSceneQuery : public RegionSceneQuery
    {
    protected:
        PlaneBoundedVolumeList mVolumes;
    public:
        PlaneBoundedVolumeListSceneQuery(SceneManager* mgr);
        virtual ~PlaneBoundedVolumeListSceneQuery();
        /** Sets the volume which is to be used for this query. */
        void setVolumes(const PlaneBoundedVolumeList& volumes);

        /** Gets the volume which is being used for this query. */
        const PlaneBoundedVolumeList& getVolumes() const;

    };

    /** Alternative listener class for dealing with RaySceneQuery.

        Because the RaySceneQuery returns results in an extra bit of information, namely
        distance, the listener interface must be customised from the standard SceneQueryListener.
    */
    class _OgreExport RaySceneQueryListener 
    {
    public:
        virtual ~RaySceneQueryListener() { }
        /** Called when a movable objects intersects the ray.

            As with SceneQueryListener, the implementor of this method should return 'true'
            if further results are required, or 'false' to abandon any further results from
            the current query.
        */
        virtual bool queryResult(MovableObject* obj, Real distance) = 0;

        /** Called when a world fragment is intersected by the ray. 

            As with SceneQueryListener, the implementor of this method should return 'true'
            if further results are required, or 'false' to abandon any further results from
            the current query.
        */
        virtual bool queryResult(SceneQuery::WorldFragment* fragment, Real distance) = 0;

    };
      
    /** This struct allows a single comparison of result data no matter what the type */
    struct _OgreExport RaySceneQueryResultEntry
    {
        /// Distance along the ray
        Real distance;
        /// The movable, or NULL if this is not a movable result
        MovableObject* movable;
        /// Only relevant for the BSP Scene Manager. The world fragment, or NULL if this is not a fragment result
        SceneQuery::WorldFragment* worldFragment;
        /// Comparison operator for sorting
        bool operator < (const RaySceneQueryResultEntry& rhs) const
        {
            return this->distance < rhs.distance;
        }

    };
    typedef std::vector<RaySceneQueryResultEntry> RaySceneQueryResult;

    /** Specialises the SceneQuery class for querying along a ray. */
    class _OgreExport RaySceneQuery : public SceneQuery, public RaySceneQueryListener
    {
    protected:
        Ray mRay;
    private:
        bool mSortByDistance;
        ushort mMaxResults;
        RaySceneQueryResult mResult;

    public:
        RaySceneQuery(SceneManager* mgr);
        virtual ~RaySceneQuery();
        /** Sets the ray which is to be used for this query. */
        virtual void setRay(const Ray& ray);
        /** Gets the ray which is to be used for this query. */
        virtual const Ray& getRay(void) const;
        /** Sets whether the results of this query will be sorted by distance along the ray.

            Often you want to know what was the first object a ray intersected with, and this 
            method allows you to ask the query to sort the results so that the nearest results
            are listed first.
        @par
            Note that because the query returns results based on bounding volumes, the ray may not
            actually intersect the detail of the objects returned from the query, just their 
            bounding volumes. For this reason the caller is advised to use more detailed 
            intersection tests on the results if a more accurate result is required; OGRE uses 
            bounds checking in order to give the most speedy results since not all applications 
            need extreme accuracy.
        @param sort If true, results will be sorted.
        @param maxresults If sorting is enabled, this value can be used to constrain the maximum number
            of results that are returned. Please note (as above) that the use of bounding volumes mean that
            accuracy is not guaranteed; if in doubt, allow more results and filter them in more detail.
            0 means unlimited results.
        */
        virtual void setSortByDistance(bool sort, ushort maxresults = 0);
        /** Gets whether the results are sorted by distance. */
        virtual bool getSortByDistance(void) const;
        /** Gets the maximum number of results returned from the query (only relevant if 
        results are being sorted) */
        virtual ushort getMaxResults(void) const;
        /** Executes the query, returning the results back in one list.

            This method executes the scene query as configured, gathers the results
            into one structure and returns a reference to that structure. These
            results will also persist in this query object until the next query is
            executed, or clearResults() is called. An more lightweight version of
            this method that returns results through a listener is also available.
        */
        virtual RaySceneQueryResult& execute(void);

        /** Executes the query and returns each match through a listener interface. 

            Note that this method does not store the results of the query internally 
            so does not update the 'last result' value. This means that this version of
            execute is more lightweight and therefore more efficient than the version 
            which returns the results as a collection.
        */
        virtual void execute(RaySceneQueryListener* listener) = 0;

        /** Gets the results of the last query that was run using this object, provided
            the query was executed using the collection-returning version of execute. 
        */
        const RaySceneQueryResult& getLastResults(void) const;
        /** Clears the results of the last query execution.

            You only need to call this if you specifically want to free up the memory
            used by this object to hold the last query results. This object clears the
            results itself when executing and when destroying itself.
        */
        void clearResults(void);

        /** Self-callback in order to deal with execute which returns collection. */
        bool queryResult(MovableObject* obj, Real distance) override;
        /** Self-callback in order to deal with execute which returns collection. */
        bool queryResult(SceneQuery::WorldFragment* fragment, Real distance) override;




    };

    /** Alternative listener class for dealing with IntersectionSceneQuery.

        Because the IntersectionSceneQuery returns results in pairs, rather than singularly,
        the listener interface must be customised from the standard SceneQueryListener.
    */
    class _OgreExport IntersectionSceneQueryListener 
    {
    public:
        virtual ~IntersectionSceneQueryListener() { }
        /** Called when 2 movable objects intersect one another.

            As with SceneQueryListener, the implementor of this method should return 'true'
            if further results are required, or 'false' to abandon any further results from
            the current query.
        */
        virtual bool queryResult(MovableObject* first, MovableObject* second) = 0;

        /** Called when a movable intersects a world fragment. 

            As with SceneQueryListener, the implementor of this method should return 'true'
            if further results are required, or 'false' to abandon any further results from
            the current query.
        */
        virtual bool queryResult(MovableObject* movable, SceneQuery::WorldFragment* fragment) = 0;

        /* NB there are no results for world fragments intersecting other world fragments;
           it is assumed that world geometry is either static or at least that self-intersections
           are irrelevant or dealt with elsewhere (such as the custom scene manager) */
        
    
    };
        
    typedef std::pair<MovableObject*, MovableObject*> SceneQueryMovableObjectPair;
    typedef std::pair<MovableObject*, SceneQuery::WorldFragment*> SceneQueryMovableObjectWorldFragmentPair;
    typedef std::list<SceneQueryMovableObjectPair> SceneQueryMovableIntersectionList;
    typedef std::list<SceneQueryMovableObjectWorldFragmentPair> SceneQueryMovableWorldFragmentIntersectionList;
    /** Holds the results of an intersection scene query (pair values). */
    struct _OgreExport IntersectionSceneQueryResult : public SceneMgtAlloc
    {
        /// List of movable / movable intersections (entities, particle systems etc)
        SceneQueryMovableIntersectionList movables2movables;
        /// List of movable / world intersections
        SceneQueryMovableWorldFragmentIntersectionList movables2world;
        
        

    };

    /** Separate SceneQuery class to query for pairs of objects which are
        possibly intersecting one another.

        This SceneQuery subclass considers the whole world and returns pairs of objects
        which are close enough to each other that they may be intersecting. Because of
        this slightly different focus, the return types and listener interface are
        different for this class.
    */
    class _OgreExport IntersectionSceneQuery
        : public SceneQuery, public IntersectionSceneQueryListener 
    {
        IntersectionSceneQueryResult* mLastResult;
    public:
        IntersectionSceneQuery(SceneManager* mgr);
        virtual ~IntersectionSceneQuery();

        /** Executes the query, returning the results back in one list.

            This method executes the scene query as configured, gathers the results
            into one structure and returns a reference to that structure. These
            results will also persist in this query object until the next query is
            executed, or clearResults() is called. An more lightweight version of
            this method that returns results through a listener is also available.
        */
        virtual IntersectionSceneQueryResult& execute(void);

        /** Executes the query and returns each match through a listener interface. 

            Note that this method does not store the results of the query internally 
            so does not update the 'last result' value. This means that this version of
            execute is more lightweight and therefore more efficient than the version 
            which returns the results as a collection.
        */
        virtual void execute(IntersectionSceneQueryListener* listener) = 0;

        /** Gets the results of the last query that was run using this object, provided
            the query was executed using the collection-returning version of execute. 
        */
        virtual IntersectionSceneQueryResult& getLastResults(void) const;
        /** Clears the results of the last query execution.

            You only need to call this if you specifically want to free up the memory
            used by this object to hold the last query results. This object clears the
            results itself when executing and when destroying itself.
        */
        void clearResults(void);

        /** Self-callback in order to deal with execute which returns collection. */
        bool queryResult(MovableObject* first, MovableObject* second) override;
        /** Self-callback in order to deal with execute which returns collection. */
        bool queryResult(MovableObject* movable, SceneQuery::WorldFragment* fragment) override;
    };
    
    /** @} */
    /** @} */

}
    
#include "OgreHeaderSuffix.h"

#endif
