PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Serializer Class Reference

serialize data into memory More...

Public Member Functions

MemBlock getDataPtr ()
 get the serialized data
 
number getDataSize ()
 get the size of the serialized data
 
 serialize_1 (int val)
 serialize 1 signed byte
 
 serialize_1u (uint val)
 serialize 1 unsigned byte
 
 serialize_2 (int val)
 serialize 2 signed bytes
 
 serialize_2u (uint val)
 serialize 2 unsigned bytes
 
 serialize_3u (uint val)
 serialize 3 unsigned bytes
 
 serialize_4 (int val)
 serialize 4 signed bytes
 
 serialize_4u (uint val)
 serialize 4 unsigned bytes
 
 serialize_8 (number val)
 serialize 8 signed bytes
 
 serialize_8u (number val)
 serialize 8 unsigned bytes
 
 serialize_bool (boolean val)
 serialize a 1 bit boolean value
 
 serialize_color (Color val)
 serialize a Color
 
 serialize_d (number val)
 serialize a double precision floating point number
 
 serialize_f (number val)
 serialize a single precision floating point number
 
 serialize_mem (BinaryString mem)
 serialize a binary string
 
 serialize_mem (MemBlock mem)
 serialize a block of memory
 
 serialize_obj (ISerializable obj)
 serialize a serializable object
 
 serialize_offset (Offset val)
 serialize an Offset's (x,y) values
 
 serialize_point (Point val)
 serialize a Point's (x,y) values
 
 serialize_quad (Quad val)
 serialize a Quad's (x,y) point values
 
 serialize_rect (Rect val)
 serialize a Rect's left, top, right, bottom values
 
 serialize_ref (object obj)
 
 serialize_rotr (RotatedRect val)
 serialize a RotatedRect's data values
 
 serialize_str (string str)
 serialize a JavaScript string
 
 serialize_uint (uint val)
 serialize up to 4 unsigned bytes
 
 serialize_vector (Vector val)
 serialize a Vector's (x,y) values
 
uint sizeof_1 (int val)
 
uint sizeof_1u (uint val)
 
uint sizeof_2 (int val)
 
uint sizeof_2u (uint val)
 
uint sizeof_3u (uint val)
 
uint sizeof_4 (int val)
 
uint sizeof_4u (uint val)
 
uint sizeof_8 (int val)
 
uint sizeof_8u (uint val)
 
uint sizeof_bool (boolean val)
 get the number of bytes used to serialize the given boolean
 
uint sizeof_color (Color val)
 get the number of bytes used to serialize the given Color
 
uint sizeof_d (number val)
 
uint sizeof_f (number val)
 
uint sizeof_mem (BinaryString mem)
 
uint sizeof_mem (MemBlock mem)
 get the number of bytes used to serialize the given block of memory
 
uint sizeof_obj (ISerializable val)
 get the number of bytes used to serialize the given object, including any objects that it serializes
 
uint sizeof_offset (Offset val)
 get the number of bytes used to serialize the given Offset
 
uint sizeof_point (Point val)
 get the number of bytes used to serialize the given Point
 
uint sizeof_quad (Quad val)
 get the number of bytes used to serialize the given Quad
 
uint sizeof_rect (Rect val)
 get the number of bytes used to serialize the given Rect
 
uint sizeof_ref (object val)
 
uint sizeof_rotr (RotatedRect val)
 get the number of bytes used to serialize the given RotatedRect
 
uint sizeof_str (string val)
 get the number of bytes used to serialize the given string
 
uint sizeof_uint (uint val)
 get the number of bytes used to serialize the given unsigned integer
 
uint sizeof_vector (Vector val)
 get the number of bytes used to serialize the given Vector
 

Detailed Description

serialize data into memory

Precondition
API Stability: 3 - Stable. The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility is guaranteed.

Serializer stores complex data into memory in a way that it can be read back from a Deserializer. It can correctly store entire object hierarchies without duplication.

The data stream format is platform neutral, so it is suitable for saved game files and network messages between client and server, using NetConnection.send(ISerializable).

Serializer writes tags at key points that the deserialization process can use to be sure things haven't gotten out of sync. However, if you want your serialized data streams to be versioned, you will have to add that yourself; either on a per object/message basis or for an entire saved stream.

Method Groups

See Also
Deserializer
ISerializable
NetConnection.send(ISerializable)

Member Function Documentation

getDataPtr ( )

get the serialized data

Returns
a MemBlock object with the serialized data.
Note
This is really only useful after one or more serialize_X methods have been called to actually write data into the memory block.
See Also
getDataSize
Deserializer.setDataPtr
getDataSize ( )

