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 |
23 | namespace physx |
24 | { |
25 | #endif |
26 | |
27 | /** |
28 | \brief Volumetric cache for local collision geometry. |
29 | |
30 | Provides 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 | */ |
34 | class PxVolumeCache |
35 | { |
36 | public: |
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 | |
268 | protected: |
269 | virtual ~PxVolumeCache() {} |
270 | }; // class PxVolumeCache |
271 | |
272 | #ifndef PX_DOXYGEN |
273 | } // namespace physx |
274 | #endif |
275 | |
276 | /** @} */ |
277 | #endif |
278 | |