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_SCENEQUERYDESC
15#define PX_PHYSICS_NX_SCENEQUERYDESC
16/** \addtogroup physics
17@{ */
18
19#include "PxPhysXConfig.h"
20#include "PxClient.h"
21#include "PxFiltering.h"
22#include "PxQueryFiltering.h"
23#include "PxQueryReport.h"
24
25#ifndef PX_DOXYGEN
26namespace physx
27{
28#endif
29
30struct PxSweepHit;
31struct PxRaycastHit;
32
33struct PxBatchQueryStatus
34{
35 enum Enum
36 {
37 /**
38 \brief This is the initial state before a query starts.
39 */
40 ePENDING = 0,
41
42 /**
43 \brief The query is finished; results have been written into the result and hit buffers.
44 */
45 eSUCCESS,
46
47 /**
48 \brief The query results were incomplete due to touch hit buffer overflow. Blocking hit is still correct.
49 */
50 eOVERFLOW
51 };
52};
53
54/**
55\brief Generic struct for receiving results of single query in a batch. Gets templated on hit type PxRaycastHit, PxSweepHit or PxOverlapHit.
56*/
57template<typename HitType>
58struct PxBatchQueryResult
59{
60 HitType block; //!< Holds the closest blocking hit for a single query in a batch. Only valid if hasBlock is true.
61 HitType* touches; //!< This pointer will either be set to NULL for 0 nbTouches or will point
62 //!< into the user provided batch query results buffer specified in PxBatchQueryDesc.
63 PxU32 nbTouches; //!< Number of touching hits returned by this query, works in tandem with touches pointer.
64 void* userData; //!< Copy of the userData pointer specified in the corresponding query.
65 PxU8 queryStatus; //!< Takes on values from PxBatchQueryStatus::Enum.
66 bool hasBlock; //!< True if there was a blocking hit.
67 PxU16 pad; //!< pads the struct to 16 bytes.
68
69 /** \brief Computes the number of any hits in this result, blocking or touching. */
70 PX_INLINE PxU32 getNbAnyHits() const { return nbTouches + (hasBlock ? 1 : 0); }
71
72 /** \brief Convenience iterator used to access any hits in this result, blocking or touching. */
73 PX_INLINE const HitType& getAnyHit(const PxU32 index) const { PX_ASSERT(index < nbTouches + (hasBlock ? 1 : 0));
74 return index < nbTouches ? touches[index] : block; }
75};
76
77/** \brief Convenience typedef for the result of a batched raycast query. */
78typedef PxBatchQueryResult<PxRaycastHit> PxRaycastQueryResult;
79
80/** \brief Convenience typedef for the result of a batched sweep query. */
81typedef PxBatchQueryResult<PxSweepHit> PxSweepQueryResult;
82
83/** \brief Convenience typedef for the result of a batched overlap query. */
84typedef PxBatchQueryResult<PxOverlapHit> PxOverlapQueryResult;
85
86/**
87\brief Struct for #PxBatchQuery memory pointers.
88
89@see PxBatchQuery PxBatchQueryDesc
90*/
91struct PxBatchQueryMemory
92 {
93 /**
94 \brief The pointer to the user-allocated buffer for results of raycast queries in corresponding order of issue
95
96 \note The size should be large enough to fit the number of expected raycast queries.
97 \note For ps3, this must be 16 bytes aligned and not on stack
98
99 @see PxRaycastQueryResult
100 */
101 PxRaycastQueryResult* userRaycastResultBuffer;
102
103 /**
104 \brief The pointer to the user-allocated buffer for raycast touch hits.
105 \note The size of this buffer should be large enough to store PxRaycastHit.
106 If the buffer is too small to store hits, the related PxRaycastQueryResult.queryStatus will be set to eOVERFLOW
107 \note For ps3, this buffer must be 16 bytes aligned and not on stack
108
109 */
110 PxRaycastHit* userRaycastTouchBuffer;
111
112 /**
113 \brief The pointer to the user-allocated buffer for results of sweep queries in corresponding order of issue
114
115 \note The size should be large enough to fit the number of expected sweep queries.
116 \note For ps3, this must be 16 bytes aligned and not on stack
117
118 @see PxRaycastQueryResult
119 */
120 PxSweepQueryResult* userSweepResultBuffer;
121
122 /**
123 \brief The pointer to the user-allocated buffer for sweep hits.
124 \note The size of this buffer should be large enough to store PxSweepHit.
125 If the buffer is too small to store hits, the related PxSweepQueryResult.queryStatus will be set to eOVERFLOW
126 \note For ps3, this buffer must be 16 bytes aligned and not on stack
127
128 */
129 PxSweepHit* userSweepTouchBuffer;
130
131 /**
132 \brief The pointer to the user-allocated buffer for results of overlap queries in corresponding order of issue
133
134 \note The size should be large enough to fit the number of expected overlap queries.
135 \note For ps3, this must be 16 bytes aligned and not on stack
136
137 @see PxRaycastQueryResult
138 */
139 PxOverlapQueryResult* userOverlapResultBuffer;
140
141 /**
142 \brief The pointer to the user-allocated buffer for overlap hits.
143 \note The size of this buffer should be large enough to store the hits returned.
144 If the buffer is too small to store hits, the related PxOverlapQueryResult.queryStatus will be set to eABORTED
145 \note For ps3, this buffer must be 16 bytes aligned and not on stack
146
147 */
148 PxOverlapHit* userOverlapTouchBuffer;
149
150 /** \brief Capacity of the user-allocated userRaycastTouchBuffer in elements */
151 PxU32 raycastTouchBufferSize;
152
153 /** \brief Capacity of the user-allocated userSweepTouchBuffer in elements */
154 PxU32 sweepTouchBufferSize;
155
156 /** \brief Capacity of the user-allocated userOverlapTouchBuffer in elements */
157 PxU32 overlapTouchBufferSize;
158
159 /** \return Capacity of the user-allocated userRaycastResultBuffer in elements (max number of raycast() calls before execute() call) */
160 PX_FORCE_INLINE PxU32 getMaxRaycastsPerExecute() const { return raycastResultBufferSize; }
161
162 /** \return Capacity of the user-allocated userSweepResultBuffer in elements (max number of sweep() calls before execute() call) */
163 PX_FORCE_INLINE PxU32 getMaxSweepsPerExecute() const { return sweepResultBufferSize; }
164
165 /** \return Capacity of the user-allocated userOverlapResultBuffer in elements (max number of overlap() calls before execute() call) */
166 PX_FORCE_INLINE PxU32 getMaxOverlapsPerExecute() const { return overlapResultBufferSize; }
167
168 PxBatchQueryMemory(PxU32 raycastResultBufferSize_, PxU32 sweepResultBufferSize_, PxU32 overlapResultBufferSize_) :
169 userRaycastResultBuffer (NULL),
170 userRaycastTouchBuffer (NULL),
171 userSweepResultBuffer (NULL),
172 userSweepTouchBuffer (NULL),
173 userOverlapResultBuffer (NULL),
174 userOverlapTouchBuffer (NULL),
175 raycastTouchBufferSize (0),
176 sweepTouchBufferSize (0),
177 overlapTouchBufferSize (0),
178 raycastResultBufferSize (raycastResultBufferSize_),
179 sweepResultBufferSize (sweepResultBufferSize_),
180 overlapResultBufferSize (overlapResultBufferSize_)
181 {
182 }
183
184protected:
185 PxU32 raycastResultBufferSize;
186 PxU32 sweepResultBufferSize;
187 PxU32 overlapResultBufferSize;
188};
189
190/**
191\brief Maximum allowed size for combined SPU shader code and data size.
192*/
193#define PX_QUERY_SPU_SHADER_LIMIT 2048
194
195/**
196\brief Descriptor class for #PxBatchQuery.
197
198@see PxBatchQuery PxSceneQueryExecuteMode
199*/
200class PxBatchQueryDesc
201{
202public:
203
204 /**
205 \brief Shared global filter data which will get passed into the filter shader.
206
207 \note The provided data will get copied to internal buffers and this copy will be used for filtering calls.
208
209 <b>Default:</b> NULL
210
211 @see PxSimulationFilterShader
212 */
213 void* filterShaderData;
214
215 /**
216 \brief Size (in bytes) of the shared global filter data #filterShaderData.
217
218 <b>Default:</b> 0
219
220 @see PxSimulationFilterShader filterShaderData
221 */
222 PxU32 filterShaderDataSize;
223
224 /**
225 \brief The custom preFilter shader to use for filtering.
226
227 @see PxBatchQueryPreFilterShader PxDefaultPreFilterShader
228 */
229 PxBatchQueryPreFilterShader preFilterShader;
230
231 /**
232 \brief The custom postFilter shader to use for filtering.
233
234 @see PxBatchQueryPostFilterShader PxDefaultPostFilterShader
235 */
236 PxBatchQueryPostFilterShader postFilterShader;
237
238 /**
239 \brief The custom spu pre filter shader to use for collision filtering.
240
241 \note This parameter is a fragment of SPU binary codes with the similar function of #PxBatchQueryPreFilterShader.
242 The requirement of the spu function is the same as PxBatchQueryPreFilterShader::filter. To compile the shader for
243 spu, you can reference the implementation, makefile and awk scripts in SampleVehicle. If you don't want to define
244 your own filter shader you can just leave this variable as NULL.
245
246 <b>Platform specific:</b> Applies to PS3 only.
247
248 */
249 void* spuPreFilterShader;
250
251 /**
252 \brief Size (in bytes) of the spu pre filter shader codes #spuPreFilterShader
253
254 <b>Default:</b> 0
255
256 <b>Platform specific:</b> Applies to PS3 only.
257
258 \note spuPreFilterShaderSize+spuPostFilterShaderSize+filterShaderDataSize should <= PX_QUERY_SPU_SHADER_LIMIT
259
260 @see spuPreFilterShader
261 */
262 PxU32 spuPreFilterShaderSize;
263
264 /**
265 \brief The custom spu post filter shader to use for collision filtering.
266
267 \note This parameter is a fragment of SPU binary codes with the similar function of #PxBatchQueryPostFilterShader.
268 The requirement of the spu function is the same as PxBatchQueryPreFilterShader::filter. To compile the shader for
269 spu, you can reference the implementation, PreBuild configuration in the project file of SampleVehicle.If you don't want to define
270 your own filter shader you can just leave this variable as NULL.
271 library.
272
273 <b>Platform specific:</b> Applies to PS3 only.
274
275 */
276 void* spuPostFilterShader;
277
278 /**
279 \brief Size (in bytes) of the spu post filter shader codes #spuPostFilterShader
280
281 <b>Default:</b> 0
282
283 <b>Platform specific:</b> Applies to PS3 only.
284
285 \note spuPreFilterShaderSize+spuPostFilterShaderSize+filterShaderDataSize should <= PX_QUERY_SPU_SHADER_LIMIT
286
287 @see spuPostFilterShader
288 */
289 PxU32 spuPostFilterShaderSize;
290
291 /**
292 \brief client that creates and owns this scene query.
293
294 This value will be used as an override when PX_DEFAULT_CLIENT value is passed to the query in PxQueryFilterData.clientId.
295
296 @see PxScene::createClient()
297 */
298 PxClientID ownerClient;
299
300 /**
301 \brief User memory buffers for the query.
302
303 @see PxBatchQueryMemory
304 */
305 PxBatchQueryMemory queryMemory;
306
307 /**
308 \brief PS3 only. Enables or disables SPU execution for this batch.
309
310 Defaults to true on PS3, ignored on other platforms.
311 */
312 bool runOnSpu;
313
314 /**
315 \brief Construct a batch query with specified maximum number of queries per batch.
316
317 If the number of raycasts/sweeps/overlaps per execute exceeds the limit, the query will be discarded with a warning.
318
319 \param maxRaycastsPerExecute Maximum number of raycast() calls allowed before execute() call.
320 This has to match the amount of memory allocated for PxBatchQueryMemory::userRaycastResultBuffer.
321 \param maxSweepsPerExecute Maximum number of sweep() calls allowed before execute() call.
322 This has to match the amount of memory allocated for PxBatchQueryMemory::userSweepResultBuffer.
323 \param maxOverlapsPerExecute Maximum number of overlap() calls allowed before execute() call.
324 This has to match the amount of memory allocated for PxBatchQueryMemory::userOverlapResultBuffer.
325 */
326 PX_INLINE PxBatchQueryDesc(PxU32 maxRaycastsPerExecute, PxU32 maxSweepsPerExecute, PxU32 maxOverlapsPerExecute);
327 PX_INLINE bool isValid() const;
328};
329
330
331PX_INLINE PxBatchQueryDesc::PxBatchQueryDesc(PxU32 maxRaycastsPerExecute, PxU32 maxSweepsPerExecute, PxU32 maxOverlapsPerExecute) :
332 filterShaderData (NULL),
333 filterShaderDataSize (0),
334 preFilterShader (NULL),
335 postFilterShader (NULL),
336 spuPreFilterShader (NULL),
337 spuPreFilterShaderSize (0),
338 spuPostFilterShader (NULL),
339 spuPostFilterShaderSize (0),
340 ownerClient (PX_DEFAULT_CLIENT),
341 queryMemory (maxRaycastsPerExecute, maxSweepsPerExecute, maxOverlapsPerExecute),
342 runOnSpu (true)
343{
344}
345
346
347PX_INLINE bool PxBatchQueryDesc::isValid() const
348{
349 if ( ((filterShaderDataSize == 0) && (filterShaderData != NULL)) ||
350 ((filterShaderDataSize > 0) && (filterShaderData == NULL)) )
351 return false;
352
353#if defined(PX_PS3)
354
355 if ( ((spuPreFilterShaderSize == 0) && (spuPreFilterShader != NULL)) ||
356 ((spuPreFilterShaderSize > 0) && (spuPreFilterShader == NULL)) ||
357 ((spuPostFilterShaderSize == 0) && (spuPostFilterShader != NULL)) ||
358 ((spuPostFilterShaderSize > 0) && (spuPostFilterShader == NULL)) )
359 return false;
360
361 if ( ((spuPreFilterShader != NULL) && (preFilterShader == NULL)) ||
362 ((spuPostFilterShader != NULL) && (postFilterShader == NULL)))
363 return false;
364
365 if ( ((spuPostFilterShaderSize + spuPreFilterShaderSize) > 0) &&
366 ((filterShaderDataSize + spuPostFilterShaderSize + spuPreFilterShaderSize) > PX_QUERY_SPU_SHADER_LIMIT) )
367 return false;
368
369#endif
370
371 return true;
372}
373
374#ifndef PX_DOXYGEN
375} // namespace physx
376#endif
377
378/** @} */
379#endif
380