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_PX_COLLECTION
32#define PX_PHYSICS_PX_COLLECTION
33
34#include "common/PxSerialFramework.h"
35
36/** \addtogroup common
37@{
38*/
39
40#if !PX_DOXYGEN
41namespace physx
42{
43#endif
44
45class PxBase;
46
47/**
48\brief Collection class for serialization.
49
50A collection is a set of PxBase objects. PxBase objects can be added to the collection
51regardless of other objects they depend on. Objects may be named using PxSerialObjectId values in order
52to resolve dependencies between objects of different collections.
53
54Serialization and deserialization only work through collections.
55
56A scene is typically serialized using the following steps:
57
58 -# create a serialization registry
59 -# create a collection for scene objects
60 -# complete the scene objects (adds all dependent objects, e.g. meshes)
61 -# serialize collection
62 -# release collection
63 -# release serialization registry
64
65For example the code may look like this:
66
67\code
68 PxPhysics* physics; // The physics
69 PxScene* scene; // The physics scene
70 SerialStream s; // The user-defined stream doing the actual write to disk
71
72 PxSerializationRegistry* registry = PxSerialization::createSerializationRegistry(*physics); // step 1)
73 PxCollection* collection = PxSerialization::createCollection(*scene); // step 2)
74 PxSerialization::complete(*collection, *registry); // step 3)
75 PxSerialization::serializeCollectionToBinary(s, *collection, *registry); // step 4)
76 collection->release(); // step 5)
77 registry->release(); // step 6)
78\endcode
79
80A scene is typically deserialized using the following steps:
81
82 -# load a serialized collection into memory
83 -# create a serialization registry
84 -# create a collection by passing the serialized memory block
85 -# add collected objects to scene
86 -# release collection
87 -# release serialization registry
88
89For example the code may look like this:
90
91\code
92 PxPhysics* physics; // The physics
93 PxScene* scene; // The physics scene
94 void* memory128; // a 128-byte aligned buffer previously loaded from disk by the user - step 1)
95
96 PxSerializationRegistry* registry = PxSerialization::createSerializationRegistry(*physics); // step 2)
97 PxCollection* collection = PxSerialization::createCollectionFromBinary(memory128, *registry); // step 3)
98 scene->addCollection(*collection); // step 4)
99 collection->release(); // step 5)
100 registry->release(); // step 6)
101\endcode
102
103@see PxBase, PxCreateCollection()
104*/
105class PxCollection
106{
107public:
108
109 /**
110 \brief Adds a PxBase object to the collection.
111
112 Adds a PxBase object to the collection. Optionally a PxSerialObjectId can be provided
113 in order to resolve dependencies between collections. A PxSerialObjectId value of PX_SERIAL_OBJECT_ID_INVALID
114 means the object remains without id. Objects can be added regardless of other objects they require. If the object
115 is already in the collection, the ID will be set if it was PX_SERIAL_OBJECT_ID_INVALID previously, otherwise the
116 operation fails.
117
118
119 \param[in] object Object to be added to the collection
120 \param[in] id Optional PxSerialObjectId id
121 */
122 virtual void add(PxBase& object, PxSerialObjectId id = PX_SERIAL_OBJECT_ID_INVALID) = 0;
123
124 /**
125 \brief Removes a PxBase member object from the collection.
126
127 Object needs to be contained by the collection.
128
129 \param[in] object PxBase object to be removed
130 */
131 virtual void remove(PxBase& object) = 0;
132
133 /**
134 \brief Returns whether the collection contains a certain PxBase object.
135
136 \param[in] object PxBase object
137 \return Whether object is contained.
138 */
139 virtual bool contains(PxBase& object) const = 0;
140
141 /**
142 \brief Adds an id to a member PxBase object.
143
144 If the object is already associated with an id within the collection, the id is replaced.
145 May only be called for objects that are members of the collection. The id needs to be unique
146 within the collection.
147
148 \param[in] object Member PxBase object
149 \param[in] id PxSerialObjectId id to be given to the object
150 */
151 virtual void addId(PxBase& object, PxSerialObjectId id) = 0;
152
153 /**
154 \brief Removes id from a contained PxBase object.
155
156 May only be called for ids that are associated with an object in the collection.
157
158 \param[in] id PxSerialObjectId value
159 */
160 virtual void removeId(PxSerialObjectId id) = 0;
161
162 /**
163 \brief Adds all PxBase objects and their ids of collection to this collection.
164
165 PxBase objects already in this collection are ignored. Object ids need to be conflict
166 free, i.e. the same object may not have two different ids within the two collections.
167
168 \param[in] collection Collection to be added
169 */
170 virtual void add(PxCollection& collection) = 0;
171
172 /**
173 \brief Removes all PxBase objects of collection from this collection.
174
175 PxBase objects not present in this collection are ignored. Ids of objects
176 which are removed are also removed.
177
178 \param[in] collection Collection to be removed
179 */
180 virtual void remove(PxCollection& collection) = 0;
181
182 /**
183 \brief Gets number of PxBase objects in this collection.
184
185 \return Number of objects in this collection
186 */
187 virtual PxU32 getNbObjects() const = 0;
188
189 /**
190 \brief Gets the PxBase object of this collection given its index.
191
192 \param[in] index PxBase index in [0, getNbObjects())
193 \return PxBase object at index index
194 */
195 virtual PxBase& getObject(PxU32 index) const = 0;
196
197 /**
198 \brief Copies member PxBase pointers to a user specified buffer.
199
200 \param[out] userBuffer Array of PxBase pointers
201 \param[in] bufferSize Capacity of userBuffer
202 \param[in] startIndex Offset into list of member PxBase objects
203 \return number of members PxBase objects that have been written to the userBuffer
204 */
205 virtual PxU32 getObjects(PxBase** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
206
207 /**
208 \brief Looks for a PxBase object given a PxSerialObjectId value.
209
210 If there is no PxBase object in the collection with the given id, NULL is returned.
211
212 \param[in] id PxSerialObjectId value to look for
213 \return PxBase object with the given id value or NULL
214 */
215 virtual PxBase* find(PxSerialObjectId id) const = 0;
216
217 /**
218 \brief Gets number of PxSerialObjectId names in this collection.
219
220 \return Number of PxSerialObjectId names in this collection
221 */
222 virtual PxU32 getNbIds() const = 0;
223
224 /**
225 \brief Copies member PxSerialObjectId values to a user specified buffer.
226
227 \param[out] userBuffer Array of PxSerialObjectId values
228 \param[in] bufferSize Capacity of userBuffer
229 \param[in] startIndex Offset into list of member PxSerialObjectId values
230 \return number of members PxSerialObjectId values that have been written to the userBuffer
231 */
232 virtual PxU32 getIds(PxSerialObjectId* userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
233
234 /**
235 \brief Gets the PxSerialObjectId name of a PxBase object within the collection.
236
237 The PxBase object needs to be a member of the collection.
238
239 \param[in] object PxBase object to get id for
240 \return PxSerialObjectId name of the object or PX_SERIAL_OBJECT_ID_INVALID if the object is unnamed
241 */
242 virtual PxSerialObjectId getId(const PxBase& object) const = 0;
243
244 /**
245 \brief Deletes a collection object.
246
247 This function only deletes the collection object, i.e. the container class. It doesn't delete objects
248 that are part of the collection.
249
250 @see PxCreateCollection()
251 */
252
253 virtual void release() = 0;
254
255protected:
256 PxCollection() {}
257 virtual ~PxCollection() {}
258};
259
260#if !PX_DOXYGEN
261} // namespace physx
262#endif
263
264/**
265\brief Creates a collection object.
266
267Objects can only be serialized or deserialized through a collection.
268For serialization, users must add objects to the collection and serialize the collection as a whole.
269For deserialization, the system gives back a collection of deserialized objects to users.
270
271\return The new collection object.
272
273@see PxCollection, PxCollection::release()
274*/
275PX_PHYSX_COMMON_API physx::PxCollection* PX_CALL_CONV PxCreateCollection();
276
277
278/** @} */
279#endif
280

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