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 |
41 | namespace physx |
42 | { |
43 | #endif |
44 | |
45 | class PxBase; |
46 | |
47 | /** |
48 | \brief Collection class for serialization. |
49 | |
50 | A collection is a set of PxBase objects. PxBase objects can be added to the collection |
51 | regardless of other objects they depend on. Objects may be named using PxSerialObjectId values in order |
52 | to resolve dependencies between objects of different collections. |
53 | |
54 | Serialization and deserialization only work through collections. |
55 | |
56 | A 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 | |
65 | For 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 | |
80 | A 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 | |
89 | For 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 | */ |
105 | class PxCollection |
106 | { |
107 | public: |
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 | |
255 | protected: |
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 | |
267 | Objects can only be serialized or deserialized through a collection. |
268 | For serialization, users must add objects to the collection and serialize the collection as a whole. |
269 | For 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 | */ |
275 | PX_PHYSX_COMMON_API physx::PxCollection* PX_CALL_CONV PxCreateCollection(); |
276 | |
277 | |
278 | /** @} */ |
279 | #endif |
280 | |