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_AGGREGATE
15#define PX_PHYSICS_NX_AGGREGATE
16
17/** \addtogroup physics
18@{
19*/
20
21#include "PxPhysXConfig.h"
22#include "common/PxBase.h"
23
24
25#ifndef PX_DOXYGEN
26namespace physx
27{
28#endif
29
30class PxActor;
31
32/**
33\brief Class to aggregate actors into a single broad phase entry.
34
35A PxAggregate object is a collection of PxActors, which will exist as a single entry in the
36broad-phase structures. This has 3 main benefits:
37
381) it reduces "broad phase pollution", where multiple objects of a single entity often overlap
39 all the time (e.g. typically in a ragdoll).
40
412) it reduces broad-phase memory usage (which can be vital e.g. on SPU)
42
433) filtering can be optimized a lot if self-collisions within an aggregate are not needed. For
44 example if you don't need collisions between ragdoll bones, it's faster to simply disable
45 filtering once and for all, for the aggregate containing the ragdoll, rather than filtering
46 out each bone-bone collision in the filter shader.
47
48@see PxActor, PxPhysics.createAggregate
49*/
50
51class PxAggregate : public PxBase
52{
53public:
54
55 /**
56 \brief Deletes the aggregate object.
57
58 Deleting the PxAggregate object does not delete the aggregated actors. If the PxAggregate object
59 belongs to a scene, the aggregated actors are automatically re-inserted in that scene. If you intend
60 to delete both the PxAggregate and its actors, it is best to release the actors first, then release
61 the PxAggregate when it is empty.
62 */
63 virtual void release() = 0;
64
65 /**
66 \brief Adds an actor to the aggregate object.
67
68 A warning is output if the total number of actors is reached, or if the incoming actor already belongs
69 to an aggregate.
70
71 If the aggregate belongs to a scene, adding an actor to the aggregate also adds the actor to that scene.
72
73 If the actor already belongs to a scene, a warning is output and the call is ignored. You need to remove
74 the actor from the scene first, before adding it to the aggregate.
75
76 \param [in] actor The actor that should be added to the aggregate
77 return true if success
78 */
79 virtual bool addActor(PxActor& actor) = 0;
80
81 /**
82 \brief Removes an actor from the aggregate object.
83
84 A warning is output if the incoming actor does not belong to the aggregate. Otherwise the actor is
85 removed from the aggregate. If the aggregate belongs to a scene, the actor is reinserted in that
86 scene. If you intend to delete the actor, it is best to call #PxActor::release() directly. That way
87 the actor will be automatically removed from its aggregate (if any) and not reinserted in a scene.
88
89 \param [in] actor The actor that should be removed from the aggregate
90 return true if success
91 */
92 virtual bool removeActor(PxActor& actor) = 0;
93
94 /**
95 \brief Adds an articulation to the aggregate object.
96
97 A warning is output if the total number of actors is reached (every articulation link counts as an actor),
98 or if the incoming articulation already belongs to an aggregate.
99
100 If the aggregate belongs to a scene, adding an articulation to the aggregate also adds the articulation to that scene.
101
102 If the articulation already belongs to a scene, a warning is output and the call is ignored. You need to remove
103 the articulation from the scene first, before adding it to the aggregate.
104
105 \param [in] articulation The articulation that should be added to the aggregate
106 return true if success
107 */
108 virtual bool addArticulation(PxArticulation& articulation) = 0;
109
110 /**
111 \brief Removes an articulation from the aggregate object.
112
113 A warning is output if the incoming articulation does not belong to the aggregate. Otherwise the articulation is
114 removed from the aggregate. If the aggregate belongs to a scene, the articulation is reinserted in that
115 scene. If you intend to delete the articulation, it is best to call #PxArticulation::release() directly. That way
116 the articulation will be automatically removed from its aggregate (if any) and not reinserted in a scene.
117
118 \param [in] articulation The articulation that should be removed from the aggregate
119 return true if success
120 */
121 virtual bool removeArticulation(PxArticulation& articulation) = 0;
122
123 /**
124 \brief Returns the number of actors contained in the aggregate.
125
126 You can use #getActors() to retrieve the actor pointers.
127
128 \return Number of actors contained in the aggregate.
129
130 @see PxActor getActors()
131 */
132 virtual PxU32 getNbActors() const = 0;
133
134 /**
135 \brief Retrieves max amount of actors that can be contained in the aggregate.
136
137 \return Max aggregate size.
138
139 @see PxPhysics::createAggregate()
140 */
141 virtual PxU32 getMaxNbActors() const = 0;
142
143 /**
144 \brief Retrieve all actors contained in the aggregate.
145
146 You can retrieve the number of actor pointers by calling #getNbActors()
147
148 \param[out] userBuffer The buffer to store the actor pointers.
149 \param[in] bufferSize Size of provided user buffer.
150 \param[in] startIndex Index of first actor pointer to be retrieved
151 \return Number of actor pointers written to the buffer.
152
153 @see PxShape getNbShapes()
154 */
155 virtual PxU32 getActors(PxActor** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
156
157 /**
158 \brief Retrieves the scene which this aggregate belongs to.
159
160 \return Owner Scene. NULL if not part of a scene.
161
162 @see PxScene
163 */
164 virtual PxScene* getScene() = 0;
165
166 /**
167 \brief Retrieves aggregate's self-collision flag.
168
169 \return self-collision flag
170 */
171 virtual bool getSelfCollision() const = 0;
172
173 virtual const char* getConcreteTypeName() const { return "PxAggregate"; }
174
175protected:
176 PX_INLINE PxAggregate(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags) {}
177 PX_INLINE PxAggregate(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
178 virtual ~PxAggregate() {}
179 virtual bool isKindOf(const char* name) const { return !strcmp("PxAggregate", name) || PxBase::isKindOf(name); }
180};
181
182#ifndef PX_DOXYGEN
183} // namespace physx
184#endif
185
186/** @} */
187#endif
188