Menu
Lumberyard
C++ API Reference (Version 1.10)

Classes | Public Types | Public Member Functions | Friends | List of all members
AZ::SerializeContext Class Reference

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

The serialize context contains information about every Lumberyard class that might need to be saved to persistent storage and reconstructed in memory. More...

Inherits AZ::ReflectContext .

Classes

class ClassData
This structure is built up and stored in the serialize context while you are calling SerializeContext::ClassInfo functions to reflect a class's data to the serialize context. More...
struct ClassElement
A subelement of a class that is reflected to the serialize context. More...
class ClassInfo
Builder class that reflects class members to the serialize context. More...
struct DataElement
Represents an element within the tree of serialized data. More...
class DataElementNode
Represents a node in the tree of serialized data. More...
struct DbgStackEntry
A debug stack element that provides useful debugging information as Lumberyard traverses through the class hierarchy to serialize data. More...
class ErrorHandler
Reports errors and warnings as Lumberyard serializes data. More...
class IEventHandler
You can use this class if you want special functions to run before reading or writing a class. More...

Public Types

typedef VersionConverter
A callback function that converts old versions of a class to the latest version. More...
typedef ClassPersistentId
A callback function that, given a class instance, returns a u64 that represents the persistent ID of the instance. More...
typedef UuidToClassMap
A type that is used to map all classes in the serialize context to their unique ID. More...
typedef ClassElementArray
An array of class elements. More...

Public Member Functions

SerializeContext (bool registerIntegralTypes=true, bool createEditContext=false)
Initializes a SerializeContext object. More...
virtual ~SerializeContext ()
A destructor. More...
EditContext * CreateEditContext ()
Creates a global EditContext to enable data to be reflected for editing in Lumberyard Editor. More...
void DestroyEditContext ()
Destroys the EditContext and frees all edit-related reflection data. More...
EditContext * GetEditContext () const
Returns a pointer to the EditContext that corresponds to this SerializeContext . More...
template<class T >
ClassInfo Class ()
Creates a temporary object ( ClassInfo ) that you call functions on to add reflected classes and data to the serialize context. More...
template<class T , class B1 >
ClassInfo Class ()
A version of Class() that automatically reflects a base class of the reflected class. More...
template<class T , class B1 , class B2 >
ClassInfo Class ()
A version of Class() that automatically reflects two base classes of the reflected class. More...
template<class T , class B1 , class B2 , class B3 >
ClassInfo Class ()
A version of Class() that automatically reflects three base classes of the reflected class. More...
void ClassDeprecate (const char *name, const AZ::Uuid &typeUuid, VersionConverter converter=nullptr)
Deprecates a previously reflected class. More...
- Public Member Functions inherited from AZ::ReflectContext
ReflectContext ()
Initializes a reflection context instance. More...
virtual ~ReflectContext ()
An empty destructor. More...
void EnableRemoveReflection ()
Sets the behavior such that calls to this context remove reflection for types passed to it. More...
void DisableRemoveReflection ()
Sets the behavior such that calls to this context add reflection for types passed to it. More...
bool IsRemovingReflection () const
Indicates whether calls to this context remove reflection for types passed to it. More...

Friends

class EditContext

Detailed Description

The serialize context contains information about every Lumberyard class that might need to be saved to persistent storage and reconstructed in memory.

For example, a game might enable users to save the level state to a disk. To load the level, Lumberyard must have the information it needs to reconstruct the relevant classes in memory.

There is one SerializeContext instance, and that instance manages the information for all classes that are reflected to it.

Note
Although you can reflect any class, you most commonly reflect AZ::Component classes.

To reflect a class's information to the serialize context, you must add code to the class's implementation of the Reflect() function.

Your class can reflect two types of information to the serialize context: data and versioning. The data is simply the member variables that you want to reflect. Versioning, which is optional, enables you to convert old versions of a class to the latest version of the class. As a simple example, you can replace one member variable with another. You can also use versioning to deprecate classes. To do versioning, you provide a version converter function that specifies how to convert or deprecate the class.

If your class never needs to be saved to persistent storage, then you do not need to reflect it to the serialize context. However, the EditContext , which makes class data editable in Lumberyard Editor, depends on the SerializeContext . If you want to reflect data to the edit context, you must first reflect it to the serialize context.

The following example shows how a class can implement its Reflect() function to reflect its data and version information to the serialize context. The code uses a builder pattern to reflect multiple fields.

class MyClass
{
public :
int m_data;
int m_otherData;
static void Reflect( AZ::ReflectContext * context);
};
void MyClass::Reflect( AZ::ReflectContext * context)
{
AZ::SerializeContext * serialize = azrtti_cast < AZ::SerializeContext *>(context);
if (serialize)
{
serialize-> Class <MyClass>()
->Version(1) // Sets the version number.
-> Field ( "DataName" , &MyClass::m_data) // Reflects a member variable.
-> Field ( "OtherDataName" , &MyClass::m_otherData); // Reflects a member variable.
}
}

