1/*
2 * Copyright (c) 2008-2015, NVIDIA CORPORATION. All rights reserved.
3 *
4 * NVIDIA CORPORATION and its licensors retain all intellectual property
5 * and proprietary rights in and to this software, related documentation
6 * and any modifications thereto. Any use, reproduction, disclosure or
7 * distribution of this software and related documentation without an express
8 * license agreement from NVIDIA CORPORATION is strictly prohibited.
9 */
10// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
11// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
12
13
14#ifndef PX_PHYSICS_SPATIAL_INDEX
15#define PX_PHYSICS_SPATIAL_INDEX
16/** \addtogroup physics
17@{ */
18
19#include "PxPhysXConfig.h"
20#include "foundation/PxTransform.h"
21#include "geometry/PxGeometry.h"
22#include "PxQueryReport.h"
23
24#ifndef PX_DOXYGEN
25namespace physx
26{
27#endif
28
29typedef PxU32 PxSpatialIndexItemId;
30static const PxSpatialIndexItemId PX_SPATIAL_INDEX_INVALID_ITEM_ID = 0xffffffff;
31
32
33class PxSpatialIndexItem
34{
35};
36
37/**
38\brief Callback class for overlap queries against PxSpatialIndex
39
40@see PxSpatialIndex
41*/
42struct PxSpatialOverlapCallback
43{
44
45 /**
46 \brief callback method invoked when an overlap query hits an item in a PxSpatialIndex structure.
47
48 \param[in] item the item that was hit.
49 \return true if the query should continue, false if it should stop
50 */
51
52 virtual PxAgain onHit(PxSpatialIndexItem& item) = 0;
53
54 virtual ~PxSpatialOverlapCallback() {}
55};
56
57/**
58\brief Callback class for raycast and sweep queries against PxSpatialIndex
59
60@see PxSpatialIndex
61*/
62struct PxSpatialLocationCallback
63{
64 /**
65 \brief callback method invoked when a sweep or raycast query hits an item in a PxSpatialIndex structure.
66
67 \param[in] item the item that was hit.
68 \param[in] distance the current maximum distance of the query.
69 \param[out] shrunkDistance the updated maximum distance of the query. This must be no more than the current maximum distance.
70
71 \return true if the query should continue, false if it should stop
72
73 @see PxAgain
74 */
75 virtual PxAgain onHit(PxSpatialIndexItem& item, PxReal distance, PxReal& shrunkDistance) = 0;
76
77 virtual ~PxSpatialLocationCallback() {}
78};
79
80
81
82/**
83\brief provides direct access to PhysX' Spatial Query engine
84
85This class allows bounding boxes to be inserted, and then queried using sweep, raycast and overlap
86checks.
87
88It is not thread-safe and defers handling some updates until queries are invoked, so care must be taken when calling any methods in parallel. Specifically,
89to call query methods (raycast, overlap, sweep) in parallel, first call flush() to force immediate update of internal structures.
90
91@see PxCreateSpatialIndex
92*/
93class PxSpatialIndex
94{
95public:
96
97
98 /**
99 \brief insert a bounding box into a spatial index
100
101 \param[in] item the item to be inserted
102 \param[in] bounds the bounds of the new item
103 */
104 virtual PxSpatialIndexItemId insert(PxSpatialIndexItem& item,
105 const PxBounds3& bounds) = 0;
106
107 /**
108 \brief update a bounding box in a spatial index
109
110 \param[in] id the id of the item to be updated
111 \param[in] bounds the new bounds of the item
112 */
113 virtual void update(PxSpatialIndexItemId id,
114 const PxBounds3& bounds) = 0;
115
116 /**
117 \brief remove an item from a spatial index
118
119 \param[in] id the id of the item to be removed
120 */
121 virtual void remove(PxSpatialIndexItemId id) = 0;
122
123
124 /**
125 \brief make an overlap query against a spatial index
126
127 \param[in] aabb the axis aligned bounding box for the query
128 \param[in] callback the callback to invoke when an overlap is found
129 */
130 virtual void overlap(const PxBounds3 &aabb,
131 PxSpatialOverlapCallback& callback) const = 0;
132
133 /**
134 \brief make a raycast query against a spatial index
135
136 \param[in] origin the origin of the ray
137 \param[in] unitDir a unit vector in the direction of the ray
138 \param[in] maxDist the maximum distance to cast the ray
139 \param[in] callback the callback to invoke when an item is hit by the ray
140 */
141 virtual void raycast(const PxVec3& origin,
142 const PxVec3& unitDir,
143 PxReal maxDist,
144 PxSpatialLocationCallback& callback) const = 0;
145
146 /**
147 \brief make a sweep query against a spatial index
148
149 \param[in] aabb the axis aligned bounding box to sweep
150 \param[in] unitDir a unit vector in the direction of the sweep
151 \param[in] maxDist the maximum distance to apply the sweep
152 \param[in] callback the callback to invoke when an item is hit by the sweep
153 */
154 virtual void sweep(const PxBounds3& aabb,
155 const PxVec3& unitDir,
156 PxReal maxDist,
157 PxSpatialLocationCallback& callback) const = 0;
158
159 /**
160 \brief force an immediate update of the internal structures of the index
161
162 For reasons of efficiency an index structure may be lazily updated at the point of query if this method is not called. Once this method
163 has been called, subsequent queries (sweeps, overlaps, raycasts) may be executed in parallel until the next write call to the index (insertion,
164 removal, update, rebuild)
165 */
166 virtual void flush() = 0;
167
168 /**
169 \brief force a full optimized rebuild of the index.
170 */
171 virtual void rebuildFull() = 0;
172
173 /**
174 \brief set the incremental rebuild rate for the index.
175
176 The index builds gradually in the background each time a rebuild step is taken; this value determines the number of steps required to rebuild the index.
177
178 See PxScene::setDynamicTreeRebuildRateHint() for more information.
179
180 \param[in] rate the rebuild rate
181
182 @see PxScene::setDynamicTreeRebuildRateHint()
183 */
184 virtual void setIncrementalRebuildRate(PxU32 rate) = 0;
185
186 /**
187 \brief take one step in rebuilding the tree. See setIncrementalRebuildRate()
188 */
189 virtual void rebuildStep() = 0;
190
191 /**
192 \brief release this object
193 */
194 virtual void release() = 0;
195protected:
196 virtual ~PxSpatialIndex(){}
197};
198
199/**
200\brief Creates a spatial index.
201
202@see PxSpatialIndex
203*/
204PX_PHYSX_CORE_API PxSpatialIndex* PxCreateSpatialIndex();
205
206#ifndef PX_DOXYGEN
207} // namespace physx
208#endif
209
210/** @} */
211#endif
212