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_SCENEQUERY
15#define PX_PHYSICS_NX_SCENEQUERY
16/** \addtogroup scenequery
17@{ */
18
19#include "PxPhysXConfig.h"
20#include "PxShape.h"
21#include "PxBatchQueryDesc.h"
22#include "PxQueryReport.h"
23#include "PxQueryFiltering.h"
24
25#ifndef PX_DOXYGEN
26namespace physx
27{
28#endif
29
30class PxBoxGeometry;
31class PxSphereGeometry;
32struct PxQueryCache;
33
34/**
35\brief Batched queries object. This is used to perform several queries at the same time.
36
37@see PxScene, PxScene.createBatchQuery
38*/
39class PxBatchQuery
40{
41 public:
42
43 /**
44 \brief Executes batched queries.
45 */
46 virtual void execute() = 0;
47
48 /**
49 \brief Gets the prefilter shader in use for this scene query.
50
51 \return Prefilter shader.
52
53 @see PxBatchQueryDesc.preFilterShade PxBatchQueryPreFilterShader
54 */
55 virtual PxBatchQueryPreFilterShader getPreFilterShader() const = 0;
56
57 /**
58 \brief Gets the postfilter shader in use for this scene query.
59
60 \return Postfilter shader.
61
62 @see PxBatchQueryDesc.preFilterShade PxBatchQueryPostFilterShader
63 */
64 virtual PxBatchQueryPostFilterShader getPostFilterShader() const = 0;
65
66
67 /**
68 \brief Gets the shared global filter data in use for this scene query.
69
70 \return Shared filter data for filter shader.
71
72 @see getFilterShaderDataSize() PxBatchQueryDesc.filterShaderData PxBatchQueryPreFilterShader, PxBatchQueryPostFilterShader
73 */
74 virtual const void* getFilterShaderData() const = 0;
75
76 /**
77 \brief Gets the size of the shared global filter data (#PxSceneDesc.filterShaderData)
78
79 \return Size of shared filter data [bytes].
80
81 @see getFilterShaderData() PxBatchQueryDesc.filterShaderDataSize PxBatchQueryPreFilterShader, PxBatchQueryPostFilterShader
82 */
83 virtual PxU32 getFilterShaderDataSize() const = 0;
84
85
86 /**
87 \brief Retrieves the client specified with PxBatchQueryDesc::ownerClient at creation time.
88
89 It is not possible to change this value after creating the scene query.
90
91 @see PxBatchQueryDesc::ownerClient
92 */
93 virtual PxClientID getOwnerClient() const = 0;
94
95 /**
96 \brief Sets new user memory pointers.
97
98 It is not possible to change the memory during query execute.
99
100 @see PxBatchQueryDesc
101 */
102 virtual void setUserMemory(const PxBatchQueryMemory&) = 0;
103
104 /**
105 \brief Gets the user memory pointers.
106
107 @see PxBatchQueryDesc
108 */
109 virtual const PxBatchQueryMemory& getUserMemory() = 0;
110
111 /**
112 \brief Releases PxBatchQuery from PxScene
113
114 @see PxScene, PxScene.createBatchQuery
115 */
116 virtual void release() = 0;
117
118
119 /**
120 \brief PS3 only. Enables or disables SPU execution for this query.
121
122 @see PxBatchQueryDesc
123 */
124 virtual void setRunOnSpu(bool runOnSpu) = 0;
125
126 /**
127 \brief PS3 only. Returns true if this query should run on SPU.
128
129 @see PxBatchQueryDesc
130 */
131 virtual bool getRunOnSpu() = 0;
132
133 /**
134 \brief Performs a raycast against objects in the scene, returns results in PxBatchQueryMemory::userRaycastResultBuffer
135 specified at PxBatchQuery creation time or via PxBatchQuery::setUserMemory call.
136
137 \note Touching hits are not ordered.
138 \note Shooting a ray from within an object leads to different results depending on the shape type. Please check the details in article SceneQuery. User can ignore such objects by using one of the provided filter mechanisms.
139
140 \param[in] origin Origin of the ray.
141 \param[in] unitDir Normalized direction of the ray.
142 \param[in] distance Length of the ray. Needs to be larger than 0.
143 \param[in] maxTouchHits Maximum number of hits to record in the touch buffer for this query. Default=0 reports a single blocking hit. If maxTouchHits is set to 0 all hits are treated as blocking by default.
144 \param[in] hitFlags Specifies which properties per hit should be computed and returned in hit array and blocking hit.
145 \param[in] filterData Filtering data passed to the filer shader. See #PxQueryFilterData #PxBatchQueryPreFilterShader, #PxBatchQueryPostFilterShader
146 \param[in] userData User can pass any value in this argument, usually to identify this particular query
147 \param[in] cache Cached hit shape (optional). Query is tested against cached shape first. If no hit is found the ray gets queried against the scene.
148 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
149 Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
150
151 \note This query call writes to a list associated with the query object and is NOT thread safe (for performance reasons there is no lock
152 and overlapping writes from different threads may result in undefined behavior).
153
154 @see PxQueryFilterData PxBatchQueryPreFilterShader PxBatchQueryPostFilterShader PxRaycastHit PxScene::raycast
155 */
156 virtual void raycast(
157 const PxVec3& origin, const PxVec3& unitDir, PxReal distance = PX_MAX_F32, PxU16 maxTouchHits = 0,
158 PxHitFlags hitFlags = PxHitFlag::ePOSITION|PxHitFlag::eNORMAL|PxHitFlag::eDISTANCE,
159 const PxQueryFilterData& filterData = PxQueryFilterData(),
160 void* userData = NULL, const PxQueryCache* cache = NULL) = 0;
161
162
163 /**
164 \brief Performs an overlap test of a given geometry against objects in the scene, returns results in PxBatchQueryMemory::userOverlapResultBuffer
165 specified at PxBatchQuery creation time or via PxBatchQuery::setUserMemory call.
166
167 \note Filtering: returning eBLOCK from user filter for overlap queries will cause a warning (see #PxQueryHitType).
168
169 \param[in] geometry Geometry of object to check for overlap (supported types are: box, sphere, capsule, convex).
170 \param[in] pose Pose of the object.
171 \param[in] maxTouchHits Maximum number of hits to record in the touch buffer for this query. Default=0 reports a single blocking hit. If maxTouchHits is set to 0 all hits are treated as blocking by default.
172 \param[in] filterData Filtering data and simple logic. See #PxQueryFilterData #PxBatchQueryPreFilterShader, #PxBatchQueryPostFilterShader
173 \param[in] userData User can pass any value in this argument, usually to identify this particular query
174 \param[in] cache Cached hit shape (optional). Query is tested against cached shape first. If no hit is found the ray gets queried against the scene.
175 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
176 Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
177
178 \note eBLOCK should not be returned from user filters for overlap(). Doing so will result in undefined behavior, and a warning will be issued.
179 \note If the PxQueryFlag::eNO_BLOCK flag is set, the eBLOCK will instead be automatically converted to an eTOUCH and the warning suppressed.
180 \note This query call writes to a list associated with the query object and is NOT thread safe (for performance reasons there is no lock
181 and overlapping writes from different threads may result in undefined behavior).
182
183 @see PxQueryFilterData PxBatchQueryPreFilterShader PxBatchQueryPostFilterShader
184 */
185 virtual void overlap(
186 const PxGeometry& geometry, const PxTransform& pose, PxU16 maxTouchHits = 0,
187 const PxQueryFilterData& filterData = PxQueryFilterData(), void* userData=NULL, const PxQueryCache* cache = NULL) = 0;
188
189 /**
190 \brief Performs a sweep test against objects in the scene, returns results in PxBatchQueryMemory::userSweepResultBuffer
191 specified at PxBatchQuery creation time or via PxBatchQuery::setUserMemory call.
192
193 \note Touching hits are not ordered.
194 \note If a shape from the scene is already overlapping with the query shape in its starting position,
195 the hit is returned unless eASSUME_NO_INITIAL_OVERLAP was specified.
196
197 \param[in] geometry Geometry of object to sweep (supported types are: box, sphere, capsule, convex).
198 \param[in] pose Pose of the sweep object.
199 \param[in] unitDir Normalized direction of the sweep.
200 \param[in] distance Sweep distance. Needs to be larger than 0. Will be clamped to PX_MAX_SWEEP_DISTANCE.
201 \param[in] maxTouchHits Maximum number of hits to record in the touch buffer for this query. Default=0 reports a single blocking hit. If maxTouchHits is set to 0 all hits are treated as blocking by default.
202 \param[in] hitFlags Specifies which properties per hit should be computed and returned in hit array and blocking hit.
203 \param[in] filterData Filtering data and simple logic. See #PxQueryFilterData #PxBatchQueryPreFilterShader, #PxBatchQueryPostFilterShader
204 \param[in] userData User can pass any value in this argument, usually to identify this particular query
205 \param[in] cache Cached hit shape (optional). Query is tested against cached shape first. If no hit is found the ray gets queried against the scene.
206 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
207 Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
208 \param[in] inflation This parameter creates a skin around the swept geometry which increases its extents for sweeping. The sweep will register a hit as soon as the skin touches a shape, and will return the corresponding distance and normal.
209 Note: ePRECISE_SWEEP doesn't support inflation. Therefore the sweep will be performed with zero inflation.
210
211 \note This query call writes to a list associated with the query object and is NOT thread safe (for performance reasons there is no lock
212 and overlapping writes from different threads may result in undefined behavior).
213
214 @see PxHitFlags PxQueryFilterData PxBatchQueryPreFilterShader PxBatchQueryPostFilterShader PxSweepHit
215 */
216 virtual void sweep(
217 const PxGeometry& geometry, const PxTransform& pose, const PxVec3& unitDir, const PxReal distance,
218 PxU16 maxTouchHits = 0, PxHitFlags hitFlags = PxHitFlag::ePOSITION|PxHitFlag::eNORMAL|PxHitFlag::eDISTANCE,
219 const PxQueryFilterData& filterData = PxQueryFilterData(), void* userData=NULL, const PxQueryCache* cache = NULL,
220 const PxReal inflation = 0.f) = 0;
221
222protected:
223 virtual ~PxBatchQuery() {}
224};
225
226#ifndef PX_DOXYGEN
227} // namespace physx
228#endif
229
230/** @} */
231#endif
232