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_EXTENSIONS_PARTICLEEXT_H
15#define PX_PHYSICS_EXTENSIONS_PARTICLEEXT_H
16/** \addtogroup extensions
17 @{
18*/
19
20#include "PxPhysXConfig.h"
21#include "foundation/PxStrideIterator.h"
22#include "foundation/PxBounds3.h"
23
24#ifndef PX_DOXYGEN
25namespace physx
26{
27#endif
28
29class PxParticleExt
30{
31public:
32
33 struct ParticleBounds
34 {
35 PxBounds3 bounds;
36 PxU32 firstParticle;
37 PxU32 numParticles;
38 };
39
40 /**
41 \brief Computes particle bounds by sorting particle positions into a spatial hash grid.
42
43 Given a strided array of particle positions, this function partitions the particles into
44 subsets of nearby particles by mapping the particle positions onto a 3-dimensional grid
45 and creating ParticleBounds data structures for each occupied grid cell.
46
47 Each returned ParticleBounds data structure can be used to determine the indices of the particles
48 belonging to the same grid cell. Particle indices of one grid cell are returned as contiguous
49 blocks in the sortedParticleIndices buffer and can be found within the range
50 [firstParticle, firstParticle + numParticles - 1]. Each returned ParticleBounds further contains
51 an AABB "bounds" that tightly fits all particle positions within the grid cell.
52
53 The number of created ParticleBounds can be retrieved via the return value. The user can cap the
54 maximum amount of generated ParticleBounds via the maxBounds parameter. Particles that would cause
55 this maximum to be exceeded will be skipped over and will not be part of any returned ParticleBounds.
56 (Note that this also hold when maxBounds is equal to hashSize. Thus, in the worst case, if no particle
57 should ever be skipped over by the algorithm "hashSize" must be at least equal to numParticles)
58
59 The user is responsible for allocating the output buffers sortedParticleIndices
60 (for at least numParticles entries) and particleBounds (for at least maxBounds entries).
61
62 The size of a cubical grid cell can be tuned by setting the gridSpacing parameter.
63
64 The user supplied hashSize must be a power of two.
65
66 \param[out] sortedParticleIndices Pointer to user allocated array of size numParticles where the sorted particle indices will be written to.
67 \param[out] particleBounds Pointer to user allocated array of size maxBounds where the ParticleBounds will be written to.
68 \param[in] positionBuffer Strided data of input particle positions.
69 \param[in] validParticleRange Range of valid particles within validParticleBitmap. (See PxParticleReadData.validParticleRange).
70 \param[in] validParticleBitmap Bitmap specifying valid slots in positionBuffer. (See PxParticleReadData.validParticleBitmap).
71 \param[in] hashSize Hash size used internally by the hashing algorithm. Must be a power of two.
72 \param[in] maxBounds Maximum number of bounds to be returned. Must be smaller or equal than hashSize.
73 \param[in] gridSpacing Side length of each cubical grid cell.
74 \return PxU32. Number of ParticleBounds data structures written to the particleBounds buffer. Smaller or equal than maxBounds.
75
76 */
77 static PxU32 buildBoundsHash(PxU32* sortedParticleIndices,
78 ParticleBounds* particleBounds,
79 const PxStrideIterator<const PxVec3>& positionBuffer,
80 const PxU32 validParticleRange,
81 const PxU32* validParticleBitmap,
82 const PxU32 hashSize,
83 const PxU32 maxBounds,
84 const PxReal gridSpacing);
85
86 /**
87 \brief Class to manage particle indices.
88 Extension particle index management can be useful if no application side particle index allocation
89 functionality is available. An PxParticleExt::IndexPool instance is meant to be used for one
90 PxParticleSystem/PxParticleFluid instance.
91 The instance can be created with PxParticleExt::createIndexPool().
92
93 @see PxParticleExt::createIndexPool()
94 */
95 class IndexPool
96 {
97 public:
98 /**
99 \brief Allocates a requested number of indices if possible.
100 \param[in] num Number of indices that should be allocated.
101 \param[out] indexBuffer Strided data to which allocated indices are written.
102 \return PxU32. Number of indices that where allocated by the operation.
103 */
104 virtual PxU32 allocateIndices(PxU32 num, const PxStrideIterator<PxU32>& indexBuffer) = 0;
105
106 /**
107 \brief Deallocates a requested number of indices.
108 \param[in] num Number of indices that should be freed.
109 \param[in] indexBuffer Strided data describing the indices that need to be freed. It's a requirement
110 to specify unique indices, that where previously allocated by PxParticlesExt::allocateIndices()
111 */
112 virtual void freeIndices(PxU32 num, const PxStrideIterator<const PxU32>& indexBuffer) = 0;
113
114 /**
115 \brief Deallocates all previously allocated indices.
116 */
117 virtual void freeIndices() = 0;
118
119 /**
120 \brief Releases IndexPool instance.
121 */
122 virtual void release() = 0;
123
124 /**
125 \brief virtual destructor
126 */
127 virtual ~IndexPool() {}
128 };
129
130 /**
131 \brief Creates a PxParticlesExt::IndexPool instance.
132 \param[in] maxParticles Maximum number of available indices.
133 */
134 static IndexPool* createIndexPool(PxU32 maxParticles);
135
136 /**
137 \brief Creates a PxParticlesExt::IndexPool instance initialized with a preallocated set of indices specified with a bitmap.
138 \param[in] maxParticles Maximum number of available indices.
139 \param[in] validParticleRange Range of indices represented in validParticleBitmap. (See PxParticleReadData.validParticleRange).
140 \param[in] validParticleBitmap Bitmap specifying the valid particle indices that should be preallocated. (See PxParticleReadData.validParticleBitmap).
141 */
142 static IndexPool* createIndexPool(PxU32 maxParticles, PxU32 validParticleRange, const PxU32* validParticleBitmap);
143
144};
145
146#ifndef PX_DOXYGEN
147} // namespace physx
148#endif
149
150/** @} */
151#endif
152