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_COMMON_NX_SERIAL_FRAMEWORK |
32 | #define PX_PHYSICS_COMMON_NX_SERIAL_FRAMEWORK |
33 | |
34 | /** \addtogroup common |
35 | @{ |
36 | */ |
37 | |
38 | #include "common/PxPhysXCommonConfig.h" |
39 | |
40 | #if !PX_DOXYGEN |
41 | namespace physx |
42 | { |
43 | #endif |
44 | |
45 | typedef PxU16 PxType; |
46 | class PxBase; |
47 | class PxSerializationContext; |
48 | class PxRepXSerializer; |
49 | class PxSerializer; |
50 | class PxPhysics; |
51 | |
52 | //! Default serialization alignment |
53 | #define PX_SERIAL_ALIGN 16 |
54 | |
55 | //! Serialized input data must be aligned to this value |
56 | #define PX_SERIAL_FILE_ALIGN 128 |
57 | |
58 | //! PxSerialObjectId value for objects that do not have an ID |
59 | #define PX_SERIAL_OBJECT_ID_INVALID 0 |
60 | |
61 | //! ID type for PxBase objects in a PxCollection |
62 | typedef PxU64 PxSerialObjectId; |
63 | |
64 | //! Bit to mark pointer type references, @see PxDeserializationContext |
65 | #define PX_SERIAL_REF_KIND_PTR_TYPE_BIT (1u<<31) |
66 | |
67 | //! Reference kind value for PxBase objects |
68 | #define PX_SERIAL_REF_KIND_PXBASE (0 | PX_SERIAL_REF_KIND_PTR_TYPE_BIT) |
69 | |
70 | //! Reference kind value for material indices |
71 | #define PX_SERIAL_REF_KIND_MATERIAL_IDX (1) |
72 | |
73 | //! Used to fix multi-byte characters warning from gcc for situations like: PxU32 foo = 'CCTS'; |
74 | #define PX_MAKE_FOURCC(a, b, c, d) ( (a) | ((b)<<8) | ((c)<<16) | ((d)<<24) ) |
75 | |
76 | /** |
77 | \brief Callback class used to process PxBase objects. |
78 | |
79 | @see PxSerializer::requires |
80 | */ |
81 | class PxProcessPxBaseCallback |
82 | { |
83 | public: |
84 | virtual ~PxProcessPxBaseCallback() {} |
85 | virtual void process(PxBase&) = 0; |
86 | }; |
87 | |
88 | |
89 | /** |
90 | \brief Binary serialization context class. |
91 | |
92 | This class is used to register reference values and write object |
93 | and object extra data during serialization. |
94 | It is mainly used by the serialization framework. Except for custom |
95 | serializable types, users should not have to worry about it. |
96 | |
97 | @see PxDeserializationContext |
98 | */ |
99 | class PxSerializationContext |
100 | { |
101 | public: |
102 | |
103 | /** |
104 | \brief Registers a reference value corresponding to a PxBase object. |
105 | |
106 | This method is assumed to be called in the implementation of PxSerializer::registerReferences for serialized |
107 | references that need to be resolved on deserialization. |
108 | |
109 | A reference needs to be associated with exactly one PxBase object in either the collection or the |
110 | external references collection. |
111 | |
112 | Different kinds of references are supported and need to be specified. In the most common case |
113 | (PX_SERIAL_REF_KIND_PXBASE) the PxBase object matches the reference value (which is the pointer |
114 | to the PxBase object). Integer references maybe registered as well (used for internal material |
115 | indices with PX_SERIAL_REF_KIND_MATERIAL_IDX). Other kinds could be added with the restriction that |
116 | for pointer types the kind value needs to be marked with the PX_SERIAL_REF_KIND_PTR_TYPE_BIT. |
117 | |
118 | \param[in] base PxBase object associated with the reference |
119 | \param[in] kind What kind of reference this is (PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX or custom kind) |
120 | \param[in] reference Value of reference |
121 | |
122 | @see PxDeserializationContext::resolveReference, PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX, PxSerializer::registerReferences |
123 | */ |
124 | virtual void registerReference(PxBase& base, PxU32 kind, size_t reference) = 0; |
125 | |
126 | /** |
127 | \brief Returns the collection that is being serialized. |
128 | */ |
129 | virtual const PxCollection& getCollection() const = 0; |
130 | |
131 | /** |
132 | \brief Serializes object data and object extra data. |
133 | |
134 | This function is assumed to be called within the implementation of PxSerializer::exportData and PxSerializer::exportExtraData. |
135 | |
136 | @see PxSerializer::exportData, PxSerializer::exportExtraData, PxSerializer::createObject, PxDeserializationContext::readExtraData |
137 | */ |
138 | virtual void writeData(const void* data, PxU32 size) = 0; |
139 | |
140 | /** |
141 | \brief Aligns the serialized data. |
142 | |
143 | This function is assumed to be called within the implementation of PxSerializer::exportData and PxSerializer::exportExtraData. |
144 | |
145 | @see PxSerializer::exportData, PxSerializer::exportExtraData, PxDeserializationContext::alignExtraData |
146 | */ |
147 | virtual void alignData(PxU32 alignment = PX_SERIAL_ALIGN) = 0; |
148 | |
149 | /** |
150 | \brief Helper function to write a name to the extraData if serialization is configured to save names. |
151 | |
152 | This function is assumed to be called within the implementation of PxSerializer::exportExtraData. |
153 | |
154 | @see PxSerialization::serializeCollectionToBinary, PxDeserializationContext::readName |
155 | */ |
156 | virtual void writeName(const char* name) = 0; |
157 | |
158 | protected: |
159 | |
160 | PxSerializationContext() {} |
161 | virtual ~PxSerializationContext() {} |
162 | }; |
163 | |
164 | |
165 | /** |
166 | \brief Binary deserialization context class. |
167 | |
168 | This class is used to resolve references and access extra data during deserialization. |
169 | It is mainly used by the serialization framework. Except for custom |
170 | serializable types, users should not have to worry about it. |
171 | |
172 | @see PxSerializationContext |
173 | */ |
174 | class PxDeserializationContext |
175 | { |
176 | public: |
177 | |
178 | /** |
179 | \brief Retrieves a pointer to a deserialized PxBase object given a corresponding deserialized reference value |
180 | |
181 | This method is assumed to be called in the implementation of PxSerializer::createObject in order |
182 | to update reference values on deserialization. |
183 | |
184 | To update a PxBase reference the corresponding deserialized pointer value needs to be provided in order to retrieve |
185 | the location of the corresponding deserialized PxBase object. (PxDeserializationContext::translatePxBase simplifies |
186 | this common case). |
187 | |
188 | For other kinds of references the reverence values need to be updated by deduction given the corresponding PxBase instance. |
189 | |
190 | \param[in] kind What kind of reference this is (PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX or custom kind) |
191 | \param[in] reference Deserialized reference value |
192 | \return PxBase object associated with the reference value |
193 | |
194 | @see PxSerializationContext::registerReference, PX_SERIAL_REF_KIND_PXBASE, PX_SERIAL_REF_KIND_MATERIAL_IDX, translatePxBase |
195 | */ |
196 | virtual PxBase* resolveReference(PxU32 kind, size_t reference) const = 0; |
197 | |
198 | /** |
199 | \brief Helper function to update PxBase pointer on deserialization |
200 | |
201 | @see resolveReference, PX_SERIAL_REF_KIND_PXBASE |
202 | */ |
203 | template<typename T> |
204 | void translatePxBase(T*& base) { if (base) { base = static_cast<T*>(resolveReference(PX_SERIAL_REF_KIND_PXBASE, reference: size_t(base))); } } |
205 | |
206 | /** |
207 | \brief Helper function to read a name from the extra data during deserialization. |
208 | |
209 | This function is assumed to be called within the implementation of PxSerializer::createObject. |
210 | |
211 | @see PxSerializationContext::writeName |
212 | */ |
213 | PX_INLINE void readName(const char*& name) |
214 | { |
215 | PxU32 len = *reinterpret_cast<PxU32*>(mExtraDataAddress); |
216 | mExtraDataAddress += sizeof(len); |
217 | name = len ? reinterpret_cast<const char*>(mExtraDataAddress) : NULL; |
218 | mExtraDataAddress += len; |
219 | } |
220 | |
221 | /** |
222 | \brief Function to read extra data during deserialization. |
223 | |
224 | This function is assumed to be called within the implementation of PxSerializer::createObject. |
225 | |
226 | @see PxSerializationContext::writeData, PxSerializer::createObject |
227 | */ |
228 | template<typename T> |
229 | PX_INLINE T* (PxU32 count=1) |
230 | { |
231 | T* data = reinterpret_cast<T*>(mExtraDataAddress); |
232 | mExtraDataAddress += sizeof(T)*count; |
233 | return data; |
234 | } |
235 | |
236 | /** |
237 | \brief Function to read extra data during deserialization optionally aligning the extra data stream before reading. |
238 | |
239 | This function is assumed to be called within the implementation of PxSerializer::createObject. |
240 | |
241 | @see PxSerializationContext::writeData, PxDeserializationContext::alignExtraData, PxSerializer::createObject |
242 | */ |
243 | template<typename T, PxU32 alignment> |
244 | PX_INLINE T* (PxU32 count=1) |
245 | { |
246 | alignExtraData(alignment); |
247 | return readExtraData<T>(count); |
248 | } |
249 | |
250 | /** |
251 | \brief Function to align the extra data stream to a power of 2 alignment |
252 | |
253 | This function is assumed to be called within the implementation of PxSerializer::createObject. |
254 | |
255 | @see PxSerializationContext::alignData, PxSerializer::createObject |
256 | */ |
257 | PX_INLINE void (PxU32 alignment = PX_SERIAL_ALIGN) |
258 | { |
259 | size_t addr = reinterpret_cast<size_t>(mExtraDataAddress); |
260 | addr = (addr+alignment-1)&~size_t(alignment-1); |
261 | mExtraDataAddress = reinterpret_cast<PxU8*>(addr); |
262 | } |
263 | |
264 | protected: |
265 | |
266 | PxDeserializationContext() {} |
267 | virtual ~PxDeserializationContext() {} |
268 | |
269 | PxU8* ; |
270 | }; |
271 | |
272 | /** |
273 | \brief Callback type for exporting binary meta data for a serializable type. |
274 | @see PxSerializationRegistry::registerBinaryMetaDataCallback |
275 | |
276 | \param stream Stream to store binary meta data. |
277 | */ |
278 | typedef void (*PxBinaryMetaDataCallback)(PxOutputStream& stream); |
279 | |
280 | /** |
281 | \brief Class serving as a registry for XML (RepX) and binary serializable types. |
282 | |
283 | In order to serialize and deserialize objects the application needs |
284 | to maintain an instance of this class. It can be created with |
285 | PxSerialization::createSerializationRegistry() and released with |
286 | PxSerializationRegistry::release(). |
287 | |
288 | @see PxSerialization::createSerializationRegistry |
289 | */ |
290 | class PxSerializationRegistry |
291 | { |
292 | public: |
293 | /************************************************************************************************/ |
294 | |
295 | /** @name Binary Serialization Functionality |
296 | */ |
297 | //@{ |
298 | |
299 | /** |
300 | \brief Register a serializer for a concrete type |
301 | |
302 | \param type PxConcreteType corresponding to the serializer |
303 | \param serializer The PxSerializer to be registered |
304 | |
305 | @see PxConcreteType, PxSerializer, PxSerializationRegistry::unregisterSerializer |
306 | */ |
307 | virtual void registerSerializer(PxType type, PxSerializer& serializer) = 0; |
308 | |
309 | /** |
310 | \brief Unregister a serializer for a concrete type, and retrieves the corresponding serializer object. |
311 | |
312 | \param type PxConcreteType for which the serializer should be unregistered |
313 | \return Unregistered serializer corresponding to type, NULL for types for which no serializer has been registered. |
314 | |
315 | @see PxConcreteType, PxSerializationRegistry::registerSerializer, PxSerializationRegistry::release |
316 | */ |
317 | virtual PxSerializer* unregisterSerializer(PxType type) = 0; |
318 | |
319 | /** |
320 | \brief Register binary meta data callback |
321 | |
322 | The callback is executed when calling PxSerialization::dumpBinaryMetaData. |
323 | |
324 | \param callback PxBinaryMetaDataCallback to be registered. |
325 | |
326 | @see PxBinaryMetaDataCallback, PxSerialization::dumpBinaryMetaData |
327 | */ |
328 | virtual void registerBinaryMetaDataCallback(PxBinaryMetaDataCallback callback) = 0; |
329 | |
330 | /** |
331 | \brief Returns PxSerializer corresponding to type |
332 | |
333 | \param type PxConcreteType of the serializer requested. |
334 | \return Registered PxSerializer object corresponding to type |
335 | |
336 | @see PxConcreteType |
337 | */ |
338 | virtual const PxSerializer* getSerializer(PxType type) const = 0; |
339 | |
340 | //@} |
341 | /************************************************************************************************/ |
342 | |
343 | /** @name RepX (XML) Serialization Functionality |
344 | */ |
345 | //@{ |
346 | |
347 | /** |
348 | \brief Register a RepX serializer for a concrete type |
349 | |
350 | \param type PxConcreteType corresponding to the RepX serializer |
351 | \param serializer The PxRepXSerializer to be registered |
352 | |
353 | @see PxConcreteType, PxRepXSerializer |
354 | */ |
355 | virtual void registerRepXSerializer(PxType type, PxRepXSerializer& serializer) = 0; |
356 | |
357 | /** |
358 | \brief Unregister a RepX serializer for a concrete type, and retrieves the corresponding serializer object. |
359 | |
360 | \param type PxConcreteType for which the RepX serializer should be unregistered |
361 | \return Unregistered PxRepxSerializer corresponding to type, NULL for types for which no RepX serializer has been registered. |
362 | |
363 | @see PxConcreteType, PxSerializationRegistry::registerRepXSerializer, PxSerializationRegistry::release |
364 | */ |
365 | virtual PxRepXSerializer* unregisterRepXSerializer(PxType type) = 0; |
366 | |
367 | /** |
368 | \brief Returns RepX serializer given the corresponding type name |
369 | |
370 | \param typeName Name of the type |
371 | \return Registered PxRepXSerializer object corresponding to type name |
372 | |
373 | @see PxRepXSerializer, PxTypeInfo, PX_DEFINE_TYPEINFO |
374 | */ |
375 | virtual PxRepXSerializer* getRepXSerializer(const char* typeName) const = 0; |
376 | |
377 | //@} |
378 | /************************************************************************************************/ |
379 | |
380 | /** |
381 | \brief Releases PxSerializationRegistry instance. |
382 | |
383 | This unregisters all PhysX and PhysXExtension serializers. Make sure to unregister all custom type |
384 | serializers before releasing the PxSerializationRegistry. |
385 | |
386 | @see PxSerializationRegistry::unregisterSerializer, PxSerializationRegistry::unregisterRepXSerializer |
387 | */ |
388 | virtual void release() = 0; |
389 | |
390 | protected: |
391 | virtual ~PxSerializationRegistry(){} |
392 | }; |
393 | |
394 | #if !PX_DOXYGEN |
395 | } // namespace physx |
396 | #endif |
397 | |
398 | /** @} */ |
399 | #endif |
400 | |