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