PxSerialization

Defined in include/extensions/PxSerialization.h

Structs

• PxXmlMiscParameter: Additional PxScene and PxPhysics options stored in XML serialized data.

class PxSerialization

Utility functions for serialization.

See also

PxCollection, PxSerializationRegistry

Public Static Functions

static bool isSerializable(PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *externalReferences = NULL)

Returns whether the collection is serializable with the externalReferences collection.

Some definitions to explain whether a collection can be serialized or not:

For definitions of requires and complete see PxSerialization::complete

A serializable object is subordinate if it cannot be serialized on its own The following objects are subordinate:

• articulation links

• articulation joints

• joints

A collection C can be serialized with external references collection D iff

• C is complete relative to D (no dangling references)

• Every object in D required by an object in C has a valid ID (no unnamed references)

• Every subordinate object in C is required by another object in C (no orphans)

See also

PxSerialization::complete, PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml, PxSerializationRegistry

Parameters

• collection – [in] Collection to be checked

• sr – [in] PxSerializationRegistry instance with information about registered classes.

• externalReferences – [in] the external References collection

Returns

Whether the collection is serializable

static void complete(PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *exceptFor = NULL, bool followJoints = false)

Adds to a collection all objects such that it can be successfully serialized.

A collection C is complete relative to an other collection D if every object required by C is either in C or D. This function adds objects to a collection, such that it becomes complete with respect to the exceptFor collection. Completeness is needed for serialization. See PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml.

Sdk objects require other sdk object according to the following rules:

• joints require their actors and constraint

• rigid actors require their shapes

• shapes require their material(s) and mesh (triangle mesh, convex mesh or height field), if any

• articulations require their links and joints

• aggregates require their actors

If followJoints is specified another rule is added:

• actors require their joints

Specifying followJoints will make whole jointed actor chains being added to the collection. Following chains is interrupted whenever a object in exceptFor is encountered.

See also

PxCollection, PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml, PxSerializationRegistry

Parameters

• collection – [inout] Collection which is completed

• sr – [in] PxSerializationRegistry instance with information about registered classes.

• exceptFor – [in] Optional exemption collection

• followJoints – [in] Specifies whether joints should be added for jointed actors

static void createSerialObjectIds(PxCollection &collection, const PxSerialObjectId base)

Creates PxSerialObjectId values for unnamed objects in a collection.

Creates PxSerialObjectId names for unnamed objects in a collection starting at a base value and incrementing, skipping values that are already assigned to objects in the collection.

See also

PxCollection

Parameters

• collection – [inout] Collection for which names are created

• base – [in] Start address for PxSerialObjectId names

static PxCollection *createCollectionFromXml(PxInputData &inputData, const PxCookingParams &params, PxSerializationRegistry &sr, const PxCollection *externalRefs = NULL, PxStringTable *stringTable = NULL, PxXmlMiscParameter *outArgs = NULL)

Creates a PxCollection from XML data.

Deprecated:

Xml serialization is deprecated. An alternative serialization system is provided through USD Physics.

See also

PxCollection, PxSerializationRegistry, PxInputData, PxStringTable, PxCooking, PxSerialization::PxXmlMiscParameter

Parameters

• inputData – The input data containing the XML collection.

• params – Cooking parameters used for sdk object instantiation.

• sr – PxSerializationRegistry instance with information about registered classes.

• externalRefs – PxCollection used to resolve external references.

• stringTable – PxStringTable instance used for storing object names.

• outArgs – Optional parameters of physics and scene deserialized from XML. See PxSerialization::PxXmlMiscParameter

Returns

a pointer to a PxCollection if successful or NULL if it failed.

static PxCollection *createCollectionFromBinary(void *memBlock, PxSerializationRegistry &sr, const PxCollection *externalRefs = NULL)

Deserializes a PxCollection from memory.

Creates a collection from memory. If the collection has external dependencies another collection can be provided to resolve these.

The memory block provided has to be 128 bytes aligned and contain a contiguous serialized collection as written by PxSerialization::serializeCollectionToBinary. The contained binary data needs to be compatible with the current binary format version which is defined by “PX_PHYSICS_VERSION_MAJOR.PX_PHYSICS_VERSION_MINOR.PX_PHYSICS_VERSION_BUGFIX-PX_BINARY_SERIAL_VERSION”. For a list of compatible sdk releases refer to the documentation of PX_BINARY_SERIAL_VERSION.

See also

PxCollection, PxSerialization::complete, PxSerialization::serializeCollectionToBinary, PxSerializationRegistry, PX_BINARY_SERIAL_VERSION

Parameters

• memBlock – [in] Pointer to memory block containing the serialized collection

• sr – [in] PxSerializationRegistry instance with information about registered classes.

• externalRefs – [in] Collection to resolve external dependencies

static bool serializeCollectionToXml(PxOutputStream &outputStream, PxCollection &collection, PxSerializationRegistry &sr, const PxCookingParams *params = NULL, const PxCollection *externalRefs = NULL, PxXmlMiscParameter *inArgs = NULL)

