PxSerialization Class Reference

Utility functions for serialization. More...

#include <PxSerialization.h>

Classes

struct  PxXmlMiscParameter
 Additional PxScene and PxPhysics options stored in XML serialized data. More...
 

Static Public Member Functions

static bool isSerializable (PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *externalReferences=NULL)
 Returns whether the collection is serializable with the externalReferences collection. More...
 
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. More...
 
static void createSerialObjectIds (PxCollection &collection, const PxSerialObjectId base)
 Creates PxSerialObjectId values for unnamed objects in a collection. More...
 
static PxCollectioncreateCollectionFromXml (PxInputData &inputData, PxCooking &cooking, PxSerializationRegistry &sr, const PxCollection *externalRefs=NULL, PxStringTable *stringTable=NULL, PxXmlMiscParameter *outArgs=NULL)
 Creates a PxCollection from XML data. More...
 
static PxCollectioncreateCollectionFromBinary (void *memBlock, PxSerializationRegistry &sr, const PxCollection *externalRefs=NULL)
 Deserializes a PxCollection from memory. More...
 
static bool serializeCollectionToXml (PxOutputStream &outputStream, PxCollection &collection, PxSerializationRegistry &sr, PxCooking *cooking=NULL, const PxCollection *externalRefs=NULL, PxXmlMiscParameter *inArgs=NULL)
 Serializes a physics collection to an XML output stream. More...
 
static bool serializeCollectionToBinary (PxOutputStream &outputStream, PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *externalRefs=NULL, bool exportNames=false)
 Serializes a collection to a binary stream. More...
 
static bool serializeCollectionToBinaryDeterministic (PxOutputStream &outputStream, PxCollection &collection, PxSerializationRegistry &sr, const PxCollection *externalRefs=NULL, bool exportNames=false)
 Serializes a collection to a binary stream. More...
 
static void dumpBinaryMetaData (PxOutputStream &outputStream, PxSerializationRegistry &sr)
 Dumps the binary meta-data to a stream. More...
 
static PxBinaryConvertercreateBinaryConverter ()
 Creates binary converter for re-targeting binary-serialized data. More...
 
static PxSerializationRegistrycreateSerializationRegistry (PxPhysics &physics)
 Creates an application managed registry for serialization. More...
 

Detailed Description

Utility functions for serialization.

See also
PxCollection, PxSerializationRegistry

Member Function Documentation

◆ complete()

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

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.

Parameters
[in,out]collectionCollection which is completed
[in]srPxSerializationRegistry instance with information about registered classes.
[in]exceptForOptional exemption collection
[in]followJointsSpecifies whether joints should be added for jointed actors
See also
PxCollection, PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml, PxSerializationRegistry

◆ createBinaryConverter()

static PxBinaryConverter* PxSerialization::createBinaryConverter ( )
static

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

Returns
Binary converter instance.

◆ createCollectionFromBinary()

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

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.

Parameters
[in]memBlockPointer to memory block containing the serialized collection
[in]srPxSerializationRegistry instance with information about registered classes.
[in]externalRefsCollection to resolve external dependencies
See also
PxCollection, PxSerialization::complete, PxSerialization::serializeCollectionToBinary, PxSerializationRegistry, PX_BINARY_SERIAL_VERSION

◆ createCollectionFromXml()

static PxCollection* PxSerialization::createCollectionFromXml ( PxInputData inputData,
PxCooking cooking,
PxSerializationRegistry sr,
const PxCollection externalRefs = NULL,
PxStringTable stringTable = NULL,
PxXmlMiscParameter outArgs = NULL 
)
static

Creates a PxCollection from XML data.

Parameters
inputDataThe input data containing the XML collection.
cookingPxCooking instance used for sdk object instantiation.
srPxSerializationRegistry instance with information about registered classes.
externalRefsPxCollection used to resolve external references.
stringTablePxStringTable instance used for storing object names.
outArgsOptional parameters of physics and scene deserialized from XML. See PxSerialization::PxXmlMiscParameter
Returns
a pointer to a PxCollection if successful or NULL if it failed.
See also
PxCollection, PxSerializationRegistry, PxInputData, PxStringTable, PxCooking, PxSerialization::PxXmlMiscParameter

◆ createSerializationRegistry()

static PxSerializationRegistry* PxSerialization::createSerializationRegistry ( PxPhysics physics)
static

Creates an application managed registry for serialization.

Parameters
[in]physicsPhysics SDK to generate create serialization registry
Returns
PxSerializationRegistry instance.
See also
PxSerializationRegistry

◆ createSerialObjectIds()

static void PxSerialization::createSerialObjectIds ( PxCollection collection,
const PxSerialObjectId  base 
)
static

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.

Parameters
[in,out]collectionCollection for which names are created
[in]baseStart address for PxSerialObjectId names
See also
PxCollection

◆ dumpBinaryMetaData()

static void PxSerialization::dumpBinaryMetaData ( PxOutputStream outputStream,
PxSerializationRegistry sr 
)
static

Dumps the binary meta-data to a stream.

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).

Parameters
[out]outputStreamStream to write meta data to
[in]srPxSerializationRegistry instance with information about registered classes used for conversion.
See also
PxOutputStream, PxSerializationRegistry

◆ isSerializable()

static bool PxSerialization::isSerializable ( PxCollection collection,
PxSerializationRegistry sr,
const PxCollection externalReferences = NULL 
)
static

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)
Parameters
[in]collectionCollection to be checked
[in]srPxSerializationRegistry instance with information about registered classes.
[in]externalReferencesthe external References collection
Returns
Whether the collection is serializable
See also
PxSerialization::complete, PxSerialization::serializeCollectionToBinary, PxSerialization::serializeCollectionToXml, PxSerializationRegistry

◆ serializeCollectionToBinary()

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

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.

Note
Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.
Parameters
[out]outputStreaminto which the collection is serialized
[in]collectionCollection to be serialized
[in]srPxSerializationRegistry instance with information about registered classes.
[in]externalRefsCollection used to resolve external dependencies
[in]exportNamesSpecifies whether object names are serialized
Returns
Whether serialization was successful
See also
PxCollection, PxOutputStream, PxSerialization::complete, PxSerialization::createCollectionFromBinary, PxSerializationRegistry

◆ serializeCollectionToBinaryDeterministic()

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

Serializes a collection to a binary stream.

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

See also
PxSerialization::serializeCollectionToBinary, PxSerialization::dumpBinaryMetaData, PxBinaryConverter

◆ serializeCollectionToXml()

static bool PxSerialization::serializeCollectionToXml ( PxOutputStream outputStream,
PxCollection collection,
PxSerializationRegistry sr,
PxCooking cooking = NULL,
const PxCollection externalRefs = NULL,
PxXmlMiscParameter inArgs = NULL 
)
static

Serializes a physics collection to an XML output stream.

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.
Note
Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.
Parameters
outputStreamStream to save collection to.
collectionPxCollection instance which is serialized. The collection needs to be complete with respect to the externalRefs collection.
srPxSerializationRegistry instance with information about registered classes.
cookingOptional pointer to cooking instance. If provided, cooked mesh data is cached for fast loading.
externalRefsCollection containing external references.
inArgsOptional parameters of physics and scene serialized to XML along with the collection. See PxSerialization::PxXmlMiscParameter
Returns
true if the collection is successfully serialized.
See also
PxCollection, PxOutputStream, PxSerializationRegistry, PxCooking, PxSerialization::PxXmlMiscParameter

The documentation for this class was generated from the following file: