Serialization
Serialization is required to save a data structure to stable storage or transmit it across a network. A typical use case for serialization is to quickly re-create pre-computed shapes. However, Jolt JNI also allows serialization of body settings and entire scenes.
There are 2 serialization systems: a snapshot system for short-term use with cooked data structures, and an object-stream system for long-term use with uncooked data structures.
The main distinction between cooked and uncooked
is that cooked data structures contain Shape
objects
instead of ShapeSettings
ones.
The snapshot system
Many Jolt-JNI classes implement the saveBinaryState(StreamOut)
method:
-
BodyCreationSettings
(cooked, withShape
) -
ConstraintSettings
-
GroupFilter
-
PathConstraintPath
-
PhysicsMaterial
-
PhysicsScene
-
RagdollSettings
-
Shape
-
Skeleton
-
SoftBodyCreationSettings
-
SpringSettings
-
VehicleAntiRollBar
-
VehicleControllerSettings
-
WheelSettings
The StreamOut
argument can be either
a wrapped OfStream
(a file) or
a wrapped StringStream
(a variable-length buffer).
In some classes, saveBinaryState()
takes additional arguments.
To de-serialize snapshot data, you must know the type of the original object. You either:
-
instantiate an object of the expected type and invoke its
restoreBinaryState(StreamIn)
method or else -
invoke the static
sRestoreFromBinaryState(StreamIn)
method for the expected type.
Snapshot data is optimized for loading speed. It’s in a binary format that’s likely to change between library versions and might not be compatible between Sp- and Dp-flavored native libraries. For these reasons, snapshots shouldn’t be your primary data format.
The object-stream system
The ObjectStreamOut.sWriteObject()
method can serialize
physics objects of many types, including:
-
BodyCreationSettings
(uncooked, withShapeSettings
) -
ConstraintSettings
-
GroupFilter
-
PathConstraintPath
-
PhysicsMaterial
-
PhysicsScene
-
RagdollSettings
-
ShapeSettings
-
SoftBodyCreationSettings
-
SoftBodySharedSettings
-
VehicleControllerSettings
-
WheelSettings
Objects can be serialized in either binary or text format,
either to a file or a StringStream
(variable-length buffer).
To de-serialize object-stream data, you must know the approximate type of the original object.
-
For
RefCount
types, instantiate an empty counted reference of the expected type and pass it to theObjectStreamIn.sReadObject()
method. -
For non-
RefCount
types, instantiate an object of the expected type and pass it toObjectStreamIn.sReadObject()
.
Data stored in this way is likely to be compatible with future versions of the library (although compatibility is not guaranteed).