Serializes a physics collection to an XML output stream.

Deprecated:

Xml serialization is deprecated. An alternative serialization system is provided through USD Physics.

The collection to be serialized needs to be complete

See also

PxSerialization.complete. Optionally the XML may contain meshes in binary cooked format for fast loading. It does this when providing a valid non-null PxCooking pointer.

See also

PxCollection, PxOutputStream, PxSerializationRegistry, PxCooking, PxSerialization::PxXmlMiscParameter

Note

Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.

Parameters

• outputStream – Stream to save collection to.

• collection – PxCollection instance which is serialized. The collection needs to be complete with respect to the externalRefs collection.

• sr – PxSerializationRegistry instance with information about registered classes.

• params – Optional pointer to cooking params. If provided, cooked mesh data is cached for fast loading.

• externalRefs – Collection containing external references.

• inArgs – Optional parameters of physics and scene serialized to XML along with the collection. See PxSerialization::PxXmlMiscParameter

Returns

true if the collection is successfully serialized.

static bool serializeCollectionToBinary(PxOutputStream &outputStream, PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *externalRefs = NULL, bool exportNames = false)

Serializes a collection to a binary stream.

Serializes a collection to a stream. In order to resolve external dependencies the externalReferences collection has to be provided. Optionally names of objects that where set for example with PxActor::setName are serialized along with the objects.

The collection can be successfully serialized if isSerializable(collection) returns true. See isSerializable.

The implementation of the output stream needs to fulfill the requirements on the memory block input taken by PxSerialization::createCollectionFromBinary.

See also

PxCollection, PxOutputStream, PxSerialization::complete, PxSerialization::createCollectionFromBinary, PxSerializationRegistry

Note

Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.

Parameters

• outputStream – [out] into which the collection is serialized

• collection – [in] Collection to be serialized

• sr – [in] PxSerializationRegistry instance with information about registered classes.

• externalRefs – [in] Collection used to resolve external dependencies

• exportNames – [in] Specifies whether object names are serialized

Returns

Whether serialization was successful

static bool serializeCollectionToBinaryDeterministic(PxOutputStream &outputStream, PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *externalRefs = NULL, bool exportNames = false)

Serializes a collection to a binary stream.

Deprecated:

Deterministic binary serialization is deprecated. PxSerialization::serializeCollectionToBinary might become deterministic in the future.

Convenience function that serializes a collection to a stream while rebasing memory addresses and handles to achieve a deterministic output, independent of the PhysX runtime environment the objects have been created in.

The same functionality can be achieved by manually

• creating a binary data stream with PxSerialization::serializeCollectionToBinary

• producing the binary meta data of the current runtime platform with PxSerialization::dumpBinaryMetaData

• converting the binary data stream with the PxBinaryConverter, using the binary meta for both source and destination

See also

PxSerialization::serializeCollectionToBinary, PxSerialization::dumpBinaryMetaData, PxBinaryConverter

static void dumpBinaryMetaData(PxOutputStream &outputStream, PxSerializationRegistry &sr)

Dumps the binary meta-data to a stream.

Deprecated:

Binary conversion and binary meta data are deprecated.

A meta-data file contains information about the SDK’s internal classes and about custom user types ready for serialization. Such a file is needed to convert binary-serialized data from one platform to another (re-targeting). The converter needs meta-data files for the source and target platforms to perform conversions.

Custom user types can be supported with PxSerializationRegistry::registerBinaryMetaDataCallback (see the guide for more information).

See also

PxOutputStream, PxSerializationRegistry

Parameters

• outputStream – [out] Stream to write meta data to

• sr – [in] PxSerializationRegistry instance with information about registered classes used for conversion.

static PxBinaryConverter *createBinaryConverter()

Creates binary converter for re-targeting binary-serialized data.

Deprecated:

Binary conversion and binary meta data are deprecated.

Returns

Binary converter instance.

static PxSerializationRegistry *createSerializationRegistry(PxPhysics &physics)

Creates an application managed registry for serialization.

See also

PxSerializationRegistry

Parameters

physics – [in] Physics SDK to generate create serialization registry

Returns

PxSerializationRegistry instance.

struct PxXmlMiscParameter

Additional PxScene and PxPhysics options stored in XML serialized data.

Deprecated:

Xml serialization is deprecated. An alternative serialization system is provided through USD Physics.

The PxXmlMiscParameter parameter can be serialized and deserialized along with PxCollection instances (XML only). This is for application use only and has no impact on how objects are serialized or deserialized.

See also

PxSerialization::createCollectionFromXml, PxSerialization::serializeCollectionToXml

Public Functions

inline PxXmlMiscParameter()

inline PxXmlMiscParameter(PxVec3 &inUpVector, PxTolerancesScale inScale)

Public Members

PxVec3 upVector

Up vector for the scene reference coordinate system.

PxTolerancesScale scale

Tolerances scale to be used for the scene.