1//
2// Redistribution and use in source and binary forms, with or without
3// modification, are permitted provided that the following conditions
4// are met:
5// * Redistributions of source code must retain the above copyright
6// notice, this list of conditions and the following disclaimer.
7// * Redistributions in binary form must reproduce the above copyright
8// notice, this list of conditions and the following disclaimer in the
9// documentation and/or other materials provided with the distribution.
10// * Neither the name of NVIDIA CORPORATION nor the names of its
11// contributors may be used to endorse or promote products derived
12// from this software without specific prior written permission.
13//
14// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
15// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
18// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25//
26// Copyright (c) 2008-2021 NVIDIA Corporation. All rights reserved.
27// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
28// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
29
30
31#ifndef PX_PHYSICS_NX_AGGREGATE
32#define PX_PHYSICS_NX_AGGREGATE
33
34/** \addtogroup physics
35@{
36*/
37
38#include "PxPhysXConfig.h"
39#include "common/PxBase.h"
40
41
42#if !PX_DOXYGEN
43namespace physx
44{
45#endif
46
47class PxActor;
48class PxBVHStructure;
49
50/**
51\brief Class to aggregate actors into a single broad-phase entry.
52
53A PxAggregate object is a collection of PxActors, which will exist as a single entry in the
54broad-phase structures. This has 3 main benefits:
55
561) it reduces "broad phase pollution" by allowing a collection of spatially coherent broad-phase
57entries to be replaced by a single aggregated entry (e.g. a ragdoll or a single actor with a
58large number of attached shapes).
59
602) it reduces broad-phase memory usage
61
623) filtering can be optimized a lot if self-collisions within an aggregate are not needed. For
63 example if you don't need collisions between ragdoll bones, it's faster to simply disable
64 filtering once and for all, for the aggregate containing the ragdoll, rather than filtering
65 out each bone-bone collision in the filter shader.
66
67@see PxActor, PxPhysics.createAggregate
68*/
69
70class PxAggregate : public PxBase
71{
72public:
73
74 /**
75 \brief Deletes the aggregate object.
76
77 Deleting the PxAggregate object does not delete the aggregated actors. If the PxAggregate object
78 belongs to a scene, the aggregated actors are automatically re-inserted in that scene. If you intend
79 to delete both the PxAggregate and its actors, it is best to release the actors first, then release
80 the PxAggregate when it is empty.
81 */
82 virtual void release() = 0;
83
84 /**
85 \brief Adds an actor to the aggregate object.
86
87 A warning is output if the total number of actors is reached, or if the incoming actor already belongs
88 to an aggregate.
89
90 If the aggregate belongs to a scene, adding an actor to the aggregate also adds the actor to that scene.
91
92 If the actor already belongs to a scene, a warning is output and the call is ignored. You need to remove
93 the actor from the scene first, before adding it to the aggregate.
94
95 \note When BVHStructure is provided the actor shapes are grouped together.
96 The scene query pruning structure inside PhysX SDK will store/update one
97 bound per actor. The scene queries against such an actor will query actor
98 bounds and then make a local space query against the provided BVH structure, which is in
99 actor's local space.
100
101 \param [in] actor The actor that should be added to the aggregate
102 \param [in] bvhStructure BVHStructure for actor shapes.
103 return true if success
104 */
105 virtual bool addActor(PxActor& actor, const PxBVHStructure* bvhStructure = NULL) = 0;
106
107 /**
108 \brief Removes an actor from the aggregate object.
109
110 A warning is output if the incoming actor does not belong to the aggregate. Otherwise the actor is
111 removed from the aggregate. If the aggregate belongs to a scene, the actor is reinserted in that
112 scene. If you intend to delete the actor, it is best to call #PxActor::release() directly. That way
113 the actor will be automatically removed from its aggregate (if any) and not reinserted in a scene.
114
115 \param [in] actor The actor that should be removed from the aggregate
116 return true if success
117 */
118 virtual bool removeActor(PxActor& actor) = 0;
119
120 /**
121 \brief Adds an articulation to the aggregate object.
122
123 A warning is output if the total number of actors is reached (every articulation link counts as an actor),
124 or if the incoming articulation already belongs to an aggregate.
125
126 If the aggregate belongs to a scene, adding an articulation to the aggregate also adds the articulation to that scene.
127
128 If the articulation already belongs to a scene, a warning is output and the call is ignored. You need to remove
129 the articulation from the scene first, before adding it to the aggregate.
130
131 \param [in] articulation The articulation that should be added to the aggregate
132 return true if success
133 */
134 virtual bool addArticulation(PxArticulationBase& articulation) = 0;
135
136 /**
137 \brief Removes an articulation from the aggregate object.
138
139 A warning is output if the incoming articulation does not belong to the aggregate. Otherwise the articulation is
140 removed from the aggregate. If the aggregate belongs to a scene, the articulation is reinserted in that
141 scene. If you intend to delete the articulation, it is best to call #PxArticulation::release() directly. That way
142 the articulation will be automatically removed from its aggregate (if any) and not reinserted in a scene.
143
144 \param [in] articulation The articulation that should be removed from the aggregate
145 return true if success
146 */
147 virtual bool removeArticulation(PxArticulationBase& articulation) = 0;
148
149 /**
150 \brief Returns the number of actors contained in the aggregate.
151
152 You can use #getActors() to retrieve the actor pointers.
153
154 \return Number of actors contained in the aggregate.
155
156 @see PxActor getActors()
157 */
158 virtual PxU32 getNbActors() const = 0;
159
160 /**
161 \brief Retrieves max amount of actors that can be contained in the aggregate.
162
163 \return Max aggregate size.
164
165 @see PxPhysics::createAggregate()
166 */
167 virtual PxU32 getMaxNbActors() const = 0;
168
169 /**
170 \brief Retrieve all actors contained in the aggregate.
171
172 You can retrieve the number of actor pointers by calling #getNbActors()
173
174 \param[out] userBuffer The buffer to store the actor pointers.
175 \param[in] bufferSize Size of provided user buffer.
176 \param[in] startIndex Index of first actor pointer to be retrieved
177 \return Number of actor pointers written to the buffer.
178
179 @see PxShape getNbShapes()
180 */
181 virtual PxU32 getActors(PxActor** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
182
183 /**
184 \brief Retrieves the scene which this aggregate belongs to.
185
186 \return Owner Scene. NULL if not part of a scene.
187
188 @see PxScene
189 */
190 virtual PxScene* getScene() = 0;
191
192 /**
193 \brief Retrieves aggregate's self-collision flag.
194
195 \return self-collision flag
196 */
197 virtual bool getSelfCollision() const = 0;
198
199 virtual const char* getConcreteTypeName() const { return "PxAggregate"; }
200
201protected:
202 PX_INLINE PxAggregate(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags) {}
203 PX_INLINE PxAggregate(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
204 virtual ~PxAggregate() {}
205 virtual bool isKindOf(const char* name) const { return !::strcmp(s1: "PxAggregate", s2: name) || PxBase::isKindOf(superClass: name); }
206};
207
208#if !PX_DOXYGEN
209} // namespace physx
210#endif
211
212/** @} */
213#endif
214

source code of qtquick3dphysics/src/3rdparty/PhysX/include/PxAggregate.h