MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
rayquerytool.h
1 // © Copyright 2010 - 2014 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 #ifndef _rayquerytool_h
41 #define _rayquerytool_h
42 
43 #include "datatypes.h"
44 #include "crossplatformexport.h"
45 #include "vector3.h"
46 
47 namespace Ogre
48 {
49  class RaySceneQuery;
50  class Vector3;
51  class Quaternion;
52  class Entity;
53 }
54 
55 namespace Mezzanine
56 {
57  class Plane;
58  class Ray;
59  class WorldObject;
60  ///////////////////////////////////////////////////////////////////////////////
61  /// @class RayQueryTool
62  /// @headerfile rayquerytool.h
63  /// @brief This provides a number of optional tools for working with a Mezzanine::World
64  /// @details Currently this allows for more seamless mouse use, including 'picking'
65  /// of objects with the mouse, and associated functionality.
66  ///////////////////////////////////////
67  class MEZZ_LIB RayQueryTool// : public InputQueryTool
68  {
69  private:
70  /// @brief True if the last Query yielded a meaningful Result.
71  bool ValidResult;
72  /// @brief An Offset or location from something meaningful to the last query.
73  Vector3 Offset;
74  /// @brief If there is an WorldObject result to a query the result will be stored in this.
75  /// @warning This is weak reference, Some other system could delete out from under us and we cannot delete this.
76  WorldObject* IntersectedObject;
77 
78  public:
79 
80  /// @brief Create a RayQueryTool ready for querying
81  RayQueryTool();
82 
83  ///////////////////////////////////////////////////////////////////////////////
84  // Query Results
85  ///////////////////////////////////////
86  /// @brief Clears an previously stored return values.
87  /// @brief returns false.
88  Boolean ClearReturns();
89  /// @brief Check to see if the last query found anything.
90  /// @return True if something was found, false otherwise.
91  Boolean LastQueryResultsValid() const;
92  /// @brief Get an offset from the last query. Depending on the last query, this could be an Offset from a variety of things.
93  /// @return A Vector3 if the last query worked and returns an Offset, A empty vector otherwise. Use LastQueryResultsValid() Prior to this.
94  Vector3 LastQueryResultsOffset() const;
95  /// @brief It is common to ray query for WorldObjects, if so the results can be retrieved with this.
96  /// @return A pointer to an WorldObject if the last query returns a WorldObject and worked, a Null pointer otherwise. Use LastQueryResultsValid() Prior to this.
97  /// @warning Does not confer ownership of WorldObject, do not delete pointers returned by this unless you have taken special steps.
98  WorldObject* LastQueryResultsObjectPtr() const;
99 
100  protected:
101  ///////////////////////////////////////////////////////////////////////////////
102  // Query Helpers
103  ///////////////////////////////////////
104 
105 
106  public:
107  ///////////////////////////////////////////////////////////////////////////////
108  // Ray Queries
109  ///////////////////////////////////////
110  /// @brief This will find the first Object to intesect the Given ray.
111  /// @details This use the graphics subsystem to cast a ray in the world. If the ray passes through any the triangles in an actor
112  /// This will return that actor. This function runs in linear time relative to the amount of triangles in 3d meshes near the the
113  /// ray being cast. This will start at ray.from and go to ray.to .
114  /// @param ActorRay The Ray to search along.
115  /// @param ObjectFlags A whole comprising all the valid objects to be checked in the scene.
116  /// See WorldAndSceneObjectType in enumerations.h for a listing of objects to use as flags.
117  /// @return True if something is found, false otherwise. Use LastQueryResultsOffset() and LastQueryResultsActorPtr() for more details.
118  Boolean GetFirstObjectOnRayByPolygon(Ray ObjectRay, Whole ObjectFlags);
119 
120  /// @brief Partially implemented. This should find the first Object that is on or almost on the a given Ray.
121  /// @details This casts a ray through the gameworld. The first actor with an Axis Aligned Bounding Box that intersects that ray is returned.
122  /// Presently this is untested and does not return the Offset of the intersection. This should perform faster than WorldQueryTool::GetFirstActorOnRayByPolygon
123  /// but not by a known amount.
124  /// @param ActorRay The Ray to search along.
125  /// @param ObjectFlags A whole comprising all the valid objects to be checked in the scene.
126  /// See WorldAndSceneObjectType in enumerations.h for a listing of objects to use as flags.
127  /// @return True if something is found, false otherwise. Use LastQueryResultsActorPtr() for more details. Any return Offset is empty
128  Boolean GetFirstObjectOnRayByAABB(Ray ObjectRay, Whole ObjectFlags);
129 
130  /// @brief Where does this Ray Meet this Plane?
131  /// @details This does some fancy math to return the point where the ray and the plane intersent.
132  /// @param QueryRay This is the Ray that could intersent the plane
133  /// @param QueryPlane This is the plane to be interesected.
134  /// @return True if something is found, false otherwise. Use LastQueryResultsOffset() for more details. Any return Actor Pointer is NULL;
135  Boolean RayPlaneIntersection(const Ray& QueryRay, const Plane& QueryPlane);
136 
137  /// @brief Get a Ray from the current viewport, following the mouse
138  /// @details This calls on the graphics subsystem to get a ray from the location of the current camera
139  /// @param Length how long of a ray do you want? Thsi defaults to 1000
140  /// @return This returns a ray that matches originates at the camera and goes out in 3d space behind the mouse pointer.
141  static Ray GetMouseRay(Real Length=1000);
142 
143  ///////////////////////////////////////////////////////////////////////////////
144  // Serialization
145 
146  /// @brief Convert this class to an XML::Node ready for serialization
147  /// @param CurrentRoot The point in the XML hierarchy that all this vector3 should be appended to.
148  void ProtoSerialize(XML::Node& CurrentRoot) const;
149  /// @brief Take the data stored in an XML and overwrite this instance of this object with it
150  /// @param OneNode and XML::Node containing the data.
151  void ProtoDeSerialize(const XML::Node& OneNode);
152  /// @brief Get the name of the the XML tag this class will leave behind as its instances are serialized.
153  /// @return A string containing "Vector3"
154  static String SerializableName();
155  };//RayQueryTool
156 }//Mezzanine
157 
158 #endif