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 |
43 | namespace physx |
44 | { |
45 | #endif |
46 | |
47 | class PxShape; |
48 | class PxRigidActor; |
49 | struct PxQueryHit; |
50 | |
51 | |
52 | /** |
53 | \brief Filtering flags for scene queries. |
54 | |
55 | @see PxQueryFilterData.flags |
56 | */ |
57 | struct 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 | }; |
78 | PX_COMPILE_TIME_ASSERT(PxQueryFlag::eSTATIC==(1<<0)); |
79 | PX_COMPILE_TIME_ASSERT(PxQueryFlag::eDYNAMIC==(1<<1)); |
80 | |
81 | /** |
82 | \brief Flags typedef for the set of bits defined in PxQueryFlag. |
83 | |
84 | */ |
85 | typedef PxFlags<PxQueryFlag::Enum,PxU16> PxQueryFlags; |
86 | PX_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 | |
98 | All hits in overlap() queries are treated as if the intersection distance were zero. |
99 | This means the hits are unsorted and all eTOUCH hits are recorded by the callback even if an eBLOCK overlap hit was encountered. |
100 | Even though all overlap() blocking hits have zero length, only one (arbitrary) eBLOCK overlap hit is recorded in PxHitCallback::block. |
101 | All overlap() eTOUCH type hits are reported (zero touchDistance <= zero blockDistance condition). |
102 | |
103 | For raycast/sweep/overlap calls with zero touch buffer or PxHitCallback::nbTouches member, |
104 | only 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 | */ |
108 | struct 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 | |
121 | Whenever 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 |
124 | queryFilterData 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 |
127 | to 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 | */ |
132 | struct 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 | |
150 | Custom 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. |
154 | If this function returns #PxQueryHitType::eTOUCH or #PxQueryHitType::eBLOCK, exact testing is performed to |
155 | determine the intersection location. |
156 | |
157 | The preFilter function may overwrite the copy of queryFlags it receives as an argument to specify any of #PxHitFlag::eMODIFIABLE_FLAGS |
158 | on 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. |
163 | This overrides any touch/block status previously returned from the preFilter function for this shape. |
164 | |
165 | Filtering 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 | */ |
169 | class PxQueryFilterCallback |
170 | { |
171 | public: |
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 | |
203 | Custom filtering logic for batched query intersection candidates. If an intersection candidate object passes the data based filter (see #PxQueryFilterData), |
204 | filtering 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. |
207 | If the shader returns #PxQueryHitType::eTOUCH or #PxQueryHitType::eBLOCK, exact testing is performed to |
208 | determine the intersection location. |
209 | |
210 | The preFilter shader may overwrite the copy of queryFlags it receives as an argument to specify any of #PxHitFlag::eMODIFIABLE_FLAGS |
211 | on 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 | |
215 | Filtering 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 | */ |
233 | typedef 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 | |
241 | Custom filtering logic for batched query intersection candidates. If an intersection candidate object passes the data based filter (see #PxQueryFilterData), |
242 | the 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. |
245 | This overrides any touch/block status previously returned from the preFilter function for this shape. |
246 | |
247 | Filtering shaders are not in order along the query direction, rather they are processed in the order in which |
248 | candidate 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 | |
266 | typedef 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 | |