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 | /** |
46 | PX_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 |
47 | the 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 |
53 | namespace physx |
54 | { |
55 | #endif |
56 | |
57 | class PxBinaryConverter; |
58 | |
59 | /** |
60 | \brief Utility functions for serialization |
61 | |
62 | @see PxCollection, PxSerializationRegistry |
63 | */ |
64 | class PxSerialization |
65 | { |
66 | public: |
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 | |