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_SCENE_QUERY_FILTERING
32#define PX_PHYSICS_NX_SCENE_QUERY_FILTERING
33/** \addtogroup scenequery
34@{
35*/
36
37#include "PxPhysXConfig.h"
38#include "PxFiltering.h"
39#include "PxQueryReport.h"
40#include "PxClient.h"
41
42#if !PX_DOXYGEN
43namespace physx
44{
45#endif
46
47class PxShape;
48class PxRigidActor;
49struct PxQueryHit;
50
51
52/**
53\brief Filtering flags for scene queries.
54
55@see PxQueryFilterData.flags
56*/
57struct PxQueryFlag
58{
59 enum Enum
60 {
61 eSTATIC = (1<<0), //!< Traverse static shapes
62
63 eDYNAMIC = (1<<1), //!< Traverse dynamic shapes
64
65 ePREFILTER = (1<<2), //!< Run the pre-intersection-test filter (see #PxQueryFilterCallback::preFilter())
66
67 ePOSTFILTER = (1<<3), //!< Run the post-intersection-test filter (see #PxQueryFilterCallback::postFilter())
68
69 eANY_HIT = (1<<4), //!< Abort traversal as soon as any hit is found and return it via callback.block.
70 //!< Helps query performance. Both eTOUCH and eBLOCK hitTypes are considered hits with this flag.
71
72 eNO_BLOCK = (1<<5), //!< All hits are reported as touching. Overrides eBLOCK returned from user filters with eTOUCH.
73 //!< This is also an optimization hint that may improve query performance.
74
75 eRESERVED = (1<<15) //!< Reserved for internal use
76 };
77};
78PX_COMPILE_TIME_ASSERT(PxQueryFlag::eSTATIC==(1<<0));
79PX_COMPILE_TIME_ASSERT(PxQueryFlag::eDYNAMIC==(1<<1));
80
81/**
82\brief Flags typedef for the set of bits defined in PxQueryFlag.
83
84*/
85typedef PxFlags<PxQueryFlag::Enum,PxU16> PxQueryFlags;
86PX_FLAGS_OPERATORS(PxQueryFlag::Enum,PxU16)
87
88/**
89\brief Classification of scene query hits (intersections).
90
91 - eNONE: Returning this hit type means that the hit should not be reported.
92 - eBLOCK: For all raycast, sweep and overlap queries the nearest eBLOCK type hit will always be returned in PxHitCallback::block member.
93 - eTOUCH: Whenever a raycast, sweep or overlap query was called with non-zero PxHitCallback::nbTouches and PxHitCallback::touches
94 parameters, eTOUCH type hits that are closer or same distance (touchDistance <= blockDistance condition)
95 as the globally nearest eBLOCK type hit, will be reported.
96 - For example, to record all hits from a raycast query, always return eTOUCH.
97
98All hits in overlap() queries are treated as if the intersection distance were zero.
99This means the hits are unsorted and all eTOUCH hits are recorded by the callback even if an eBLOCK overlap hit was encountered.
100Even though all overlap() blocking hits have zero length, only one (arbitrary) eBLOCK overlap hit is recorded in PxHitCallback::block.
101All overlap() eTOUCH type hits are reported (zero touchDistance <= zero blockDistance condition).
102
103For raycast/sweep/overlap calls with zero touch buffer or PxHitCallback::nbTouches member,
104only the closest hit of type eBLOCK is returned. All eTOUCH hits are discarded.
105
106@see PxQueryFilterCallback.preFilter PxQueryFilterCallback.postFilter PxScene.raycast PxScene.sweep PxScene.overlap
107*/
108struct PxQueryHitType
109{
110 enum Enum
111 {
112 eNONE = 0, //!< the query should ignore this shape
113 eTOUCH = 1, //!< a hit on the shape touches the intersection geometry of the query but does not block it
114 eBLOCK = 2 //!< a hit on the shape blocks the query (does not block overlap queries)
115 };
116};
117
118/**
119\brief Scene query filtering data.
120
121Whenever the scene query intersects a shape, filtering is performed in the following order:
122
123\li For non-batched queries only:<br>If the data field is non-zero, and the bitwise-AND value of data AND the shape's
124queryFilterData is zero, the shape is skipped
125\li If filter callbacks are enabled in flags field (see #PxQueryFlags) they will get invoked accordingly.
126\li If neither #PxQueryFlag::ePREFILTER or #PxQueryFlag::ePOSTFILTER is set, the hit defaults
127to type #PxQueryHitType::eBLOCK when the value of PxHitCallback::nbTouches provided with the query is zero and to type
128#PxQueryHitType::eTOUCH when PxHitCallback::nbTouches is positive.
129
130@see PxScene.raycast PxScene.sweep PxScene.overlap PxBatchQuery.raycast PxBatchQuery.sweep PxBatchQuery.overlap PxQueryFlag::eANY_HIT
131*/
132struct PxQueryFilterData
133{
134 /** \brief default constructor */
135 explicit PX_INLINE PxQueryFilterData() : flags(PxQueryFlag::eDYNAMIC | PxQueryFlag::eSTATIC) {}
136
137 /** \brief constructor to set both filter data and filter flags */
138 explicit PX_INLINE PxQueryFilterData(const PxFilterData& fd, PxQueryFlags f) : data(fd), flags(f) {}
139
140 /** \brief constructor to set filter flags only */
141 explicit PX_INLINE PxQueryFilterData(PxQueryFlags f) : flags(f) {}
142
143 PxFilterData data; //!< Filter data associated with the scene query
144 PxQueryFlags flags; //!< Filter flags (see #PxQueryFlags)
145};
146
147/**
148\brief Scene query filtering callbacks.
149
150Custom filtering logic for scene query intersection candidates. If an intersection candidate object passes the data based filter
151(see #PxQueryFilterData), filtering callbacks are executed if requested (see #PxQueryFilterData.flags)
152
153\li If #PxQueryFlag::ePREFILTER is set, the preFilter function runs before exact intersection tests.
154If this function returns #PxQueryHitType::eTOUCH or #PxQueryHitType::eBLOCK, exact testing is performed to
155determine the intersection location.
156
157The preFilter function may overwrite the copy of queryFlags it receives as an argument to specify any of #PxHitFlag::eMODIFIABLE_FLAGS
158on a per-shape basis. Changes apply only to the shape being filtered, and changes to other flags are ignored.
159
160\li If #PxQueryFlag::ePREFILTER is not set, precise intersection testing is performed using the original query's filterData.flags.
161
162\li If #PxQueryFlag::ePOSTFILTER is set, the postFilter function is called for each intersection to determine the touch/block status.
163This overrides any touch/block status previously returned from the preFilter function for this shape.
164
165Filtering calls are not guaranteed to be sorted along the ray or sweep direction.
166
167@see PxScene.raycast PxScene.sweep PxScene.overlap PxQueryFlags PxHitFlags
168*/
169class PxQueryFilterCallback
170{
171public:
172
173 /**
174 \brief This filter callback is executed before the exact intersection test if PxQueryFlag::ePREFILTER flag was set.
175
176 \param[in] filterData custom filter data specified as the query's filterData.data parameter.
177 \param[in] shape A shape that has not yet passed the exact intersection test.
178 \param[in] actor The shape's actor.
179 \param[in,out] queryFlags scene query flags from the query's function call (only flags from PxHitFlag::eMODIFIABLE_FLAGS bitmask can be modified)
180 \return the updated type for this hit (see #PxQueryHitType)
181 */
182 virtual PxQueryHitType::Enum preFilter(
183 const PxFilterData& filterData, const PxShape* shape, const PxRigidActor* actor, PxHitFlags& queryFlags) = 0;
184
185 /**
186 \brief This filter callback is executed if the exact intersection test returned true and PxQueryFlag::ePOSTFILTER flag was set.
187
188 \param[in] filterData custom filter data of the query
189 \param[in] hit Scene query hit information. faceIndex member is not valid for overlap queries. For sweep and raycast queries the hit information can be cast to #PxSweepHit and #PxRaycastHit respectively.
190 \return the updated hit type for this hit (see #PxQueryHitType)
191 */
192 virtual PxQueryHitType::Enum postFilter(const PxFilterData& filterData, const PxQueryHit& hit) = 0;
193
194 /**
195 \brief virtual destructor
196 */
197 virtual ~PxQueryFilterCallback() {}
198};
199
200/**
201\brief Batched query pre-filter shader.
202
203Custom filtering logic for batched query intersection candidates. If an intersection candidate object passes the data based filter (see #PxQueryFilterData),
204filtering shader runs if specified in filtering flags (see #PxQueryFilterData.flags)
205
206\li If #PxQueryFlag::ePREFILTER is set, the preFilter shader runs before exact intersection tests.
207If the shader returns #PxQueryHitType::eTOUCH or #PxQueryHitType::eBLOCK, exact testing is performed to
208determine the intersection location.
209
210The preFilter shader may overwrite the copy of queryFlags it receives as an argument to specify any of #PxHitFlag::eMODIFIABLE_FLAGS
211on a per-shape basis. Changes apply only to the shape being filtered, and changes to other flags are ignored.
212
213\li If #PxQueryFlag::ePREFILTER is not set, precise intersection testing is performed using the original query's filterData.flags.
214
215Filtering calls are not guaranteed to be sorted along the ray or sweep direction.
216
217\deprecated The batched query feature has been deprecated in PhysX version 3.4
218
219@see PxBatchQueryDesc.preFilterShader PxQueryFilterCallback.preFilter PxBatchQueryPostFilterShader
220
221*/
222
223/**
224\param[in] queryFilterData Query filter data
225\param[in] objectFilterData Object filter data
226\param[in] constantBlock Global constant filter data (see #PxBatchQuery)
227\param[in] constantBlockSize Size of global filter data (see #PxBatchQuery)
228\param[in,out] hitFlags Per-object modifiable hit flags (only flags from PxHitFlag::eMODIFIABLE_FLAGS mask can be modified)
229\return the updated hit type for this hit (see #PxQueryHitType)
230
231@see PxBatchQueryPostFilterShader
232*/
233typedef PX_DEPRECATED PxQueryHitType::Enum (*PxBatchQueryPreFilterShader)(
234 PxFilterData queryFilterData, PxFilterData objectFilterData,
235 const void* constantBlock, PxU32 constantBlockSize,
236 PxHitFlags& hitFlags);
237
238/**
239\brief Batched query post-filter shader.
240
241Custom filtering logic for batched query intersection candidates. If an intersection candidate object passes the data based filter (see #PxQueryFilterData),
242the filtering shader run on request (see #PxQueryFilterData.flags)
243
244\li If #PxQueryFlag::ePOSTFILTER is set, the postFilter shader is called for each intersection to determine the touch/block status.
245This overrides any touch/block status previously returned from the preFilter function for this shape.
246
247Filtering shaders are not in order along the query direction, rather they are processed in the order in which
248candidate shapes for testing are found by PhysX' scene traversal algorithms.
249
250\deprecated The batched query feature has been deprecated in PhysX version 3.4
251
252@see PxBatchQueryDesc.postFilterShader PxQueryFilterCallback.postFilter PxBatchQueryPreFilterShader
253*/
254
255/**
256\param[in] queryFilterData Query filter data
257\param[in] objectFilterData Object filter data
258\param[in] constantBlock Global constant filter data (see #PxBatchQuery)
259\param[in] constantBlockSize Size of global filter data (see #PxBatchQuery)
260\param[in] hit Hit data from the prior exact intersection test.
261\return the new hit type for this hit (see #PxQueryHitType)
262
263@see PxBatchQueryPreFilterShader
264*/
265
266typedef PX_DEPRECATED PxQueryHitType::Enum (*PxBatchQueryPostFilterShader)(
267 PxFilterData queryFilterData, PxFilterData objectFilterData,
268 const void* constantBlock, PxU32 constantBlockSize,
269 const PxQueryHit& hit);
270
271#if !PX_DOXYGEN
272} // namespace physx
273#endif
274
275/** @} */
276#endif
277

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