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