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
41namespace physx
42{
43#endif
44
45typedef PxU16 PxType;
46class PxBase;
47class PxSerializationContext;
48class PxRepXSerializer;
49class PxSerializer;
50class 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
62typedef 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*/
81class PxProcessPxBaseCallback
82{
83public:
84 virtual ~PxProcessPxBaseCallback() {}
85 virtual void process(PxBase&) = 0;
86};
87
88
89/**
90\brief Binary serialization context class.
91
92This class is used to register reference values and write object
93and object extra data during serialization.
94It is mainly used by the serialization framework. Except for custom
95serializable types, users should not have to worry about it.
96
97@see PxDeserializationContext
98*/
99class PxSerializationContext
100{
101public:
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
158protected:
159
160 PxSerializationContext() {}
161 virtual ~PxSerializationContext() {}
162};
163
164
165/**
166\brief Binary deserialization context class.
167
168This class is used to resolve references and access extra data during deserialization.
169It is mainly used by the serialization framework. Except for custom
170serializable types, users should not have to worry about it.
171
172@see PxSerializationContext
173*/
174class PxDeserializationContext
175{
176public:
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* readExtraData(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* readExtraData(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 alignExtraData(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
264protected:
265
266 PxDeserializationContext() {}
267 virtual ~PxDeserializationContext() {}
268
269 PxU8* mExtraDataAddress;
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*/
278typedef void (*PxBinaryMetaDataCallback)(PxOutputStream& stream);
279
280/**
281\brief Class serving as a registry for XML (RepX) and binary serializable types.
282
283In order to serialize and deserialize objects the application needs
284to maintain an instance of this class. It can be created with
285PxSerialization::createSerializationRegistry() and released with
286PxSerializationRegistry::release().
287
288@see PxSerialization::createSerializationRegistry
289*/
290class PxSerializationRegistry
291{
292public:
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
390protected:
391 virtual ~PxSerializationRegistry(){}
392};
393
394#if !PX_DOXYGEN
395} // namespace physx
396#endif
397
398/** @} */
399#endif
400

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