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