get the size of the serialized data

Returns
the number of bytes of data in the serialized data. This is the same value that would be returned by calling the getDataSize() method of the MemBlock returned by getDataPtr()
Note
This is really only useful after one or more serialize_X methods have been called to actually write data into the memory block.
See Also
getDataPtr
serialize_1 ( int  val)

serialize 1 signed byte

Write a one byte value in the range of −127 to 127 into the data stream.

Warning
if the value is outside the range then only the info from the least significant byte will be written into the serialized data stream
Note
data size: 1 byte
See Also
Deserializer.deserialize_1
serialize_1u ( uint  val)

serialize 1 unsigned byte

Write a one byte value in the range of 0 to 255 into the data stream.

Warning
if the value is outside the range then only the info from the least significant byte will be written into the serialized data stream
Note
data size: 1 byte
See Also
Deserializer.deserialize_1u
serialize_2 ( int  val)

serialize 2 signed bytes

Write a two byte value in the range of −32,767 to 32,767 into the data stream.

Warning
if the value is outside the range then only the info from the least significant two bytes will be written into the serialized data stream
Note
data size: 2 bytes
See Also
Deserializer.deserialize_2
serialize_2u ( uint  val)

serialize 2 unsigned bytes

Write a two byte value in the range of 0 to 65,535 into the data stream.

Warning
if the value is outside the range then only the info from the least significant two bytes will be written into the serialized data stream
Note
data size: 2 bytes
See Also
Deserializer.deserialize_2u
serialize_3u ( uint  val)

serialize 3 unsigned bytes

Write a three byte value in the range of 0 to 16,777,216 into the data stream.

Warning
if the value is outside the range then only the info from the least significant three bytes will be written into the serialized data stream.
Note
data size: 3 bytes
Remarks
there is no serialize_3(signed int); use serialize_4 instead
See Also
Deserializer.deserialize_3u
serialize_4 ( int  val)

serialize 4 signed bytes

Write a four byte value in the range of −2,147,483,647 to 2,147,483,647 into the data stream.

Warning
if the value is outside the range then only the info from the least significant four bytes will be written into the serialized data stream.
Note
data size: 4 bytes
See Also
Deserializer.deserialize_4
serialize_4u ( uint  val)

serialize 4 unsigned bytes

Write a four byte value in the range of 0 to 4,294,967,295 into the data stream.

Warning
if the value is outside the range then only the info from the least significant four bytes will be written into the serialized data stream.
Note
data size: 4 bytes
See Also
Deserializer.deserialize_4u
serialize_8 ( number  val)

serialize 8 signed bytes

Write an eight byte value in the range of −9,223,372,036,854,775,807 to 9,223,372,036,854,775,807 into the data stream.

Warning
JavaScript doesn't directly support 64-bit Integers, so for very large values expect some precision to be lost in the conversion between JavaScript's native double and 64-bit Integer. You might want to use serialize_d() instead.
Note
data size: 8 bytes
See Also
Deserializer.deserialize_8
serialize_8u ( number  val)

serialize 8 unsigned bytes

Write an eight byte value in the range of 0 to 18,446,744,073,709,551,615 into the data stream.

Warning
JavaScript doesn't directly support 64-bit Integers, so for very large values expect some precision to be lost in the conversion between JavaScript's native double and 64-bit Integer. You might want to use serialize_d() instead.
Note
data size: 8 bytes
See Also
Deserializer.deserialize_8u
serialize_bool ( boolean  val)

serialize a 1 bit boolean value

Write a one bit boolean value (true or false) into the data stream. This is optimized collect up to 8 bits in a single byte, so writing a number of boolean values is very space efficient.

Note
data size: varies, call serializedSize(bool) to determine
See Also
serializedSize(bool)
Deserializer.deserialize_bool()
serialize_color ( Color  val)

serialize a Color

Write a Color's RBGA values into the data stream.

Warning
the Color is written as a 24 (no alpha channel) or 32 bit color (with alpha channel). If you need to preserve greater color precision than this, you will need to serialize the components yourself.
Note
data size: varies, call serializedSize(Color) to determine
See Also
serializedSize(Color)
Deserializer.deserialize_color()
serialize_d ( number  val)

serialize a double precision floating point number

Write a double precision floating point value in the range of 10−308 to 10308 with 17 significant digits into the data stream.

Warning
if the value is outside the range then the results are unknown.
Note
data size: 8 bytes (IEEE 754-2008 binary64 format)
See Also
Deserializer.deserialize_d
serialize_f ( number  val)

serialize a single precision floating point number

