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#ifndef PX_PHYSICS_NX_VOLUMECACHE
14#define PX_PHYSICS_NX_VOLUMECACHE
15/** \addtogroup physics
16@{
17*/
18
19#include "PxScene.h"
20#include "geometry/PxGeometryHelpers.h"
21
22#ifndef PX_DOXYGEN
23namespace physx
24{
25#endif
26
27/**
28\brief Volumetric cache for local collision geometry.
29
30Provides a mechanism for caching objects within a specified volume and performing raycast, sweep, overlap and forEach queries on the cached objects.
31
32@see PxScene.createVolumeCache()
33*/
34class PxVolumeCache
35{
36public:
37 /**
38 \brief A callback wrapper class for use with PxVolumeCache::forEach function.
39
40 Works in tandem with #forEach(). Used to return shapes overlapping with the cache volume (set using the last fill() call) to the user.
41
42 @see PxVolumeCache::forEach
43 */
44 struct Iterator
45 {
46 /**
47 \brief Reports cache contents to the user.
48
49 \param[in] count The number of shapes returned with this call.
50 \param[in] actorShapePairs Array of PxActorShape pairs.
51
52 @see PxVolumeCache::forEach
53 */
54 virtual void processShapes(PxU32 count, const PxActorShape* actorShapePairs) = 0;
55
56 /**
57 /brief Called after the last processShapes was called.
58
59 @see PxVolumeCache::Iterator::processShapes
60 */
61 virtual void finalizeQuery() {}
62 protected:
63 virtual ~Iterator() {}
64 };
65
66
67 /**
68 \brief describes fill() return status.
69
70 @see PxVolumeCache.fill()
71 */
72 enum FillStatus
73 {
74 /**
75 \brief Cache fill() operation was successful, the cache is valid and had enough capacity to store all the objects within the specified cacheVolume.
76
77 */
78 FILL_OK,
79
80 /**
81 \brief Over specified cache capacity.
82
83 Cache fill() was over max count specified in PxScene.createVolumeCache() or #setMaxNbStaticShapes() and #setMaxNbDynamicShapes().
84 If this value is returned the cache will be in invalid state (no caching), but all the queries will still return correct results within the specified cache volume.
85
86 @see PxScene.createVolumeCache() #setMaxNbStaticShapes() #setMaxNbDynamicShapes()
87 */
88 FILL_OVER_MAX_COUNT,
89
90 /**
91 \brief Unsupported geometry type.
92
93 The geometry type of cacheVolume parameter provided to #fill() is not supported. Supported types are sphere, box, capsule.
94
95 */
96 FILL_UNSUPPORTED_GEOMETRY_TYPE,
97
98 /**
99 \brief Cache fill() ran out of temporary memory for intermediate results, try reducing the cache size.
100
101 */
102 FILL_OUT_OF_MEMORY
103 };
104
105 /**
106 \brief Fills the cache with objects intersecting the specified cacheVolume.
107
108 \param[in] cacheVolume Geometry of the cached volume (supported types are: sphere, box, capsule).
109 \param[in] pose Pose of the cache volume.
110
111 \return a #FillStatus enum.
112
113 @see PxVolumeCache.FillStatus
114 */
115 virtual FillStatus fill(const PxGeometry& cacheVolume, const PxTransform& pose) = 0;
116
117 /**
118 \brief Checks if the cache is valid (not over specified max capacity, for both statics and dynamics) and up-to-date.
119
120 \return True if the cache is valid and up-to-date. Cache can become out-of-date if any statics or dynamics are moved or added or deleted from the scene.
121
122 @see PxVolumeCache.FillStatus
123 */
124 virtual bool isValid() const = 0;
125
126 /**
127 \brief Invalidates the cache.
128
129 Marks the cache as invalid. Subsequent query will attempt to refill the cache from the scene.
130
131 */
132 virtual void invalidate() = 0;
133
134 /**
135 \brief Retrieves the last cached volume geometry.
136
137 \return False if the cache wasn't previously filled. True otherwise with cacheVolume from the last fill() call returned in resultVolume and corresponding transform in resultPose.
138
139 @see #fill()
140 */
141 virtual bool getCacheVolume(PxGeometryHolder& resultVolume, PxTransform& resultPose) = 0;
142
143 /**
144 \brief Returns the total number of cached shapes
145
146 \return The number of shapes stored in the cache (statics+dynamics). Returns -1 if the cache is invalid.
147 */
148 virtual PxI32 getNbCachedShapes() = 0;
149
150 /**
151 \brief Releases the cache object and its resources.
152
153 @see PxScene.createVolumeCache
154 */
155 virtual void release() = 0;
156
157 /**
158 \brief Iterates over the scene shapes overlapping with the cache volume.
159
160 forEach will invoke PxVolumeCache::Iterator::processShapes virtual function, returning all overlapping shapes (possibly by issuing multiple callbacks) to the user. The size of reported blocks can change depending on internal SDK implementation. Any pointers to the contents of the buffer are only valid within the scope of a single processShapes() callback function.
161 If forEach is invoked on an invalid cache (empty or out of date), this call will attempt to refill the cache within specified capacity. If the cache is over capacity, an attempt will be made to allocate a temp internal buffer, retrieve the results directly from the scene and return to the user via provided iterator.
162 Results from forEach will be current for the last set cacheVolume provided in fill() even if the cache is invalid and refill fails. If the number of overlapping shapes is so high that the internal temporary allocation fails this call will produce an error and return.
163
164 \param iter Iterator callback. forEach() will invokes iter.shapes() function (possibly multiple times) to return blocks of actor+shape pairs overlapped with cacheVolume to the user.
165 */
166 virtual void forEach(Iterator& iter) = 0;
167
168 /**
169 \brief Sets the limit on the maximum number of static shapes allowed to be stored in the cache.
170
171 If the number of cached objects goes over this limit, the query functions (forEach/raycast/sweep/overlap) will fall back to scene queries.
172
173 \param maxCount Maximum number of static shapes cached.
174 */
175 virtual void setMaxNbStaticShapes(PxU32 maxCount) = 0;
176
177 /**
178 \brief Sets the limit on the maximum number of dynamic shapes allowed to be stored in the cache.
179
180 If the number of cached objects goes over this limit, the query functions (forEach/raycast/sweep/overlap) will fall back to scene queries.
181
182 \param maxCount Maximum number of dynamic shapes cached.
183 */
184 virtual void setMaxNbDynamicShapes(PxU32 maxCount) = 0;
185
186 /**
187 \brief Returns the current maximum number of static cached shapes.
188
189 \return The max number of cached statics.
190 */
191 virtual PxU32 getMaxNbStaticShapes() = 0;
192
193 /**
194 \brief Returns the current maximum number of dynamic cached shapes.
195
196 \return The max number of cached dynamics.
197 */
198 virtual PxU32 getMaxNbDynamicShapes() = 0;
199
200 /**
201 \brief Raycast against objects in the cache, returning results via PxRaycastCallback callback or PxRaycastBuffer object
202 or a custom user callback implementation.
203
204 Returns whether any rigid actor is hit along the ray.
205
206 \note Shooting a ray from within an object leads to different results depending on the shape type. Please check the details in user guide article SceneQuery. User can ignore such objects by employing one of the provided filter mechanisms.
207
208 \param[in] origin Origin of the ray.
209 \param[in] unitDir Normalized direction of the ray.
210 \param[in] distance Length of the ray. Needs to be larger than 0.
211 \param[out] hitCall Raycast hit callback or hit buffer object.
212 \param[in] hitFlags Specifies which properties per hit should be computed and returned via the hit callback.
213 \param[in] filterData Filtering data and simple logic.
214 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
215 \return True if a blocking hit was found or any hit was found in case PxQueryFlag::eANY_HIT flag was used.
216
217 @see PxRaycastCallback PxRaycastBuffer PxQueryFilterData PxQueryFilterCallback PxQueryCache PxRaycastHit PxQueryFlag PxQueryFlag::eANY_HIT
218 */
219 virtual bool raycast(
220 const PxVec3& origin, const PxVec3& unitDir, const PxReal distance,
221 PxRaycastCallback& hitCall, PxHitFlags hitFlags = PxHitFlags(PxHitFlag::eDEFAULT),
222 const PxQueryFilterData& filterData = PxQueryFilterData(), PxQueryFilterCallback* filterCall = NULL) const = 0;
223
224 /**
225 \brief Sweep against objects in the cache, returning results via PxRaycastCallback callback or PxRaycastBuffer object
226 or a custom user callback implementation.
227
228 Returns whether any rigid actor is hit along the sweep path.
229
230 \param[in] geometry Geometry of object to sweep (supported types are: box, sphere, capsule, convex).
231 \param[in] pose Pose of the sweep object.
232 \param[in] unitDir Normalized direction of the sweep.
233 \param[in] distance Sweep distance. Needs to be larger than 0. Will be clamped to PX_MAX_SWEEP_DISTANCE.
234 \param[out] hitCall Sweep hit callback or hit buffer object.
235 \param[in] hitFlags Specifies which properties per hit should be computed and returned via the hit callback.
236 \param[in] filterData Filtering data and simple logic.
237 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
238 \param[in] inflation This parameter creates a skin around the swept geometry which increases its extents for sweeping. The sweep will register a hit as soon as the skin touches a shape, and will return the corresponding distance and normal.
239 \return True if a blocking hit was found or any hit was found in case PxQueryFlag::eANY_HIT flag was specified.
240
241 @see PxSweepCallback PxSweepBuffer PxQueryFilterData PxQueryFilterCallback PxSweepHit PxQueryCache PxHitFlags
242 */
243 virtual bool sweep(
244 const PxGeometry& geometry, const PxTransform& pose, const PxVec3& unitDir, const PxReal distance,
245 PxSweepCallback& hitCall, PxHitFlags hitFlags = PxHitFlags(PxHitFlag::ePOSITION | PxHitFlag::eNORMAL | PxHitFlag::eDISTANCE),
246 const PxQueryFilterData& filterData = PxQueryFilterData(), PxQueryFilterCallback* filterCall = NULL,
247 const PxReal inflation = 0.f) const = 0;
248
249
250 /**
251 \brief Test overlap between a geometry and objects in the cache.
252
253 \note Filtering: Overlap tests do not distinguish between touching and blocking hit types (see #PxQueryHitType). Both get written to the hit buffer.
254
255 \param[in] geometry Geometry of object to check for overlap (supported types are: box, sphere, capsule, convex).
256 \param[in] pose Pose of the object.
257 \param[out] hitCall Overlap hit callback or hit buffer object.
258 \param[in] filterData Filtering data and simple logic.
259 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to overlap.
260 \return True if a blocking hit was found or any hit was found in case PxQueryFlag::eANY_HIT flag was specified.
261
262 @see PxOverlapCallback PxOverlapBuffer PxQueryFilterData PxQueryFilterCallback
263 */
264 virtual bool overlap(
265 const PxGeometry& geometry, const PxTransform& pose, PxOverlapCallback& hitCall,
266 const PxQueryFilterData& filterData = PxQueryFilterData(), PxQueryFilterCallback* filterCall = NULL) const = 0;
267
268protected:
269 virtual ~PxVolumeCache() {}
270}; // class PxVolumeCache
271
272#ifndef PX_DOXYGEN
273} // namespace physx
274#endif
275
276/** @} */
277#endif
278