<commit_before>/*
-----------------------------------------------------------------------------
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 Tor<NAME> 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
    *  @{
    */
    /** 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
            std::vector<Plane>* 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;
        std::set<WorldFragmentType> 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 std::set<WorldFragmentType>* 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.<commit_msg>Docs: improve SceneQuery documentation<commit_after>/*
-----------------------------------------------------------------------------
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 <NAME>

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
    *  @{
    */
    /** 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
    {
    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.

            @note only supported by the BspSceneManager
        */
        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
            std::vector<Plane>* 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;
        std::set<WorldFragmentType> mSupportedWorldFragments;
        WorldFragmentType mWorldFragmentType;
    
    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;

        /** Tells the query what kind of world geometry to return from queries;
            often the full renderable geometry is not what is needed. 

            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 std::set<WorldFragmentType>* 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.
{'fraction_non_alphanumeric': 0.05911216302026208, 'fraction_numerical': 0.0025399757547768863, 'mean_word_length': 2.3710838684568984, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1862016', 'n_tokens_mistral': 3986, 'n_tokens_neox': 3820, 'n_words': 2033}