ezEngine  Milestone 7
ezSerializationContext< DERIVED > Class Template Reference

A serialization context is used to (de-)serialize special types that require more complex logic than just moving a few bytes. More...

#include <SerializationContext.h>

Static Public Member Functions

static DERIVED * GetReaderContext (ezStreamReaderBase *pStream)
 Returns the serialization context that is associated with the given stream (may be NULL). More...
 
static DERIVED * GetWriterContext (ezStreamWriterBase *pStream)
 Returns the serialization context that is associated with the given stream (may be NULL). More...
 

Protected Member Functions

 ezSerializationContext ()
 Constructor.
 
 ~ezSerializationContext ()
 The destructor ensures that stream associations are reset.
 
void RegisterReaderStream (ezStreamReaderBase *pStream)
 The deriving class should call this to associate this serialization context with the given stream. More...
 
void UnregisterReader ()
 Resets the association with any previous reader stream.
 
void RegisterWriterStream (ezStreamWriterBase *pStream)
 The deriving class should call this to associate this serialization context with the given stream. More...
 
void UnregisterWriter ()
 Resets the association with any previous writer stream.
 

Private Attributes

ezStreamReaderBasem_pReaderStream
 
ezStreamWriterBasem_pWriterStream
 

Static Private Attributes

static ezMap
< ezStreamReaderBase
*, DERIVED * > 
s_ActiveReaderContexts
 
static ezMap
< ezStreamWriterBase
*, DERIVED * > 
s_ActiveWriterContexts
 

Detailed Description

template<typename DERIVED>
class ezSerializationContext< DERIVED >

A serialization context is used to (de-)serialize special types that require more complex logic than just moving a few bytes.

A serialization context can, for example, be used to keep track of which objects have already been serialized into a stream, such that when they are written a second time to the stream, only a reference to the first one is actually stored. Upon deserialization the context of course needs to resolve these references properly.

In general a serialization context only provides additional 'state' per stream and for a specific set of types. There can be any number of serialization contexts active for the same stream, they are basically 'tacked on' from the outside, the stream itself knows nothing of serialization contexts.

A serialization context is created by deriving from ezSerializationContext, passing the own class as the template argument.

In the derived class you have to implement two functions per type that the context is supposed to handle:
(virtual) void Read (ezStreamReaderBase& stream, TYPE& type)
(virtual) void Write(ezStreamWriterBase& stream, const TYPE& type)

The macro EZ_ADD_SERIALIZATION_CONTEXT_OPERATORS() will then add the << and >> operators that redirect serialization of that type to these Read/Write functions.

In these functions you can implement whatever complex logic is necessary to (de-)serialize the type and you can keep custom state.

When serializing to or from some stream, you need to create an instance of your serialization context and associate it with the reader / writer stream. This should be done by the derived class implementation by calling RegisterReaderStream() and RegisterWriterStream(). Once that is done, the static functions GetReaderContext() and GetWriterContext() give access to the serialization context that is associated with a given stream. For details how this can be used, see the code in the EZ_ADD_SERIALIZATION_CONTEXT_OPERATORS() macro.

Member Function Documentation

template<typename DERIVED >
static DERIVED* ezSerializationContext< DERIVED >::GetReaderContext ( ezStreamReaderBase pStream)
inlinestatic

Returns the serialization context that is associated with the given stream (may be NULL).

As long as you use the EZ_ADD_SERIALIZATION_CONTEXT_OPERATORS() macro, it is typically not necessary to call this function directly.

template<typename DERIVED >
static DERIVED* ezSerializationContext< DERIVED >::GetWriterContext ( ezStreamWriterBase pStream)
inlinestatic

Returns the serialization context that is associated with the given stream (may be NULL).

As long as you use the EZ_ADD_SERIALIZATION_CONTEXT_OPERATORS() macro, it is typically not necessary to call this function directly.

template<typename DERIVED >
void ezSerializationContext< DERIVED >::RegisterReaderStream ( ezStreamReaderBase pStream)
inlineprotected

The deriving class should call this to associate this serialization context with the given stream.

Each context can only be associated with one reader and one writer stream.

template<typename DERIVED >
void ezSerializationContext< DERIVED >::RegisterWriterStream ( ezStreamWriterBase pStream)
inlineprotected

The deriving class should call this to associate this serialization context with the given stream.

Each context can only be associated with one reader and one writer stream.


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