Write a single precision floating point value in the range of 10−38 to 1038 with 9 significant digits into the data stream.

Warning
if the value is outside the range then the results are unknown.
Note
data size: 4 bytes (IEEE 754-2008 binary32 format)
See Also
Deserializer.deserialize_f
serialize_mem ( BinaryString  mem)

serialize a binary string

Binary strings are a Node.js way of handling blocks of arbitrary binary data. This serializes that data into the stream.

Deprecated:
Node.js maintainers have deprecated BinaryString, so it may not be around in future versions
Note
data size: varies, call serializedSize(MemBlock) to determine. Because binary strings used 2 bytes for each actual byte stored, the serialized data takes less memory than the original string.
See Also
serialize_mem(MemBlock)
serializedSize(MemBlock)
Deserializer.deserialize_mem
serialize_mem ( MemBlock  mem)

serialize a block of memory

MemBlocks are the game engine's way of handling blocks of arbitrary binary data in JavaScript. This serializes that data into the stream.

Note
data size: varies, call serializedSize(MemBlock) to determine.
See Also
serializedSize(MemBlock)
Deserializer.deserialize_mem
serialize_obj ( ISerializable  obj)

serialize a serializable object

This serializes the object and all its data into the stream. It does this by calling the ISerializable object's serialize method, which would then in turn call serializer methods for each of the object's data members. If the given object's data members include other serializable objects, then serialize_obj() is called recursively to serialize those objects.

The Serializer keeps track of what objects have already been added to the stream, and simply serializes a reference to any object that has already been serialized if serialize_obj is called for it again.

Note
data size: varies, call serializedSize() to determine.
See Also
serializedSize(ISerializable)
Deserializer.deserialize_obj
ISerializable
serialize_offset ( Offset  val)

serialize an Offset's (x,y) values

Write an Offset's x and y values into the data stream. This is optimized for certain common cases, such as a (0,0) offset and small positive numbers.

Warning
because JavaScript handles floating-point numbers as doubles internally but an Offset is streamed using floats, some precision is lost. If you need that precision you should serialize the Offset's x and y values yourself using serialize_d()
Note
data size: varies, call serializedSize(Offset) to determine
See Also
serializedSize(Offset)
Deserializer.deserialize_offset()
serialize_point ( Point  val)

serialize a Point's (x,y) values

Write a Point's x and y values into the data stream. This is optimized for certain common cases, such as Point(0,0) and small positive numbers.

Warning
because JavaScript handles floating-point numbers as doubles internally but a Point is streamed using floats, some precision is lost. If you need that precision you should serialize the Point's x and y values yourself using serialize_d()
Note
data size: varies, call serializedSize(Point) to determine
See Also
serializedSize(Point)
Deserializer.deserialize_point()
serialize_quad ( Quad  val)

serialize a Quad's (x,y) point values

Write a Quad's four sets of x and y values into the data stream.

Warning
because JavaScript handles floating-point numbers as doubles internally but a Quad is streamed using floats, some precision is lost. If you need that precision you should serialize the Quad's array of x and y values yourself using serialize_d()
Note
data size: varies, call serializedSize(Quad) to determine
See Also
serializedSize(Quad)
Deserializer.deserialize_quad()
serialize_rect ( Rect  val)

serialize a Rect's left, top, right, bottom values

Write a Rect's left, top, right, and bottom values into the data stream. This is optimized for certain common cases, such as empty rectangles and small positive numbers.

Warning
because JavaScript handles floating-point numbers as doubles internally but a Rect is streamed using floats, some precision is lost. If you need that precision you should serialize the Rect's left, top, right, and bottom values yourself using serialize_d()
Note
data size: varies, call serializedSize(Rect) to determine
See Also
serializedSize(Rect)
Deserializer.deserialize_rect()
serialize_ref ( object  obj)
serialize_rotr ( RotatedRect  val)

serialize a RotatedRect's data values

Write a RotatedRect's left, top, right, bottom, radians and centerOffset values into the data stream. This is optimized for certain common cases, such as empty rectangles, small positive numbers, and no center offset.

Warning
because JavaScript handles floating-point numbers as doubles internally but a RotatedRect is streamed using floats, some precision is lost. If you need that precision you should serialize the RotatedRect's left, top, right, bottom, radians, centerOffset.x and centerOffset.y values yourself using serialize_d()
Note
data size: varies, call serializedSize(RotatedRect) to determine
See Also
serializedSize(RotatedRect)
Deserializer.deserialize_rotr()
serialize_str ( string  str)

serialize a JavaScript string

Writes the string into the data stream.

