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
42namespace physx
43{
44#endif
45
46class PxShape;
47class PxRigidActor;
48
49/**
50\brief Scene query and geometry query behavior flags.
51
52PxHitFlags are used for 3 different purposes:
53
541) To request hit fields to be filled in by scene queries (such as hit position, normal, face index or UVs).
552) Once query is completed, to indicate which fields are valid (note that a query may produce more valid fields than requested).
563) To specify additional options for the narrow phase and mid-phase intersection routines.
57
58All 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*/
62struct 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*/
95PX_FLAGS_TYPEDEF(PxHitFlag, PxU16)
96
97/**
98\brief Combines a shape pointer and the actor the shape belongs to into one memory location.
99
100Serves as a base class for PxQueryHit.
101
102@see PxQueryHit
103*/
104struct 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*/
117struct 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
136only generate specific members of this structure.
137*/
138struct 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
167structure.
168
169Some members like barycentric coordinates are currently only computed for triangle meshes and height fields, but next versions
170might 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*/
174struct 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*/
192struct PxOverlapHit: public PxQueryHit { PxU32 padTo16Bytes; };
193
194
195/**
196\brief Stores results of sweep queries.
197
198@see PxScene.sweep PxBatchQuery.sweep
199*/
200struct 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
211If callback returns true, traversal will continue and callback can be issued again.
212If callback returns false, traversal will stop, callback will not be issued again.
213
214@see PxHitCallback
215*/
216typedef bool PxAgain;
217
218
219/**
220\brief This callback class facilitates reporting scene query hits (intersections) to the user.
221
222User 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*/
232template<typename HitType>
233struct 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
300Will clip touch hits to maximum buffer capacity. When clipped, an arbitrary subset of touching hits will be discarded.
301Overflow does not trigger warnings or errors. block and hasBlock will be valid in finalizeQuery callback and after query completion.
302Touching hits are guaranteed to have closer or same distance ( <= condition) as the globally nearest blocking hit at the time any processTouches()
303callback 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*/
310template<typename HitType>
311struct 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
338protected:
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. */
345typedef PxHitCallback<PxRaycastHit> PxRaycastCallback;
346
347/** \brief Overlap query callback. */
348typedef PxHitCallback<PxOverlapHit> PxOverlapCallback;
349
350/** \brief Sweep query callback. */
351typedef PxHitCallback<PxSweepHit> PxSweepCallback;
352
353/** \brief Raycast query buffer. */
354typedef PxHitBuffer<PxRaycastHit> PxRaycastBuffer;
355
356/** \brief Overlap query buffer. */
357typedef PxHitBuffer<PxOverlapHit> PxOverlapBuffer;
358
359/** \brief Sweep query buffer. */
360typedef PxHitBuffer<PxSweepHit> PxSweepBuffer;
361
362/** \brief Returns touching raycast hits to the user in a fixed size array embedded in the buffer class. **/
363template <int N>
364struct 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. **/
371template <int N>
372struct 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. **/
379template <int N>
380struct 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

source code of qtquick3dphysics/src/3rdparty/PhysX/include/PxQueryReport.h