The following example shows how to specify a version converter function when you reflect to the serialize context.

void MyClass::Reflect( AZ::ReflectContext * context)
{
AZ::SerializeContext * serialize = azrtti_cast < AZ::SerializeContext *>(context);
if (serialize)
{
serialize-> Class <MyClass>()
->Version(2, &MyClass::VersionConverter) // Provides a version converter.
-> Field ( "DataName" , &MyClass::m_data)
-> Field ( "OtherDataName" , &MyClass::m_otherData);
}
}

For example version converter functions, see VersionConverter and ClassDeprecate() .

If you have special requirements, you can write a custom serializer, but this is rarely needed. You typically use the previously described pattern to reflect the information to the serialize context, and Lumberyard implements the code to save data to persistent storage for you.

For information about reflecting components, see Reflecting a Component for Serialization and Editing in the Lumberyard User Guide .

To see real examples of reflecting to the serialize context, browse the Reflect() implementations of components in lumberyard-root\dev\Gems\LmbrCentral\Code\Source .

Member Typedef Documentation

◆ ClassElementArray

typedef AZStd::vector< ClassElement > AZ::SerializeContext::ClassElementArray

An array of class elements.

Class elements are subelements of classes that are reflected to the serialize context.

◆ ClassPersistentId

typedef u64(* AZ::SerializeContext::ClassPersistentId) (const void *)

A callback function that, given a class instance, returns a u64 that represents the persistent ID of the instance.

Persistent IDs enable slices to more easily track instances of classes that are stored in index-based containers like vectors or lists.

◆ UuidToClassMap

typedef AZStd::unordered_map<Uuid, ClassData > AZ::SerializeContext::UuidToClassMap

A type that is used to map all classes in the serialize context to their unique ID.

◆ VersionConverter

typedef bool(* AZ::SerializeContext::VersionConverter) ( SerializeContext &, DataElementNode &)

A callback function that converts old versions of a class to the latest version.

It can also provide replacement classes for deprecated classes.

The following example is a version converter function that replaces one member variable (area value) with two member variables (length and width values).

bool MyClass::VersionConverter( AZ::SerializeContext & context,
AZ::SerializeContext::DataElementNode & classElement)
{
// Version 2 converter: Replace AreaSize with AreaWidth and AreaHeight.
if (classElement. GetVersion () <= 2)
{
int areaIndex = classElement. FindElement (AZ_CRC( "AreaSize" , 0x287b852c));
if (areaIndex < 0)
{
return false ;
}
// Get the size.
AZ::SerializeContext::DataElementNode & area = classElement. GetSubElement (areaIndex);
AZ::Vector3 size;
area. GetData < AZ::Vector3 >(size);
// Create elements for width and height.
int areaWidthIndex = classElement. AddElement < float >(context, "AreaWidth" );
int areaHeightIndex = classElement. AddElement < float >(context, "AreaHeight" );
AZ::SerializeContext::DataElementNode & areaWidth = classElement. GetSubElement (areaWidthIndex);
AZ::SerializeContext::DataElementNode & areaHeight = classElement. GetSubElement (areaHeightIndex);
// Set width and height values to x and y from the old size.
areaWidth. SetData < float >(context, size.GetX());
areaHeight. SetData < float >(context, size.GetY());
// Remove the old element.
classElement. RemoveElement (areaIndex);
}
return true ;
}

For an example of a version converter that replaces a deprecated class with a new class, see ClassDeprecate() .

Constructor & Destructor Documentation

◆ SerializeContext()

AZ::SerializeContext::SerializeContext ( bool registerIntegralTypes = true ,
bool createEditContext = false
)

Initializes a SerializeContext object.

Parameters
registerIntegralTypes Set this to true if you want Lumberyard to use the default serializer for all fundamental types.
createEditContext Indicates whether to create an edit context. If you want your classes to be editable in Lumberyard Editor, you must set this value to true and reflect the appropriate data to the edit context. That process is described in EditContext . The default value is false.

◆ ~SerializeContext()

virtual AZ::SerializeContext::~SerializeContext ( )
virtual

A destructor.

Member Function Documentation

◆ Class() [1/4]

template<class T >
ClassInfo AZ::SerializeContext::Class ( )

Creates a temporary object ( ClassInfo ) that you call functions on to add reflected classes and data to the serialize context.

Uses a builder pattern.

If your class has one or more base classes that you want to reflect to the serialize context, use a version of this function that takes base classes as additional template parameters.

