ruby-ogre 0.0.1-x86-linux

data/deps/include/OGRE/OgreSceneQuery.h

@@ -0,0 +1,564 @@
+/*
+-----------------------------------------------------------------------------
+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 __SceneQuery_H__
+#define __SceneQuery_H__
+
+#include "OgrePrerequisites.h"
+#include "OgreAxisAlignedBox.h"
+#include "OgreSphere.h"
+#include "OgreRay.h"
+#include "OgreRenderOperation.h"
+#include "OgrePlaneBoundedVolume.h"
+
+namespace Ogre {
+
+    // forward declaration
+    class SceneQueryListener;
+	/** \addtogroup Core
+	*  @{
+	*/
+	/** \addtogroup Scene
+	*  @{
+	*/
+	/** A class for performing queries on a scene.
+    @remarks
+        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.
+    @par
+        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.
+    @par
+        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.
+    @par
+        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.
+        SceneManager::createSphereSceneQuery.
+    */
+	class _OgreExport SceneQuery : public SceneMgtAlloc
+    {
+    public:
+        /** This type can be used by collaborating applications & SceneManagers to 
+            agree on the type of world geometry to be returned from queries. Not all
+            these types will be supported by all SceneManagers; once the application
+            has decided which SceneManager specialisation to use, it is expected that 
+            it will know which type of world geometry abstraction is available to it.
+        */
+        enum WorldFragmentType {
+            /// Return no world geometry hits at all
+            WFT_NONE,
+            /// Return pointers to convex plane-bounded regions
+            WFT_PLANE_BOUNDED_REGION,
+            /// Return a single intersection point (typically RaySceneQuery only)
+            WFT_SINGLE_INTERSECTION,
+            /// Custom geometry as defined by the SceneManager
+            WFT_CUSTOM_GEOMETRY,
+            /// General RenderOperation structure
+            WFT_RENDER_OPERATION
+        };
+
+        /** Represents part of the world geometry that is a result of a SceneQuery. 
+        @remarks
+            Since world geometry is normally vast and sprawling, we need a way of
+            retrieving parts of it based on a query. That is what this struct is for;
+            note there are potentially as many data structures for world geometry as there
+            are SceneManagers, however this structure includes a few common abstractions as 
+            well as a more general format.
+        @par
+            The type of world fragment that is returned from a query depends on the
+            SceneManager, and the option set using SceneQuery::setWorldFragmentType. 
+            You can see what fragment types are supported on the query in question by
+            calling SceneQuery::getSupportedWorldFragmentTypes().
+        */
+        struct WorldFragment {
+            /// The type of this world fragment
+            WorldFragmentType fragmentType;
+            /// Single intersection point, only applicable for WFT_SINGLE_INTERSECTION
+            Vector3 singleIntersection;
+            /// Planes bounding a convex region, only applicable for WFT_PLANE_BOUNDED_REGION
+            list<Plane>::type* planes;
+            /// Custom geometry block, only applicable for WFT_CUSTOM_GEOMETRY
+            void* geometry;
+            /// General render operation structure, fallback if nothing else is available
+            RenderOperation* renderOp;
+            
+        };
+    protected:
+        SceneManager* mParentSceneMgr;
+        uint32 mQueryMask;
+		uint32 mQueryTypeMask;
+        set<WorldFragmentType>::type mSupportedWorldFragments;
+        WorldFragmentType mWorldFragmentType;
+    
+    public:
+        /** Standard constructor, should be called by SceneManager. */
+        SceneQuery(SceneManager* mgr);
+        virtual ~SceneQuery();
+
+        /** Sets the mask for results of this query.
+        @remarks
+            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.
+        @remarks
+            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;
+
+		/** Tells the query what kind of world geometry to return from queries;
+            often the full renderable geometry is not what is needed. 
+        @remarks
+            The application receiving the world geometry is expected to know 
+            what to do with it; inevitably this means that the application must 
+            have knowledge of at least some of the structures
+            used by the custom SceneManager.
+        @par
+            The default setting is WFT_NONE.
+        */
+        virtual void setWorldFragmentType(enum WorldFragmentType wft);
+
+        /** Gets the current world fragment types to be returned from the query. */
+        virtual WorldFragmentType getWorldFragmentType(void) const;
+
+        /** Returns the types of world fragments this query supports. */
+        virtual const set<WorldFragmentType>::type* getSupportedWorldFragmentTypes(void) const
+            {return &mSupportedWorldFragments;}
+
+        
+    };
+
+    /** This optional class allows you to receive per-result callbacks from
+        SceneQuery executions instead of a single set of consolidated results.
+    @remarks
+        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.
+        @remarks
+            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.
+        @remarks
+            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) = 0;
+
+    };
+
+    typedef list<MovableObject*>::type SceneQueryResultMovableList;
+    typedef list<SceneQuery::WorldFragment*>::type 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;
+        /// List of world fragments
+		SceneQueryResultWorldFragmentList worldFragments;
+    };
+
+    /** Abstract class defining a query which returns single results from a region. 
+    @remarks
+        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
+    {
+    protected:
+        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.
+        @remarks
+            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. 
+        @remarks
+            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. 
+        */
+        virtual SceneQueryResult& getLastResults(void) const;
+        /** Clears the results of the last query execution.
+        @remarks
+            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.
+        */
+        virtual void clearResults(void);
+
+        /** Self-callback in order to deal with execute which returns collection. */
+        bool queryResult(MovableObject* first);
+        /** Self-callback in order to deal with execute which returns collection. */
+        bool queryResult(SceneQuery::WorldFragment* fragment);
+    };
+
+    /** 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;
+
+    };
+
+
+    /*
+    /// Specialises the SceneQuery class for querying within a pyramid. 
+    class _OgreExport PyramidSceneQuery : public RegionSceneQuery
+    {
+    public:
+        PyramidSceneQuery(SceneManager* mgr);
+        virtual ~PyramidSceneQuery();
+    };
+    */
+
+    /** Alternative listener class for dealing with RaySceneQuery.
+    @remarks
+        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.
+        @remarks
+            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. 
+        @remarks
+            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;
+        /// 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 vector<RaySceneQueryResultEntry>::type RaySceneQueryResult;
+
+    /** Specialises the SceneQuery class for querying along a ray. */
+    class _OgreExport RaySceneQuery : public SceneQuery, public RaySceneQueryListener
+    {
+    protected:
+        Ray mRay;
+        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.
+        @remarks
+            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.
+        @remarks
+            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. 
+        @remarks
+            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. 
+        */
+        virtual RaySceneQueryResult& getLastResults(void);
+        /** Clears the results of the last query execution.
+        @remarks
+            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.
+        */
+        virtual void clearResults(void);
+
+        /** Self-callback in order to deal with execute which returns collection. */
+        bool queryResult(MovableObject* obj, Real distance);
+        /** Self-callback in order to deal with execute which returns collection. */
+        bool queryResult(SceneQuery::WorldFragment* fragment, Real distance);
+
+
+
+
+    };
+
+    /** Alternative listener class for dealing with IntersectionSceneQuery.
+    @remarks
+        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.
+        @remarks
+            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. 
+        @remarks
+            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 list<SceneQueryMovableObjectPair>::type SceneQueryMovableIntersectionList;
+    typedef list<SceneQueryMovableObjectWorldFragmentPair>::type 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.
+    @remarks
+        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 
+    {
+    protected:
+        IntersectionSceneQueryResult* mLastResult;
+    public:
+        IntersectionSceneQuery(SceneManager* mgr);
+        virtual ~IntersectionSceneQuery();
+
+        /** Executes the query, returning the results back in one list.
+        @remarks
+            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. 
+        @remarks
+            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.
+        @remarks
+            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.
+        */
+        virtual void clearResults(void);
+
+        /** Self-callback in order to deal with execute which returns collection. */
+        bool queryResult(MovableObject* first, MovableObject* second);
+        /** Self-callback in order to deal with execute which returns collection. */
+        bool queryResult(MovableObject* movable, SceneQuery::WorldFragment* fragment);
+    };
+    
+	/** @} */
+	/** @} */
+
+}
+    
+
+
+#endif