skia2/site/dev/contrib/flatten.md

Flattenables
============

Many objects in Skia, such as `SkShaders` and other effects on `SkPaint`, need to be 
flattened into a data stream for either transport or as part of the key to the 
font cache. Classes for these objects should derive from `SkFlattenable` or one of 
its subclasses. If you create a new flattenable class, you need to make sure you 
do a few things so that it will work on all platforms:

1: Override the method `flatten` (the default scope is protected):

<!--?prettify?-->
~~~~
virtual void flatten(SkFlattenableWriteBuffer& buffer) const override {
    this->INHERITED::flatten(buffer);
    // Write any private data that needs to be stored to recreate this object
}
~~~~

2: Override the (protected) constructor that creates an object from an 
`SkFlattenableReadBuffer`:

<!--?prettify?-->
~~~~
SkNewClass(SkFlattenableReadBuffer& buffer)
: INHERITED(buffer) {
    // Read the data from the buffer in the same order as it was written to the
    // SkFlattenableWriteBuffer and construct the new object
}
~~~~

3: Declare a set of deserialization procs for your object in the class declaration:
We have a macro for this:

<!--?prettify?-->
~~~~
public:

SK_DECLARE_PUBLIC_FLATTENABLE_DESERIALIZATION_PROCS(SkNewClass)
~~~~

4: If your class is declared in a `.cpp` file or in a private header file, create a 
function to register its group:
This occurs in cases where the classes are hidden behind a factory, like many effects 
and shaders are.  Then in the parent class header file (such as `SkGradientShader`) you 
need to add:

<!--?prettify?-->
~~~~
public:

SK_DECLARE_FLATTENABLE_REGISTRAR_GROUP()
~~~~

Then in the cpp file you define all the members of the group together:

<!--?prettify?-->
~~~~
SK_DEFINE_FLATTENABLE_REGISTRAR_GROUP_START(SkGroupClass)

    SK_DEFINE_FLATTENABLE_REGISTRAR_ENTRY(SkMemberClass1)

    SK_DEFINE_FLATTENABLE_REGISTRAR_ENTRY(SkMemberClass2)

    // etc

SK_DEFINE_FLATTENABLE_REGISTRAR_GROUP_END
~~~~


5: Register your flattenable with the global registrar:
You need to add one line to `SkFlattenable::InitalizeFlattenables()`. To register the 
flattenable in a Skia build, that function is defined in `SkGlobalInitialization_default.cpp`. 
For Chromium, it is in `SkGlobalInitialization_chromium.cpp`.
For a single flattenable add

<!--?prettify?-->
~~~~
SK_DEFINE_FLATTENABLE_REGISTRAR_ENTRY(SkNewClass)
~~~~

For a group, add

<!--?prettify?-->
~~~~
SkGroupClass::InitializeFlattenables();
~~~~