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_PX_PARTICLEBASE
15#define PX_PHYSICS_PX_PARTICLEBASE
16/** \addtogroup particles
17 @{
18*/
19
20#include "PxPhysXConfig.h"
21#include "foundation/PxBounds3.h"
22#include "PxFiltering.h"
23#include "particles/PxParticleBaseFlag.h"
24#include "PxActor.h"
25#include "particles/PxParticleCreationData.h"
26#include "particles/PxParticleReadData.h"
27#include "PxForceMode.h"
28
29#ifndef PX_DOXYGEN
30namespace physx
31{
32#endif
33
34/**
35\brief The particle base class represents the shared module for particle based simulation. This class can't be instantiated.
36
37The particle base class manages a set of particles. Particles can be created, released and updated directly through the API.
38When a particle is created the user gets an index for it which can be used to address the particle until it is released again.
39
40Particles collide with static and dynamic shapes. They are also affected by the scene gravity and a user force,
41as well as global velocity damping. When a particle collides, a particle flag is raised corresponding to the type of
42actor, static or dynamic, it collided with. Additionally a shape can be flagged as a drain (See PxShapeFlag), in order to get a corresponding
43particle flag raised when a collision occurs. This information can be used to delete particles.
44
45@see PxParticleCreationData, PxParticleReadData, PxShapeFlag, PxParticleSystem, PxParticleFluid
46*/
47class PxParticleBase : public PxActor
48{
49
50 public:
51
52/************************************************************************************************/
53
54/** @name Particle Access and Manipulation
55*/
56//@{
57
58 /**
59 \brief Locks the particle data and provides the data descriptor for accessing the particles.
60 After reading from the buffers the application needs to call PxParticleReadData::unlock() before any
61 SDK operation can access the buffers. Particularly the buffers need to be unlocked before calling
62 PxParticleBase::lockParticleReadData(), PxParticleBase::createParticles(), PxParticleBase::releaseParticles(),
63 PxScene::fetchResults().
64
65 \param flags If PxDataAccessFlag::eDEVICE is specified for GPU particles then pointers to GPU memory will be returned otherwise it will be ignored.
66 \note PxDataAccessFlag::eWRITEABLE is not supported and will be ignored
67 \note If using PxDataAccessFlag::eDEVICE, newly created particles will not become visible in the GPU buffers until a subsequent simulation step has completed
68 @see PxParticleReadData
69 */
70 virtual PxParticleReadData* lockParticleReadData(PxDataAccessFlags flags) = 0;
71
72 /**
73 \brief Locks the particle read data and provides the data descriptor for accessing the particles
74 \note This method does the same as lockParticleReadData(PxDataAccessFlags::eREADABLE)
75 @see PxParticleReadData
76 */
77 virtual PxParticleReadData* lockParticleReadData() = 0;
78
79 /**
80 \brief Creates new particles.
81
82 The PxParticleCreationData descriptor is used to create new particles based on the provided PxParticleCreationData.
83 Providing particle indices and positions is mandatory. Indices need to be consistent with the available particle slots within
84 the range [0, maxParticles-1]. The new particles can be immediately read from the application readable
85 particle data, PxParticleReadData.
86
87 \param creationData specifies particle attributes for the particles to be created. (all buffers set have to be consistent with numParticles).
88 \return whether the operation was successful.
89
90 @see PxParticleCreationData, PxParticleReadData, PxParticlesExt.IndexPool
91 */
92 virtual bool createParticles(const PxParticleCreationData& creationData) = 0;
93
94 /**
95 \brief Releases particles.
96
97 Particles corresponding to passed indices are released. Releasing a particle will immediately mark the particle in the
98 application readable particle data, PxParticleReadData, as being invalid, removing PxParticleFlag::eVALID.
99 Passing duplicate indices is not allowed.
100
101 \param numParticles Number of particles to be released.
102 \param indexBuffer Structure describing indices of particles that should be deleted. (Has to be consistent with numParticles).
103
104 @see PxParticleReadData
105 */
106 virtual void releaseParticles(PxU32 numParticles, const PxStrideIterator<const PxU32>& indexBuffer) = 0;
107
108 /**
109 \brief Releases all particles.
110
111 Application readable particle data is updated accordingly.
112 */
113 virtual void releaseParticles() = 0;
114
115 /**
116 \brief Sets particle positions.
117
118 Directly sets the positions of particles. The supplied positions are used to change particles in the order of
119 the indices listed in the index buffer. Duplicate indices are allowed. A position buffer of stride zero is allowed.
120 Application readable particle data is updated accordingly.
121
122 \param numParticles Number of particle updates.
123 \param indexBuffer Structure describing indices of particles that should be updated. (Has to be consistent with numParticles).
124 \param positionBuffer Structure describing positions for position updates. (Has to be consistent with numParticles).
125 */
126 virtual void setPositions(PxU32 numParticles, const PxStrideIterator<const PxU32>& indexBuffer,
127 const PxStrideIterator<const PxVec3>& positionBuffer) = 0;
128
129 /**
130 \brief Sets particle velocities.
131
132 Directly sets the velocities of particles. The supplied velocities are used to change particles in the order of
133 the indices listed in the index buffer. Duplicate indices are allowed. A velocity buffer of stride zero is allowed.
134 Application readable particle data is updated accordingly.
135
136 \param numParticles Number of particle updates.
137 \param indexBuffer Structure describing indices of particles that should be updated. (Has to be consistent with numParticles).
138 \param velocityBuffer Structure describing velocities for velocity updates. (Has to be consistent with numParticles).
139 */
140 virtual void setVelocities(PxU32 numParticles, const PxStrideIterator<const PxU32>& indexBuffer,
141 const PxStrideIterator<const PxVec3>& velocityBuffer) = 0;
142
143 /**
144 \brief Sets particle rest offsets.
145
146 Directly sets the rest offsets of particles. The supplied rest offsets are used to change particles in the order of
147 the indices listed in the index buffer. The provided offsets need to be in the range [0.0f, restOffset].
148 Duplicate indices are allowed. A rest offset buffer of stride zero is allowed.
149 Application readable particle data is updated accordingly.
150
151 \param numParticles Number of particle updates.
152 \param indexBuffer Structure describing indices of particles that should be updated. (Has to be consistent with numParticles).
153 \param restOffsetBuffer Structure describing rest offsets for rest offset updates. (Has to be consistent with numParticles).
154
155 @see PxParticleBaseFlag.ePER_PARTICLE_REST_OFFSET
156 */
157 virtual void setRestOffsets(PxU32 numParticles, const PxStrideIterator<const PxU32>& indexBuffer,
158 const PxStrideIterator<const PxF32>& restOffsetBuffer) = 0;
159
160
161 /**
162 \brief Set forces to be applied to the particles when the simulation starts.
163
164 This call is ignored on particle system that aren't assigned to a scene.
165
166 \param numParticles Number of particle updates.
167 \param indexBuffer Structure describing indices of particles that should be updated. (Has to be consistent with numParticles).
168 \param forceBuffer Structure describing values for particle updates depending on forceMode. (Has to be consistent with numParticles).
169 \param forceMode Describes type of update.
170 */
171 virtual void addForces(PxU32 numParticles, const PxStrideIterator<const PxU32>& indexBuffer,
172 const PxStrideIterator<const PxVec3>& forceBuffer, PxForceMode::Enum forceMode) = 0;
173
174//@}
175/************************************************************************************************/
176
177/** @name ParticleBase Parameters
178*/
179//@{
180
181 /**
182 \brief Returns the particle system damping.
183
184 \return The particle system damping.
185 */
186 virtual PxReal getDamping() const = 0;
187
188 /**
189 \brief Sets the particle system damping (must be nonnegative).
190
191 \param damp The new particle system damping.
192 */
193 virtual void setDamping(PxReal damp) = 0;
194
195 /**
196 \brief Returns the external acceleration applied to each particle at each time step.
197
198 \return The external acceleration applied to particles.
199 */
200 virtual PxVec3 getExternalAcceleration() const = 0;
201
202 /**
203 \brief Sets the external acceleration applied to each particle at each time step.
204
205 \param acceleration External acceleration to apply to particles.
206
207 @see getExternalAcceleration()
208 */
209 virtual void setExternalAcceleration(const PxVec3&acceleration) = 0;
210
211 /**
212 \brief Returns the plane the particles are projected to.
213
214 \param[out] normal Particle projection plane normal
215 \param[out] distance Particle projection plane constant term
216 */
217 virtual void getProjectionPlane(PxVec3& normal, PxReal& distance) const = 0;
218
219 /**
220 \brief Sets the plane the particles are projected to.
221
222 Points p on the plane have to fulfill the equation:
223
224 (normal.x * p.x) + (normal.y * p.y) + (normal.z * p.z) + d = 0
225
226 \param[in] normal Particle projection plane normal
227 \param[in] distance Particle projection plane constant term
228 */
229 virtual void setProjectionPlane(const PxVec3& normal, PxReal distance) = 0;
230//@}
231/************************************************************************************************/
232
233/** @name Collisions
234*/
235//@{
236
237 /**
238 \brief Returns the mass of a particle.
239
240 \return Particle mass.
241 */
242 virtual PxReal getParticleMass() const = 0;
243
244 /**
245 \brief Sets the mass of a particle.
246
247 \param mass The particle mass.
248 */
249 virtual void setParticleMass(PxReal mass) = 0;
250
251 /**
252 \brief Returns the restitution used for collision with shapes.
253
254 \return The restitution.
255 */
256 virtual PxReal getRestitution() const = 0;
257
258 /**
259 \brief Sets the restitution used for collision with shapes.
260
261 Must be between 0 and 1.
262
263 \param rest The new restitution.
264 */
265 virtual void setRestitution(PxReal rest) = 0;
266
267 /**
268 \brief Returns the dynamic friction used for collision with shapes.
269
270 \return The dynamic friction.
271 */
272 virtual PxReal getDynamicFriction() const = 0;
273
274 /**
275 \brief Sets the dynamic friction used for collision with shapes.
276
277 Must be between 0 and 1.
278
279 \param friction The new dynamic friction
280 */
281 virtual void setDynamicFriction(PxReal friction) = 0;
282
283 /**
284 \brief Returns the static friction used for collision with shapes.
285
286 \return The static friction.
287 */
288 virtual PxReal getStaticFriction() const = 0;
289
290 /**
291 \brief Sets the static friction used for collision with shapes.
292
293 Must be non-negative.
294
295 \param friction The new static friction
296 */
297 virtual void setStaticFriction(PxReal friction) = 0;
298
299//@}
300/************************************************************************************************/
301
302/** @name Collision Filtering
303*/
304//@{
305
306 /**
307 \brief Sets the user definable collision filter data.
308
309 @see getSimulationFilterData()
310 */
311 virtual void setSimulationFilterData(const PxFilterData& data) = 0;
312
313 /**
314 \brief Retrieves the object's collision filter data.
315
316 @see setSimulationFilterData()
317 */
318 virtual PxFilterData getSimulationFilterData() const = 0;
319
320 /**
321 \deprecated
322 \brief Marks the object to reset interactions and re-run collision filters in the next simulation step.
323
324 \note This method has been deprecated. Please use #PxScene::resetFiltering() instead.
325 */
326 PX_DEPRECATED virtual void resetFiltering() = 0;
327
328//@}
329/************************************************************************************************/
330
331 /**
332 \brief Sets particle system flags.
333
334 \param flag Member of #PxParticleBaseFlag.
335 \param val New flag value.
336 */
337 virtual void setParticleBaseFlag(PxParticleBaseFlag::Enum flag, bool val) = 0;
338
339 /**
340 \brief Returns particle system flags.
341
342 \return The current flag values.
343 */
344 virtual PxParticleBaseFlags getParticleBaseFlags() const = 0;
345
346/************************************************************************************************/
347
348/** @name ParticleSystem Property Read Back
349*/
350//@{
351
352 /**
353 \brief Returns the maximum number of particles for this particle system.
354
355 \return Max number of particles for this particle system.
356 */
357 virtual PxU32 getMaxParticles() const = 0;
358
359 /**
360 \brief Returns the maximal motion distance (the particle can move the maximal distance of
361 getMaxMotionDistance() during one timestep).
362
363 \return maximum motion distance.
364 */
365 virtual PxReal getMaxMotionDistance() const = 0;
366
367 /**
368 \brief Sets the maximal motion distance (the particle can move the maximal distance
369 during one timestep). Immutable when the particle system is part of a scene.
370
371 \param distance New Max motionDistance value.
372 */
373 virtual void setMaxMotionDistance(PxReal distance) = 0;
374
375 /**
376 \brief Returns the distance between particles and collision geometry, which is maintained during simulation.
377
378 \return rest offset.
379 */
380 virtual PxReal getRestOffset() const = 0;
381
382 /**
383 \brief Sets the distance between particles and collision geometry, which is maintained during simulation.
384 If per particle restOffsets are used, they need to be in the range [0.0f, restOffset]. Immutable when the
385 particle system is part of a scene.
386 \param restOffset New restOffset value.
387 */
388 virtual void setRestOffset(PxReal restOffset) = 0;
389
390 /**
391 \brief Returns the distance at which contacts are generated between particles and collision geometry.
392
393 \return contact offset.
394 */
395 virtual PxReal getContactOffset() const = 0;
396
397 /**
398 \brief Sets the distance at which contacts are generated between particles and collision geometry.
399 Immutable when the particle system is part of a scene.
400
401 \param contactOffset New contactOffset value.
402 */
403 virtual void setContactOffset(PxReal contactOffset) = 0;
404
405 /**
406 \brief Returns the particle grid size used for internal spatial data structures.
407
408 The actual grid size used might differ from the grid size set in the setGridSize().
409
410 \return The grid size.
411 */
412 virtual PxReal getGridSize() const = 0;
413
414 /**
415 \brief Sets the particle grid size used for internal spatial data structures.
416 Immutable when the particle system is part of a scene.
417 The actual grid size used might differ from the grid size set in the setGridSize().
418
419 \param gridSize New gridSize value.
420 */
421 virtual void setGridSize(PxReal gridSize) = 0;
422
423 /**
424 \brief Returns particle read data flags.
425 \return The particle read data flags.
426 @see PxParticleReadDataFlags
427 */
428 virtual PxParticleReadDataFlags getParticleReadDataFlags() const = 0;
429
430 /**
431 \brief Sets particle read data flags.
432 \param flag Member of PxParticleReadDataFlag.
433 \param val New flag value.
434 @see PxParticleReadDataFlags
435 */
436 virtual void setParticleReadDataFlag(PxParticleReadDataFlag::Enum flag, bool val)= 0;
437
438protected:
439 PX_INLINE PxParticleBase(PxType concreteType, PxBaseFlags baseFlags) : PxActor(concreteType, baseFlags) {}
440 PX_INLINE PxParticleBase(PxBaseFlags baseFlags) : PxActor(baseFlags) {}
441 virtual ~PxParticleBase() {}
442 virtual bool isKindOf(const char* name) const { return !strcmp("PxParticleBase", name) || PxActor::isKindOf(name); }
443
444//@}
445/************************************************************************************************/
446};
447
448PX_DEPRECATED PX_INLINE PxParticleBase* PxActor::isParticleBase() { return is<PxParticleBase>(); }
449PX_DEPRECATED PX_INLINE const PxParticleBase* PxActor::isParticleBase() const { return is<PxParticleBase>(); }
450
451
452#ifndef PX_DOXYGEN
453} // namespace physx
454#endif
455
456/** @} */
457#endif
458