1 | // |
2 | // Redistribution and use in source and binary forms, with or without |
3 | // modification, are permitted provided that the following conditions |
4 | // are met: |
5 | // * Redistributions of source code must retain the above copyright |
6 | // notice, this list of conditions and the following disclaimer. |
7 | // * Redistributions in binary form must reproduce the above copyright |
8 | // notice, this list of conditions and the following disclaimer in the |
9 | // documentation and/or other materials provided with the distribution. |
10 | // * Neither the name of NVIDIA CORPORATION nor the names of its |
11 | // contributors may be used to endorse or promote products derived |
12 | // from this software without specific prior written permission. |
13 | // |
14 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY |
15 | // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
16 | // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
17 | // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR |
18 | // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
19 | // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
20 | // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
21 | // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY |
22 | // OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
23 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
24 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
25 | // |
26 | // Copyright (c) 2008-2021 NVIDIA Corporation. All rights reserved. |
27 | // Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved. |
28 | // Copyright (c) 2001-2004 NovodeX AG. All rights reserved. |
29 | |
30 | |
31 | #ifndef PX_PHYSICS_NX_SCENEQUERYREPORT |
32 | #define PX_PHYSICS_NX_SCENEQUERYREPORT |
33 | /** \addtogroup scenequery |
34 | @{ |
35 | */ |
36 | #include "foundation/PxVec3.h" |
37 | #include "foundation/PxFlags.h" |
38 | #include "foundation/PxAssert.h" |
39 | #include "PxPhysXConfig.h" |
40 | |
41 | #if !PX_DOXYGEN |
42 | namespace physx |
43 | { |
44 | #endif |
45 | |
46 | class PxShape; |
47 | class PxRigidActor; |
48 | |
49 | /** |
50 | \brief Scene query and geometry query behavior flags. |
51 | |
52 | PxHitFlags are used for 3 different purposes: |
53 | |
54 | 1) To request hit fields to be filled in by scene queries (such as hit position, normal, face index or UVs). |
55 | 2) Once query is completed, to indicate which fields are valid (note that a query may produce more valid fields than requested). |
56 | 3) To specify additional options for the narrow phase and mid-phase intersection routines. |
57 | |
58 | All these flags apply to both scene queries and geometry queries (PxGeometryQuery). |
59 | |
60 | @see PxRaycastHit PxSweepHit PxOverlapHit PxScene.raycast PxScene.sweep PxScene.overlap PxGeometryQuery PxFindFaceIndex |
61 | */ |
62 | struct PxHitFlag |
63 | { |
64 | enum Enum |
65 | { |
66 | ePOSITION = (1<<0), //!< "position" member of #PxQueryHit is valid |
67 | eNORMAL = (1<<1), //!< "normal" member of #PxQueryHit is valid |
68 | eUV = (1<<3), //!< "u" and "v" barycentric coordinates of #PxQueryHit are valid. Not applicable to sweep queries. |
69 | eASSUME_NO_INITIAL_OVERLAP = (1<<4), //!< Performance hint flag for sweeps when it is known upfront there's no initial overlap. |
70 | //!< NOTE: using this flag may cause undefined results if shapes are initially overlapping. |
71 | eMESH_MULTIPLE = (1<<5), //!< Report all hits for meshes rather than just the first. Not applicable to sweep queries. |
72 | eMESH_ANY = (1<<6), //!< Report any first hit for meshes. If neither eMESH_MULTIPLE nor eMESH_ANY is specified, |
73 | //!< a single closest hit will be reported for meshes. |
74 | eMESH_BOTH_SIDES = (1<<7), //!< Report hits with back faces of mesh triangles. Also report hits for raycast |
75 | //!< originating on mesh surface and facing away from the surface normal. Not applicable to sweep queries. |
76 | //!< Please refer to the user guide for heightfield-specific differences. |
77 | ePRECISE_SWEEP = (1<<8), //!< Use more accurate but slower narrow phase sweep tests. |
78 | //!< May provide better compatibility with PhysX 3.2 sweep behavior. |
79 | eMTD = (1<<9), //!< Report the minimum translation depth, normal and contact point. |
80 | eFACE_INDEX = (1<<10), //!< "face index" member of #PxQueryHit is valid |
81 | |
82 | eDEFAULT = ePOSITION|eNORMAL|eFACE_INDEX, |
83 | |
84 | /** \brief Only this subset of flags can be modified by pre-filter. Other modifications will be discarded. */ |
85 | eMODIFIABLE_FLAGS = eMESH_MULTIPLE|eMESH_BOTH_SIDES|eASSUME_NO_INITIAL_OVERLAP|ePRECISE_SWEEP |
86 | }; |
87 | }; |
88 | |
89 | |
90 | /** |
91 | \brief collection of set bits defined in PxHitFlag. |
92 | |
93 | @see PxHitFlag |
94 | */ |
95 | PX_FLAGS_TYPEDEF(PxHitFlag, PxU16) |
96 | |
97 | /** |
98 | \brief Combines a shape pointer and the actor the shape belongs to into one memory location. |
99 | |
100 | Serves as a base class for PxQueryHit. |
101 | |
102 | @see PxQueryHit |
103 | */ |
104 | struct PxActorShape |
105 | { |
106 | PX_INLINE PxActorShape() : actor(NULL), shape(NULL) {} |
107 | PX_INLINE PxActorShape(PxRigidActor* a, PxShape* s) : actor(a), shape(s) {} |
108 | |
109 | PxRigidActor* actor; |
110 | PxShape* shape; |
111 | }; |
112 | |
113 | |
114 | /** |
115 | \brief Scene query hit information. |
116 | */ |
117 | struct PxQueryHit : public PxActorShape |
118 | { |
119 | PX_INLINE PxQueryHit() : faceIndex(0xFFFFffff) {} |
120 | |
121 | /** |
122 | Face index of touched triangle, for triangle meshes, convex meshes and height fields. |
123 | |
124 | \note This index will default to 0xFFFFffff value for overlap queries. |
125 | \note Please refer to the user guide for more details for sweep queries. |
126 | \note This index is remapped by mesh cooking. Use #PxTriangleMesh::getTrianglesRemap() to convert to original mesh index. |
127 | \note For convex meshes use #PxConvexMesh::getPolygonData() to retrieve touched polygon data. |
128 | */ |
129 | PxU32 faceIndex; |
130 | }; |
131 | |
132 | /** |
133 | \brief Scene query hit information for raycasts and sweeps returning hit position and normal information. |
134 | |
135 | ::PxHitFlag flags can be passed to scene query functions, as an optimization, to cause the SDK to |
136 | only generate specific members of this structure. |
137 | */ |
138 | struct PxLocationHit : public PxQueryHit |
139 | { |
140 | PX_INLINE PxLocationHit() : flags(0), position(PxVec3(0)), normal(PxVec3(0)), distance(PX_MAX_REAL) {} |
141 | |
142 | /** |
143 | \note For raycast hits: true for shapes overlapping with raycast origin. |
144 | \note For sweep hits: true for shapes overlapping at zero sweep distance. |
145 | |
146 | @see PxRaycastHit PxSweepHit |
147 | */ |
148 | PX_INLINE bool hadInitialOverlap() const { return (distance <= 0.0f); } |
149 | |
150 | // the following fields are set in accordance with the #PxHitFlags |
151 | PxHitFlags flags; //!< Hit flags specifying which members contain valid values. |
152 | PxVec3 position; //!< World-space hit position (flag: #PxHitFlag::ePOSITION) |
153 | PxVec3 normal; //!< World-space hit normal (flag: #PxHitFlag::eNORMAL) |
154 | |
155 | /** |
156 | \brief Distance to hit. |
157 | \note If the eMTD flag is used, distance will be a negative value if shapes are overlapping indicating the penetration depth. |
158 | \note Otherwise, this value will be >= 0 */ |
159 | PxF32 distance; |
160 | }; |
161 | |
162 | |
163 | /** |
164 | \brief Stores results of raycast queries. |
165 | |
166 | ::PxHitFlag flags can be passed to raycast function, as an optimization, to cause the SDK to only compute specified members of this |
167 | structure. |
168 | |
169 | Some members like barycentric coordinates are currently only computed for triangle meshes and height fields, but next versions |
170 | might provide them in other cases. The client code should check #flags to make sure returned values are valid. |
171 | |
172 | @see PxScene.raycast PxBatchQuery.raycast |
173 | */ |
174 | struct PxRaycastHit : public PxLocationHit |
175 | { |
176 | PX_INLINE PxRaycastHit() : u(0.0f), v(0.0f) {} |
177 | |
178 | // the following fields are set in accordance with the #PxHitFlags |
179 | |
180 | PxReal u, v; //!< barycentric coordinates of hit point, for triangle mesh and height field (flag: #PxHitFlag::eUV) |
181 | #if !PX_P64_FAMILY |
182 | PxU32 padTo16Bytes[3]; |
183 | #endif |
184 | }; |
185 | |
186 | |
187 | /** |
188 | \brief Stores results of overlap queries. |
189 | |
190 | @see PxScene.overlap PxBatchQuery.overlap |
191 | */ |
192 | struct PxOverlapHit: public PxQueryHit { PxU32 padTo16Bytes; }; |
193 | |
194 | |
195 | /** |
196 | \brief Stores results of sweep queries. |
197 | |
198 | @see PxScene.sweep PxBatchQuery.sweep |
199 | */ |
200 | struct PxSweepHit : public PxLocationHit |
201 | { |
202 | PX_INLINE PxSweepHit() {} |
203 | |
204 | PxU32 padTo16Bytes; |
205 | }; |
206 | |
207 | |
208 | /** |
209 | \brief Describes query behavior after returning a partial query result via a callback. |
210 | |
211 | If callback returns true, traversal will continue and callback can be issued again. |
212 | If callback returns false, traversal will stop, callback will not be issued again. |
213 | |
214 | @see PxHitCallback |
215 | */ |
216 | typedef bool PxAgain; |
217 | |
218 | |
219 | /** |
220 | \brief This callback class facilitates reporting scene query hits (intersections) to the user. |
221 | |
222 | User overrides the virtual processTouches function to receive hits in (possibly multiple) fixed size blocks. |
223 | |
224 | \note PxHitBuffer derives from this class and is used to receive touching hits in a fixed size buffer. |
225 | \note Since the compiler doesn't look in template dependent base classes when looking for non-dependent names |
226 | \note with some compilers it will be necessary to use "this->hasBlock" notation to access a parent variable |
227 | \note in a child callback class. |
228 | \note Pre-made typedef shorthands, such as ::PxRaycastCallback can be used for raycast, overlap and sweep queries. |
229 | |
230 | @see PxHitBuffer PxRaycastHit PxSweepHit PxOverlapHit PxRaycastCallback PxOverlapCallback PxSweepCallback |
231 | */ |
232 | template<typename HitType> |
233 | struct PxHitCallback |
234 | { |
235 | HitType block; //!< Holds the closest blocking hit result for the query. Invalid if hasBlock is false. |
236 | bool hasBlock; //!< Set to true if there was a blocking hit during query. |
237 | |
238 | HitType* touches; //!< User specified buffer for touching hits. |
239 | |
240 | /** |
241 | \brief Size of the user specified touching hits buffer. |
242 | \note If set to 0 all hits will default to PxQueryHitType::eBLOCK, otherwise to PxQueryHitType::eTOUCH |
243 | \note Hit type returned from pre-filter overrides this default */ |
244 | PxU32 maxNbTouches; |
245 | |
246 | /** |
247 | \brief Number of touching hits returned by the query. Used with PxHitBuffer. |
248 | \note If true (PxAgain) is returned from the callback, nbTouches will be reset to 0. */ |
249 | PxU32 nbTouches; |
250 | |
251 | /** |
252 | \brief Initializes the class with user provided buffer. |
253 | |
254 | \param[in] aTouches Optional buffer for recording PxQueryHitType::eTOUCH type hits. |
255 | \param[in] aMaxNbTouches Size of touch buffer. |
256 | |
257 | \note if aTouches is NULL and aMaxNbTouches is 0, only the closest blocking hit will be recorded by the query. |
258 | \note If PxQueryFlag::eANY_HIT flag is used as a query parameter, hasBlock will be set to true and blockingHit will be used to receive the result. |
259 | \note Both eTOUCH and eBLOCK hits will be registered as hasBlock=true and stored in PxHitCallback.block when eANY_HIT flag is used. |
260 | |
261 | @see PxHitCallback.hasBlock PxHitCallback.block */ |
262 | PxHitCallback(HitType* aTouches, PxU32 aMaxNbTouches) |
263 | : hasBlock(false), touches(aTouches), maxNbTouches(aMaxNbTouches), nbTouches(0) |
264 | {} |
265 | |
266 | /** |
267 | \brief virtual callback function used to communicate query results to the user. |
268 | |
269 | This callback will always be invoked with #touches as a buffer if #touches was specified as non-NULL. |
270 | All reported touch hits are guaranteed to be closer than the closest blocking hit. |
271 | |
272 | \param[in] buffer Callback will report touch hits to the user in this buffer. This pointer will be the same as #touches. |
273 | \param[in] nbHits Number of touch hits reported in buffer. This number will not exceed #maxNbTouches. |
274 | |
275 | \note There is a significant performance penalty in case multiple touch callbacks are issued (up to 2x) |
276 | \note to avoid the penalty use a bigger buffer so that all touching hits can be reported in a single buffer. |
277 | \note If true (again) is returned from the callback, nbTouches will be reset to 0, |
278 | \note If false is returned, nbTouched will remain unchanged. |
279 | \note By the time processTouches is first called, the globally closest blocking hit is already determined, |
280 | \note values of hasBlock and block are final and all touch hits are guaranteed to be closer than the blocking hit. |
281 | \note touches and maxNbTouches can be modified inside of processTouches callback. |
282 | |
283 | \return true to continue receiving callbacks in case there are more hits or false to stop. |
284 | |
285 | @see PxAgain PxRaycastHit PxSweepHit PxOverlapHit */ |
286 | virtual PxAgain processTouches(const HitType* buffer, PxU32 nbHits) = 0; |
287 | |
288 | virtual void finalizeQuery() {} //!< Query finalization callback, called after the last processTouches callback. |
289 | |
290 | virtual ~PxHitCallback() {} |
291 | |
292 | /** \brief Returns true if any blocking or touching hits were encountered during a query. */ |
293 | PX_FORCE_INLINE bool hasAnyHits() { return (hasBlock || (nbTouches > 0)); } |
294 | }; |
295 | |
296 | |
297 | /** |
298 | \brief Returns scene query hits (intersections) to the user in a preallocated buffer. |
299 | |
300 | Will clip touch hits to maximum buffer capacity. When clipped, an arbitrary subset of touching hits will be discarded. |
301 | Overflow does not trigger warnings or errors. block and hasBlock will be valid in finalizeQuery callback and after query completion. |
302 | Touching hits are guaranteed to have closer or same distance ( <= condition) as the globally nearest blocking hit at the time any processTouches() |
303 | callback is issued. |
304 | |
305 | \note Pre-made typedef shorthands, such as ::PxRaycastBuffer can be used for raycast, overlap and sweep queries. |
306 | |
307 | @see PxHitCallback |
308 | @see PxRaycastBuffer PxOverlapBuffer PxSweepBuffer PxRaycastBufferN PxOverlapBufferN PxSweepBufferN |
309 | */ |
310 | template<typename HitType> |
311 | struct PxHitBuffer : public PxHitCallback<HitType> |
312 | { |
313 | /** |
314 | \brief Initializes the buffer with user memory. |
315 | |
316 | The buffer is initialized with 0 touch hits by default => query will only report a single closest blocking hit. |
317 | Use PxQueryFlag::eANY_HIT to tell the query to abort and return any first hit encoutered as blocking. |
318 | |
319 | \param[in] aTouches Optional buffer for recording PxQueryHitType::eTOUCH type hits. |
320 | \param[in] aMaxNbTouches Size of touch buffer. |
321 | |
322 | @see PxHitCallback */ |
323 | PxHitBuffer(HitType* aTouches = NULL, PxU32 aMaxNbTouches = 0) : PxHitCallback<HitType>(aTouches, aMaxNbTouches) {} |
324 | |
325 | /** \brief Computes the number of any hits in this result, blocking or touching. */ |
326 | PX_INLINE PxU32 getNbAnyHits() const { return getNbTouches() + PxU32(this->hasBlock); } |
327 | /** \brief Convenience iterator used to access any hits in this result, blocking or touching. */ |
328 | PX_INLINE const HitType& getAnyHit(const PxU32 index) const { PX_ASSERT(index < getNbTouches() + PxU32(this->hasBlock)); |
329 | return index < getNbTouches() ? getTouches()[index] : this->block; } |
330 | |
331 | PX_INLINE PxU32 getNbTouches() const { return this->nbTouches; } |
332 | PX_INLINE const HitType* getTouches() const { return this->touches; } |
333 | PX_INLINE const HitType& getTouch(const PxU32 index) const { PX_ASSERT(index < getNbTouches()); return getTouches()[index]; } |
334 | PX_INLINE PxU32 getMaxNbTouches() const { return this->maxNbTouches; } |
335 | |
336 | virtual ~PxHitBuffer() {} |
337 | |
338 | protected: |
339 | // stops after the first callback |
340 | virtual PxAgain processTouches(const HitType* buffer, PxU32 nbHits) { PX_UNUSED(buffer); PX_UNUSED(nbHits); return false; } |
341 | }; |
342 | |
343 | |
344 | /** \brief Raycast query callback. */ |
345 | typedef PxHitCallback<PxRaycastHit> PxRaycastCallback; |
346 | |
347 | /** \brief Overlap query callback. */ |
348 | typedef PxHitCallback<PxOverlapHit> PxOverlapCallback; |
349 | |
350 | /** \brief Sweep query callback. */ |
351 | typedef PxHitCallback<PxSweepHit> PxSweepCallback; |
352 | |
353 | /** \brief Raycast query buffer. */ |
354 | typedef PxHitBuffer<PxRaycastHit> PxRaycastBuffer; |
355 | |
356 | /** \brief Overlap query buffer. */ |
357 | typedef PxHitBuffer<PxOverlapHit> PxOverlapBuffer; |
358 | |
359 | /** \brief Sweep query buffer. */ |
360 | typedef PxHitBuffer<PxSweepHit> PxSweepBuffer; |
361 | |
362 | /** \brief Returns touching raycast hits to the user in a fixed size array embedded in the buffer class. **/ |
363 | template <int N> |
364 | struct PxRaycastBufferN : public PxHitBuffer<PxRaycastHit> |
365 | { |
366 | PxRaycastHit hits[N]; |
367 | PxRaycastBufferN() : PxHitBuffer<PxRaycastHit>(hits, N) {} |
368 | }; |
369 | |
370 | /** \brief Returns touching overlap hits to the user in a fixed size array embedded in the buffer class. **/ |
371 | template <int N> |
372 | struct PxOverlapBufferN : public PxHitBuffer<PxOverlapHit> |
373 | { |
374 | PxOverlapHit hits[N]; |
375 | PxOverlapBufferN() : PxHitBuffer<PxOverlapHit>(hits, N) {} |
376 | }; |
377 | |
378 | /** \brief Returns touching sweep hits to the user in a fixed size array embedded in the buffer class. **/ |
379 | template <int N> |
380 | struct PxSweepBufferN : public PxHitBuffer<PxSweepHit> |
381 | { |
382 | PxSweepHit hits[N]; |
383 | PxSweepBufferN() : PxHitBuffer<PxSweepHit>(hits, N) {} |
384 | }; |
385 | |
386 | #if !PX_DOXYGEN |
387 | } // namespace physx |
388 | #endif |
389 | |
390 | /** @} */ |
391 | #endif |
392 | |