Template Parameters
T The class type to reflect.
Returns
An object that contains information about all the data that a class is reflecting to the serialize context.

◆ Class() [2/4]

template<class T , class B1 >
ClassInfo AZ::SerializeContext::Class ( )

A version of Class() that automatically reflects a base class of the reflected class.

The following example shows how to reflect the AZ::Component base class when you reflect a derived component.

class MyComponent : public AZ::Component
{
public :
int m_data;
static void Reflect( AZ::ReflectContext * context);
};
void MyComponent::Reflect( AZ::ReflectContext * context)
{
AZ::SerializeContext * serialize = azrtti_cast < AZ::SerializeContext *>(context);
if (serialize)
{
serialize-> Class <MyComponent, AZ::Component >()
->Version(1)
->Field( "DataName" , &MyComponent::m_data);
}
}
Template Parameters
T The class type to reflect.
B1 A base class of the class that you want to reflect.
Returns
An object that contains information about all the data that a class is reflecting to the serialize context.

◆ Class() [3/4]

template<class T , class B1 , class B2 >
ClassInfo AZ::SerializeContext::Class ( )

A version of Class() that automatically reflects two base classes of the reflected class.

Template Parameters
T The class type to reflect.
B1 A base class of the class that you want to reflect.
B2 A base class of the class that you want to reflect.
Returns
An object that contains information about all the data that a class is reflecting to the serialize context.

◆ Class() [4/4]

template<class T , class B1 , class B2 , class B3 >
ClassInfo AZ::SerializeContext::Class ( )

A version of Class() that automatically reflects three base classes of the reflected class.

Template Parameters
T The class type to reflect.
B1 A base class of the class that you want to reflect.
B2 A base class of the class that you want to reflect.
B3 A base class of the class that you want to reflect.
Returns
An object that contains information about all the data that a class is reflecting to the serialize context.

◆ ClassDeprecate()

void AZ::SerializeContext::ClassDeprecate ( const char * name ,
const AZ::Uuid & typeUuid ,
VersionConverter converter = nullptr
)

Deprecates a previously reflected class.

You do not need to keep deprecated classes in the code.

Parameters
name The name of the deprecated class.
typeUuid The UUID of the deprecated class.
converter (Optional) A pointer to a VersionConverter function.

The following is an example that shows how to call ClassDeprecate() to deprecate a class, and an example of a version converter to use with it.

class NewClass
{
public :
static void Reflect( AZ::ReflectContext * context);
static bool DeprecateClass( AZ::SerializeContext & context, AZ::SerializeContext::DataElementNode & classElement);
private :
ClassConfiguration m_configuration; // Stores the configuration for the class.
};
void NewClass::Reflect( AZ::ReflectContext * context)
{
ClassConfiguration::Reflect(context);
if ( auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
{
// Deprecate the old class and specify the version converter.
serializeContext->ClassDeprecate( "OldClass" ,
"{OLD-CLASS-UUID}" ,
&NewClass::DeprecateClass
);
serializeContext->Class<NewClass>()
->Version(1)
->Field( "Configuration" , &NewClass::m_configuration);
}
}
bool NewClass::DeprecateClass( AZ::SerializeContext & context, AZ::SerializeContext::DataElementNode & classElement)
{
// Cache the configuration.
ClassConfiguration configuration;
int configIndex = classElement. FindElement (AZ_CRC( "Configuration" ));
if (configIndex != -1)
{
classElement. GetSubElement (configIndex). GetData <ClassConfiguration>(configuration);
}
// Convert the old class to the new class.
bool result = classElement. Convert (context, "{NEW-CLASS-UUID}" );
if (result)
{
configIndex = classElement. AddElement <ClassConfiguration>(context, "Configuration" );
if (configIndex != -1)
{
classElement. GetSubElement ( configIndex ). SetData <ClassConfiguration>(context, configuration);
}
return true ;
}
return false ;
}

◆ CreateEditContext()

EditContext * AZ::SerializeContext::CreateEditContext ( )

Creates a global EditContext to enable data to be reflected for editing in Lumberyard Editor.

If an edit context already exists, a pointer to it is returned.

Returns
A pointer to the edit context.

◆ DestroyEditContext()

void AZ::SerializeContext::DestroyEditContext ( )

Destroys the EditContext and frees all edit-related reflection data.

You don't need to call DestroyEditContext() because it is automatically called when Lumberyard destroys the SerializeContext .

◆ GetEditContext()

EditContext * AZ::SerializeContext::GetEditContext ( ) const

Returns a pointer to the EditContext that corresponds to this SerializeContext .

Returns
A pointer to the edit context. Returns null if an edit context does not exist.

Friends And Related Function Documentation

◆ EditContext

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