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_SERIALIZATION_H
32#define PX_SERIALIZATION_H
33/** \addtogroup extensions
34 @{
35*/
36
37#include "PxPhysXConfig.h"
38#include "common/PxBase.h"
39#include "cooking/PxCooking.h"
40#include "foundation/PxIO.h"
41#include "common/PxTolerancesScale.h"
42#include "common/PxTypeInfo.h"
43#include "common/PxStringTable.h"
44
45/**
46PX_BINARY_SERIAL_VERSION is used to version the PhysX binary data and meta data. The global unique identifier of the PhysX SDK needs to match
47the one in the data and meta data, otherwise they are considered incompatible. A 32 character wide GUID can be generated with https://www.guidgenerator.com/ for example.
48*/
49#define PX_BINARY_SERIAL_VERSION "77E92B17A4084033A0FDB51332D5A6BB"
50
51
52#if !PX_DOXYGEN
53namespace physx
54{
55#endif
56
57 class PxBinaryConverter;
58
59/**
60\brief Utility functions for serialization
61
62@see PxCollection, PxSerializationRegistry
63*/
64class PxSerialization
65{
66public:
67 /**
68 \brief Additional PxScene and PxPhysics options stored in XML serialized data.
69
70 The PxXmlMiscParameter parameter can be serialized and deserialized along with PxCollection instances (XML only).
71 This is for application use only and has no impact on how objects are serialized or deserialized.
72 @see PxSerialization::createCollectionFromXml, PxSerialization::serializeCollectionToXml
73 */
74 struct PxXmlMiscParameter
75 {
76 /**
77 \brief Up vector for the scene reference coordinate system.
78 */
79 PxVec3 upVector;
80
81 /**
82 \brief Tolerances scale to be used for the scene.
83 */
84 PxTolerancesScale scale;
85
86 PxXmlMiscParameter() : upVector(0) {}
87 PxXmlMiscParameter(PxVec3& inUpVector, PxTolerancesScale inScale) : upVector(inUpVector), scale(inScale) {}
88 };
89
90 /**
91 \brief Returns whether the collection is serializable with the externalReferences collection.
92
93 Some definitions to explain whether a collection can be serialized or not:
94
95 For definitions of <b>requires</b> and <b>complete</b> see #PxSerialization::complete
96
97 A serializable object is <b>subordinate</b> if it cannot be serialized on its own
98 The following objects are subordinate:
99 - articulation links
100 - articulation joints
101 - joints
102
103 A collection C can be serialized with external references collection D iff
104 - C is complete relative to D (no dangling references)
105 - Every object in D required by an object in C has a valid ID (no unnamed references)
106 - Every subordinate object in C is required by another object in C (no orphans)
107
108 \param[in] collection Collection to be checked
109 \param[in] sr PxSerializationRegistry instance with information about registered classes.
110 \param[in] externalReferences the external References collection
111 \return Whether the collection is serializable
112 @see PxSerialization::complete, PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml, PxSerializationRegistry
113 */
114 static bool isSerializable(PxCollection& collection, PxSerializationRegistry& sr, const PxCollection* externalReferences = NULL);
115
116 /**
117 \brief Adds to a collection all objects such that it can be successfully serialized.
118
119 A collection C is complete relative to an other collection D if every object required by C is either in C or D.
120 This function adds objects to a collection, such that it becomes complete with respect to the exceptFor collection.
121 Completeness is needed for serialization. See #PxSerialization::serializeCollectionToBinary,
122 #PxSerialization::serializeCollectionToXml.
123
124 Sdk objects require other sdk object according to the following rules:
125 - joints require their actors and constraint
126 - rigid actors require their shapes
127 - shapes require their material(s) and mesh (triangle mesh, convex mesh or height field), if any
128 - articulations require their links and joints
129 - aggregates require their actors
130
131 If followJoints is specified another rule is added:
132 - actors require their joints
133
134 Specifying followJoints will make whole jointed actor chains being added to the collection. Following chains
135 is interrupted whenever a object in exceptFor is encountered.
136
137 \param[in,out] collection Collection which is completed
138 \param[in] sr PxSerializationRegistry instance with information about registered classes.
139 \param[in] exceptFor Optional exemption collection
140 \param[in] followJoints Specifies whether joints should be added for jointed actors
141 @see PxCollection, PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml, PxSerializationRegistry
142 */
143 static void complete(PxCollection& collection, PxSerializationRegistry& sr, const PxCollection* exceptFor = NULL, bool followJoints = false);
144
145 /**
146 \brief Creates PxSerialObjectId values for unnamed objects in a collection.
147
148 Creates PxSerialObjectId names for unnamed objects in a collection starting at a base value and incrementing,
149 skipping values that are already assigned to objects in the collection.
150
151 \param[in,out] collection Collection for which names are created
152 \param[in] base Start address for PxSerialObjectId names
153 @see PxCollection
154 */
155 static void createSerialObjectIds(PxCollection& collection, const PxSerialObjectId base);
156
157 /**
158 \brief Creates a PxCollection from XML data.
159
160 \param inputData The input data containing the XML collection.
161 \param cooking PxCooking instance used for sdk object instantiation.
162 \param sr PxSerializationRegistry instance with information about registered classes.
163 \param externalRefs PxCollection used to resolve external references.
164 \param stringTable PxStringTable instance used for storing object names.
165 \param outArgs Optional parameters of physics and scene deserialized from XML. See #PxSerialization::PxXmlMiscParameter
166 \return a pointer to a PxCollection if successful or NULL if it failed.
167
168 @see PxCollection, PxSerializationRegistry, PxInputData, PxStringTable, PxCooking, PxSerialization::PxXmlMiscParameter
169 */
170 static PxCollection* createCollectionFromXml(PxInputData& inputData, PxCooking& cooking, PxSerializationRegistry& sr, const PxCollection* externalRefs = NULL, PxStringTable* stringTable = NULL, PxXmlMiscParameter* outArgs = NULL);
171
172 /**
173 \brief Deserializes a PxCollection from memory.
174
175 Creates a collection from memory. If the collection has external dependencies another collection
176 can be provided to resolve these.
177
178 The memory block provided has to be 128 bytes aligned and contain a contiguous serialized collection as written
179 by PxSerialization::serializeCollectionToBinary. The contained binary data needs to be compatible with the current binary format version
180 which is defined by "PX_PHYSICS_VERSION_MAJOR.PX_PHYSICS_VERSION_MINOR.PX_PHYSICS_VERSION_BUGFIX-PX_BINARY_SERIAL_VERSION".
181 For a list of compatible sdk releases refer to the documentation of PX_BINARY_SERIAL_VERSION.
182
183 \param[in] memBlock Pointer to memory block containing the serialized collection
184 \param[in] sr PxSerializationRegistry instance with information about registered classes.
185 \param[in] externalRefs Collection to resolve external dependencies
186
187 @see PxCollection, PxSerialization::complete, PxSerialization::serializeCollectionToBinary, PxSerializationRegistry, PX_BINARY_SERIAL_VERSION
188 */
189 static PxCollection* createCollectionFromBinary(void* memBlock, PxSerializationRegistry& sr, const PxCollection* externalRefs = NULL);
190
191 /**
192 \brief Serializes a physics collection to an XML output stream.
193
194 The collection to be serialized needs to be complete @see PxSerialization.complete.
195 Optionally the XML may contain meshes in binary cooked format for fast loading. It does this when providing a valid non-null PxCooking pointer.
196
197 \note Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.
198
199 \param outputStream Stream to save collection to.
200 \param collection PxCollection instance which is serialized. The collection needs to be complete with respect to the externalRefs collection.
201 \param sr PxSerializationRegistry instance with information about registered classes.
202 \param cooking Optional pointer to cooking instance. If provided, cooked mesh data is cached for fast loading.
203 \param externalRefs Collection containing external references.
204 \param inArgs Optional parameters of physics and scene serialized to XML along with the collection. See #PxSerialization::PxXmlMiscParameter
205 \return true if the collection is successfully serialized.
206
207 @see PxCollection, PxOutputStream, PxSerializationRegistry, PxCooking, PxSerialization::PxXmlMiscParameter
208 */
209 static bool serializeCollectionToXml(PxOutputStream& outputStream, PxCollection& collection, PxSerializationRegistry& sr, PxCooking* cooking = NULL, const PxCollection* externalRefs = NULL, PxXmlMiscParameter* inArgs = NULL);
210
211 /**
212 \brief Serializes a collection to a binary stream.
213
214 Serializes a collection to a stream. In order to resolve external dependencies the externalReferences collection has to be provided.
215 Optionally names of objects that where set for example with #PxActor::setName are serialized along with the objects.
216
217 The collection can be successfully serialized if isSerializable(collection) returns true. See #isSerializable.
218
219 The implementation of the output stream needs to fulfill the requirements on the memory block input taken by
220 PxSerialization::createCollectionFromBinary.
221
222 \note Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.
223
224 \param[out] outputStream into which the collection is serialized
225 \param[in] collection Collection to be serialized
226 \param[in] sr PxSerializationRegistry instance with information about registered classes.
227 \param[in] externalRefs Collection used to resolve external dependencies
228 \param[in] exportNames Specifies whether object names are serialized
229 \return Whether serialization was successful
230
231 @see PxCollection, PxOutputStream, PxSerialization::complete, PxSerialization::createCollectionFromBinary, PxSerializationRegistry
232 */
233 static bool serializeCollectionToBinary(PxOutputStream& outputStream, PxCollection& collection, PxSerializationRegistry& sr, const PxCollection* externalRefs = NULL, bool exportNames = false );
234
235 /**
236 \brief Serializes a collection to a binary stream.
237
238 Convenience function that serializes a collection to a stream while rebasing memory addresses and handles
239 to achieve a deterministic output, independent of the PhysX runtime environment the objects have been created in.
240
241 The same functionality can be achieved by manually
242 - creating a binary data stream with PxSerialization::serializeCollectionToBinary
243 - producing the binary meta data of the current runtime platform with PxSerialization::dumpBinaryMetaData
244 - converting the binary data stream with the PxBinaryConverter, using the binary meta for both source and destination
245
246 @see PxSerialization::serializeCollectionToBinary, PxSerialization::dumpBinaryMetaData, PxBinaryConverter
247 */
248 static bool serializeCollectionToBinaryDeterministic(PxOutputStream& outputStream, PxCollection& collection, PxSerializationRegistry& sr, const PxCollection* externalRefs = NULL, bool exportNames = false);
249
250 /**
251 \brief Dumps the binary meta-data to a stream.
252
253 A meta-data file contains information about the SDK's internal classes and about custom user types ready
254 for serialization. Such a file is needed to convert binary-serialized data from one platform to another (re-targeting).
255 The converter needs meta-data files for the source and target platforms to perform conversions.
256
257 Custom user types can be supported with PxSerializationRegistry::registerBinaryMetaDataCallback (see the guide for more information).
258
259 \param[out] outputStream Stream to write meta data to
260 \param[in] sr PxSerializationRegistry instance with information about registered classes used for conversion.
261
262 @see PxOutputStream, PxSerializationRegistry
263 */
264 static void dumpBinaryMetaData(PxOutputStream& outputStream, PxSerializationRegistry& sr);
265
266 /**
267 \brief Creates binary converter for re-targeting binary-serialized data.
268
269 \return Binary converter instance.
270 */
271 static PxBinaryConverter* createBinaryConverter();
272
273 /**
274 \brief Creates an application managed registry for serialization.
275
276 \param[in] physics Physics SDK to generate create serialization registry
277
278 \return PxSerializationRegistry instance.
279
280 @see PxSerializationRegistry
281 */
282 static PxSerializationRegistry* createSerializationRegistry(PxPhysics& physics);
283};
284
285#if !PX_DOXYGEN
286} // namespace physx
287#endif
288
289/** @} */
290#endif
291

source code of qtquick3dphysics/src/3rdparty/PhysX/include/extensions/PxSerialization.h