Note
data size: varies, call serializedSize() to determine. Format is Unicode UTF-8.
See Also
serializedSize(string)
Deserializer.deserialize_str
serialize_uint ( uint  val)

serialize up to 4 unsigned bytes

Write a value in the range of 0 to 4,294,967,295 into the data stream. This is optimized for cases where the number is usually small, but can sometimes be quite large. If the number is usually large, you are better off just using serialize_4u.

Note
data size: varies, 1 to 5 bytes, call serializedSize() to determine.
See Also
serializedSize(uint)
serialize_4u
Deserializer.deserialize_uint
serialize_vector ( Vector  val)

serialize a Vector's (x,y) values

Write a Vector's x and y values into the data stream. This is optimized for certain common cases, such as a (0,0) offset and small positive numbers.

Warning
because JavaScript handles floating-point numbers as doubles internally but a Vector is streamed using floats, some precision is lost. If you need that precision you should serialize the Vector's x and y values yourself using serialize_d()
Note
data size: varies, call serializedSize(Vector) to determine
See Also
serializedSize(Vector)
Deserializer.deserialize_vector()
uint sizeof_1 ( int  val)
uint sizeof_1u ( uint  val)
uint sizeof_2 ( int  val)
uint sizeof_2u ( uint  val)
uint sizeof_3u ( uint  val)
uint sizeof_4 ( int  val)
uint sizeof_4u ( uint  val)
uint sizeof_8 ( int  val)
uint sizeof_8u ( uint  val)
sizeof_bool ( boolean  val)

get the number of bytes used to serialize the given boolean

Does not actually write any data to stream

Returns
the number of bytes needed (0 or 1)
Note
this will often return 0, which simply means that the particular boolean bit is being stored along with other boolean bits in a previously reserved space in the stream, so no additional bytes were needed
See Also
serialize_bool
sizeof_color ( Color  val)

get the number of bytes used to serialize the given Color

Does not actually write any data to stream

Returns
the number of bytes needed (3-5)
See Also
serialize_color
uint sizeof_d ( number  val)
uint sizeof_f ( number  val)
uint sizeof_mem ( BinaryString  mem)
sizeof_mem ( MemBlock  mem)

get the number of bytes used to serialize the given block of memory

Does not actually write any data to stream

Returns
the number of bytes needed
See Also
serialize_mem
sizeof_obj ( ISerializable  obj)

get the number of bytes used to serialize the given object, including any objects that it serializes

Does not actually write any data to stream

Returns
the number of bytes needed
See Also
serialize_obj
sizeof_offset ( Offset  val)

get the number of bytes used to serialize the given Offset

Does not actually write any data to stream

Returns
the number of bytes needed (0-9)
Note
this can return 0 for an offset whose value is (0,0), since a zero offset is optimized to be stored as a single bit.
See Also
serialize_offset
sizeof_point ( Point  val)

get the number of bytes used to serialize the given Point

Does not actually write any data to stream

Returns
the number of bytes needed (0-9)
Note
this can return 0 for a Point whose value is (0,0), since a point at origin is optimized to be stored as a single bit.
See Also
serialize_point
sizeof_quad ( Quad  val)

get the number of bytes used to serialize the given Quad

Does not actually write any data to stream

Returns
the number of bytes needed (0-34)
Note
this can return 0 under some conditions, such as a Quad made up of 4 points at the origin, which is optimized to be stored in 4 bits.
See Also
serialize_quad
sizeof_rect ( Rect  val)

get the number of bytes used to serialize the given Rect

Does not actually write any data to stream

Returns
the number of bytes needed (0-17)
Note
this can return 0 under some conditions, such as an Rect located at (0,0) with zero width or height, which is optimized to be stored in 2 bits.
See Also
serialize_rect
uint sizeof_ref ( object  val)
sizeof_rotr ( RotatedRect  val)

get the number of bytes used to serialize the given RotatedRect

Does not actually write any data to stream

Returns
the number of bytes needed (4-30)
See Also
serialize_rotr
sizeof_str ( string  str)

get the number of bytes used to serialize the given string

Does not actually write any data to stream

Returns
the number of bytes needed
See Also
serialize_str
sizeof_uint ( uint  n)

get the number of bytes used to serialize the given unsigned integer

Does not actually write any data to stream.

Returns
the number of bytes needed (1-5)
See Also
serialize_uint
sizeof_vector ( Vector  val)

get the number of bytes used to serialize the given Vector

Does not actually write any data to stream

Returns
the number of bytes needed (0-9)
Note
this can return 0 for an vector whose value is (0,0), since a zero vector is optimized to be stored as a single bit.
See Also
serialize_vector

User Comments