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