DescribeIO Manual

内容表

关于

A custom data type or an implementation of an interface will contain some internal data. A static custom DescribeIO() function describes how this data is written to or from a file.

注意
DescribeIO() does not directly access the file but instructs Cinema 4D how to handle the data.

Data Serialization

A DescribeIO() function handles the given maxon::DataSerializeInterface argument. This object should not be handled directly; only with these macros:

Certain elements may only be handled if a certain condition is fulfilled:

This snippet shows a simple custom data type:

// This example shows a simple custom data type.
class SimpleTriplet { public : SimpleTriplet();

// DescribeIO() describes how the data type is stored in a file static maxon::Result<void> DescribeIO ( const maxon::DataSerializeInterface & stream);

maxon::Int _a; // first element maxon::Int _b; // second element maxon::Int _c; // third element }; MAXON_DATATYPE (SimpleTriplet, "net.maxonexample.datatype.simpletriplet" );

This is the straightforward implementation of DescribeIO() .

// This example shows a simple implementation of DescribeIO(). // The member data of the data type is simply stored in the file. maxon::Result<void> SimpleTriplet::DescribeIO ( const maxon::DataSerializeInterface & stream) { iferr_scope ; PrepareDescribe (stream, SimpleTriplet);

// each member variable is stored in the file Describe ( "_a" , _a, maxon::Int , maxon::DESCRIBEFLAGS::NONE ) iferr_return ; Describe ( "_b" , _b, maxon::Int , maxon::DESCRIBEFLAGS::NONE ) iferr_return ; Describe ( "_c" , _c, maxon::Int , maxon::DESCRIBEFLAGS::NONE ) iferr_return ; return maxon::OK ; }

DescribeIO() is invoked when an instance of the data type is written to or read from a file:

// This example creates an instance of a custom data type that implements DescribeIO(). // The instance is saved to a file using maxon::WriteDocument(). After that, // maxon::ReadDocument() is used to read the data from the given file.

// define data SimpleTriplet triplet; triplet._a = 100; triplet._b = 200; triplet._c = 300;

// file URL const maxon::Url url = (targetFolder + "triplet.txt" _s) iferr_return ; const maxon::Id fileID { "net.maxonexample.simpletriplet" };

// save to file maxon::WriteDocument (url, maxon::OPENSTREAMFLAGS::NONE , fileID, triplet, maxon::IOFORMAT::JSON ) iferr_return ;

// read from file SimpleTriplet loadedTriplet; maxon::ReadDocument (url, fileID, loadedTriplet) iferr_return ;

// display loaded data DiagnosticOutput ( "Loaded Triplet: @, @, @" , loadedTriplet._a, loadedTriplet._b, loadedTriplet._c);

The write-process will result in a file like this:

{ "identification" : "net.example.simpletriplet" , "content" : { "_a" : 100, "_b" : 200, "_c" : 300 } }

Helper Classes

A helper class is used to define code that is executed when Cinema 4D handles the data. The helper class is used with these macros:

// This example shows a helper class and how it is used in an implementation of DescribeIO(). // The functions of the helper class are invoked as defined with PrepareHelper(). // The helper functions handle modified data that is stored with a file.

// helper class class TripletHelperClass { public : // WriteAction() is called when data is written to a file, as defined with PrepareHelper() maxon::Result<void> WriteAction( maxon::DataSerializeInterface * ds, const HelperTriplet& triplet, maxon::UInt elementHash) { // construct on initialization if (elementHash == maxon::INITIALIZEHASH ) { // all the data should be stored as a single string // the triplet values are merged into this single string _combined = maxon::String::IntToString(triplet._a); _combined += "::" _s; _combined += maxon::String::IntToString(triplet._b); _combined += "::" _s; _combined += maxon::String::IntToString(triplet._c); } return maxon::OK ; }

// ReadAction() is called when data is read from a file, as defined with PrepareHelper() maxon::Result<void> ReadAction( maxon::DataSerializeInterface * ds, HelperTriplet& triplet, maxon::UInt elementHash) { iferr_scope ;

// deconstruct on finalization if (elementHash == maxon::FINALIZEHASH ) { // all data is stored in a single string

// split string maxon::BaseArray<maxon::String> parts; _combined.Split( "::" _s, true , parts) iferr_return ;

// check element count const maxon::Int count = parts. GetCount (); DebugAssert (count == 3);

// store values in the original data type triplet._a = parts[0].ToInt() iferr_return ; triplet._b = parts[1].ToInt() iferr_return ; triplet._c = parts[2].ToInt() iferr_return ; } return maxon::OK ; } maxon::String _combined; // string containing all data }; maxon::Result<void> HelperTriplet::DescribeIO ( const maxon::DataSerializeInterface & stream) { iferr_scope ; PrepareDescribe (stream, HelperTriplet); // prepare helper class // the helper functions should be invoked on initialization / finalization PrepareHelper (TripletHelperClass, maxon::PREPAREHELPERFLAGS::INITIALIZE_WRITE | maxon::PREPAREHELPERFLAGS::FINALIZE_READ ); // the helper's "_combined" member will be stored in the file DescribeHelper ( "data" , _combined, maxon::String , maxon::DESCRIBEFLAGS::NONE ) iferr_return ; return maxon::OK ; }

This will result in a file like this:

{ "identification" : "net.example.helpertriplet" , "content" : { "data" : "100::200::300" } }

This more complex example uses DescribeHelperIf() :

// This example shows a helper class and how it is used in an implementation of DescribeIO(). // The helper class analyses the values stored in the given object. If all triplet values are the same, // only one number is stored in a file. If the values are not the same, all values are stored.

// helper class class CompactTripletHelperClass { // hashes for relevant helper members // used to identify values handled in WriteAction() / ReadAction() CONSTHASH (_compact); // hash for _compact CONSTHASH (_compactValue); // hash for _compactValue CONSTHASH (_z); // hash for _z public : // WriteAction() is called as defined with DescribeHelperIf() maxon::Result<void> WriteAction( maxon::DataSerializeInterface * ds, const CompactTriplet& triplet, maxon::UInt elementHash) { // writing the " _compact" value if (elementHash == _compactHash) { // if all three values are the same, store only one value in "compact" mode const maxon::Bool aEqualsB = triplet._a == triplet._b; const maxon::Bool bEqualsC = triplet._b == triplet._c; if (aEqualsB && bEqualsC) { _compact = true ; _compactValue = triplet._a; } else { // store each individual value _compact = false ; _x = triplet._a; _y = triplet._b; _z = triplet._c; } } return maxon::OK ; }

// ReadAction() is called as defined with DescribeHelper() maxon::Result<void> ReadAction( maxon::DataSerializeInterface * ds, CompactTriplet& triplet, maxon::UInt elementHash) { switch (elementHash) { // load compact value; DESCRIBEFLAGS::ACTION_AFTER_READ was set case (_compactValueHash): { triplet._a = _compactValue; triplet._b = _compactValue; triplet._c = _compactValue; break ; } // last individual value has been loaded; DESCRIBEFLAGS::ACTION_AFTER_READ was set case (_zHash): { // load all values after the third value has been read triplet._a = _x; triplet._b = _y; triplet._c = _z; break ; } default : { break ; } } return maxon::OK ; }

// helper class member data // the member name must be the same as the name used with DescribeHelper() maxon::Bool _compact; // compact mode maxon::Int _compactValue; // compact value maxon::Int _x; // x value maxon::Int _y; // y value maxon::Int _z; // z value }; maxon::Result<void> CompactTriplet::DescribeIO ( const maxon::DataSerializeInterface & stream) { iferr_scope ; PrepareDescribe (stream, CompactTriplet); // prepare helper PrepareHelper (CompactTripletHelperClass, maxon::PREPAREHELPERFLAGS::NONE );

// check if compact mode or not when writing to file DescribeHelperIf ( "_compact" , _compact, maxon::Bool , maxon::DESCRIBEFLAGS::ACTION_BEFORE_WRITE , true , true ) iferr_return ; { // store compact value; handle values after reading DescribeHelper ( "_compactValue" , _compactValue, maxon::Int , maxon::DESCRIBEFLAGS::ACTION_AFTER_READ ) iferr_return ; } DescribeElse () iferr_return ; { // simply write/read all values into the helper class DescribeHelper ( "_x" , _x, maxon::Int , maxon::DESCRIBEFLAGS::NONE ) iferr_return ; DescribeHelper ( "_y" , _y, maxon::Int , maxon::DESCRIBEFLAGS::NONE ) iferr_return ; // after all values have been loaded, copy to data type DescribeHelper ( "_z" , _z, maxon::Int , maxon::DESCRIBEFLAGS::ACTION_AFTER_READ ) iferr_return ; } DescribeEndIf () iferr_return ; return maxon :: OK ; }

A "compact" file using the same value for each channel will look like this:

{ "identification" : "net.example.compacttriplet" , "content" : { "_compact" : true , "_compactValue" : 100 } }

A non-compact file will look like this:

{ "identification" : "net.example.compacttriplet" , "content" : { "_compact" : false , "_x" : 10, "_y" : 100, "_z" : 1000 } }

延伸阅读

maxon::ReadDocument
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, Result< void > >::type ReadDocument(const Url &url, const Id &id, T &object, const DataDictionary &dict=DataDictionary())
定义: io.h:35
maxon::DataSerializeInterface
定义: dataserialize.h:205
maxon::DescribeIO
Result< void > DescribeIO(const T &s, const DataSerializeInterface &dsi)
定义: datatypefunctions.h:21
Describe
#define Describe(name, memberName, type, flags)
定义: dataserialize.h:293
CONSTHASH
#define CONSTHASH(x)
Expression to calculate the hash code of a member name during compile time.
定义: dataserialize.h:194
maxon
The maxon namespace contains all declarations of the MAXON API.
定义: c4d_basedocument.h:15
DescribeHelperIf
#define DescribeHelperIf(name, memberName, type, flags, mask, value)
定义: dataserialize.h:388
maxon::String
定义: string.h:1197
MAXON_DATATYPE
#define MAXON_DATATYPE(type, id)
定义: datatype.h:309
maxon::OK
return OK
定义: apibase.h:2532
maxon::DESCRIBEFLAGS::NONE
static const ValueType NONE
Default.
定义: dataserialize.h:136
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
定义: apibase.h:177
PrepareDescribe
#define PrepareDescribe(streamClass, className)
定义: dataserialize.h:267
maxon::Id
定义: apibaseid.h:250
iferr_return
#define iferr_return
定义: resultbase.h:1434
maxon::OPENSTREAMFLAGS::NONE
@ NONE
No flags set.
maxon::DESCRIBEFLAGS::ACTION_BEFORE_WRITE
static const ValueType ACTION_BEFORE_WRITE
If set there will be a call to the helper class WriteAction member function before an element is writ...
定义: dataserialize.h:142
maxon::BaseArray
定义: basearray.h:366
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
定义: debugdiagnostics.h:166
maxon::Url
定义: url.h:819
maxon::FINALIZEHASH
static const UInt FINALIZEHASH
定义: dataserialize.h:172
DescribeHelper
#define DescribeHelper(name, memberName, type, flags)
定义: dataserialize.h:344
maxon::Result< void >
OK
OK
Ok.
定义: ge_prepass.h:2
maxon::BaseArray::GetCount
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
定义: basearray.h:527
maxon::IOFORMAT::JSON
@ JSON
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
定义: apibase.h:184
iferr_scope
#define iferr_scope
定义: resultbase.h:1343
maxon::PREPAREHELPERFLAGS::INITIALIZE_WRITE
@ INITIALIZE_WRITE
The helper's WriteAction will get a call with INITIALIZEHASH before the class has been written.
DescribeEndIf
#define DescribeEndIf()
定义: dataserialize.h:429
DescribeElse
#define DescribeElse()
定义: dataserialize.h:410
maxon::PREPAREHELPERFLAGS::FINALIZE_READ
@ FINALIZE_READ
The helper's ReadAction will get a call with FINALIZEHASH after the class has been read.
maxon::WriteDocument
Result< void > WriteDocument(const Url &url, OPENSTREAMFLAGS flags, const Id &id, const T &object, IOFORMAT format=IOFORMAT::DEFAULT, const DataDictionary &dict=DataDictionary())
定义: io.h:67
PrepareHelper
#define PrepareHelper(helperName, flags)
定义: dataserialize.h:397
maxon::UInt
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
定义: apibase.h:185
maxon::INITIALIZEHASH
static const UInt INITIALIZEHASH
定义: dataserialize.h:171
maxon::DESCRIBEFLAGS::ACTION_AFTER_READ
static const ValueType ACTION_AFTER_READ
If set there will be a call to the helper class ReadAction member function after an element is read.
定义: dataserialize.h:143
DebugAssert
#define DebugAssert(condition,...)
定义: debugdiagnostics.h:245
maxon::PREPAREHELPERFLAGS::NONE
@ NONE

Copyright  © 2014-2025 乐数软件    

工业和信息化部: 粤ICP备14079481号-1