CustomDataTypeClass Class Referenceabstract

#include <c4d_customdatatype.h>

Inheritance diagram for CustomDataTypeClass:

Detailed Description

A data class for creating custom data types.
These can be used in descriptions and container just like built-in data types. Use RegisterCustomDataTypePlugin() to register a custom data type plugin.

Public Member Functions

 CustomDataTypeClass ()
 
virtual Int32 GetId ()=0
 
virtual Int32 GetDataID ()
 
virtual Int32 GetValueID ()
 
virtual CustomDataTypeAllocData ()=0
 
virtual void FreeData (CustomDataType *data)=0
 
virtual Bool CopyData (const CustomDataType *src, CustomDataType *dest, AliasTrans *aliastrans)=0
 
virtual Int32 Compare (const CustomDataType *d1, const CustomDataType *d2)=0
 
virtual Bool WriteData (const CustomDataType *d, HyperFile *hf)=0
 
virtual Bool ReadData (CustomDataType *d, HyperFile *hf, Int32 level)=0
 
virtual const CharGetResourceSym ()=0
 
virtual CustomPropertyGetProperties ()
 
virtual void GetDefaultProperties (BaseContainer &data)
 
virtual Int32 GetConversionsFrom (Int32 *&table)
 
virtual GvError ConvertFromGv (Int32 src_type, const void *const src, Int32 cpu_id, CustomDataType *dst)
 
virtual Int32 GetConversionsTo (Int32 *&table)
 
virtual GvError ConvertToGv (Int32 dst_type, const CustomDataType *src, void *dst, Int32 cpu_id)
 
virtual GvError ConvertToGeData (Int32 dst_type, const CustomDataType *src, GeData &dst)
 
virtual GvValueFlags GetCalculationFlags ()
 
virtual GvError Calculate (Int32 calculation, const CustomDataType *src1, const CustomDataType *src2, CustomDataType *dst, Float parm1)
 
virtual GV_VALUE_HANDLERGetGvValueHandler ()
 
virtual Bool ConvertGeDataToGv (const GeData &src, void *dst, Int32 cpu_id)
 
virtual Bool ConvertGvToGeData (const void *const src, Int32 cpu_id, GeData &dst)
 
virtual Bool GetDescription ()
 
virtual Bool _GetDescription (const CustomDataType *data, Description &res, DESCFLAGS_DESC &flags, const BaseContainer &parentdescription, DescID *singledescid)
 
virtual Bool GetParameter (const CustomDataType *data, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags)
 
virtual Bool SetDParameter (CustomDataType *data, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)
 
virtual Bool GetEnabling (const CustomDataType *data, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE &flags, const BaseContainer *itemdesc)
 
virtual Bool InterpolateKeys (GeData &res, const GeData &t_data1, const GeData &t_data2, Float mix, Int32 flags)
 
virtual void CheckData (const BaseContainer &bc, GeData &data)
 
- Public Member Functions inherited from BaseData
 BaseData ()
 
virtual ~BaseData (void)
 
void Destructor (void)
 

Private Attributes

Int32 defaultconversiontype
 
GV_VALUE_HANDLERvaluehandler
 

Constructor & Destructor Documentation

§ CustomDataTypeClass()

Default constructor.

Since
R17.032

Member Function Documentation

§ GetId()

virtual Int32 GetId ( )
pure virtual

Called to get the plugin ID of the custom data type.

Returns
A unique plugin ID. Must be obtained from http://www.plugincafe.com

§ GetDataID()

virtual Int32 GetDataID ( )
virtual

Called to get the plugin ID used for the custom data type.

Note
Normally it is not needed to override this. By default it returns GetId().
Returns
A unique plugin ID. Must be obtained from http://www.plugincafe.com

§ GetValueID()

virtual Int32 GetValueID ( )
virtual

Called to get the plugin ID used for Graph View values.

Returns
A unique plugin ID. Must be obtained from http://www.plugincafe.com

§ AllocData()

virtual CustomDataType* AllocData ( )
pure virtual

Called to allocate an instance of the internal data type class and return it.

Returns
A custom data type instance.

§ FreeData()

virtual void FreeData ( CustomDataType data)
pure virtual

Called to free an instance of the custom data type.

Parameters
[in,out]dataThe custom data type instance to free.

§ CopyData()

virtual Bool CopyData ( const CustomDataType src,
CustomDataType dest,
AliasTrans aliastrans 
)
pure virtual

Called to copy an instance of the custom data type. Copy the data from src to dest.

Parameters
[in]srcThe source custom data type.
[out]destThe destination custom data type.
[in]aliastransAn alias translator for the operation. Can be nullptr. The caller owns the pointed alias translator.
Returns
true if the custom data type was copied, otherwise false.

§ Compare()

virtual Int32 Compare ( const CustomDataType d1,
const CustomDataType d2 
)
pure virtual

Called to compare a pair of custom data types.

Parameters
[in]d1The first data.
[in]d2The second data.
Returns
The result of the comparison:
if (d1 == d2) return 0;
if (d1 < d2) return -1;
if (d1 > d2) return 1;

§ WriteData()

virtual Bool WriteData ( const CustomDataType d,
HyperFile hf 
)
pure virtual

Called to write the custom data type to a file.

Parameters
[in]dThe custom data type instance to write. Cinema 4D owns the pointed data.
[in]hfThe hyper file to write the custom data type to. Cinema 4D owns the pointed hyper file.
Returns
true if the custom data type was written successfully, otherwise false.

§ ReadData()

virtual Bool ReadData ( CustomDataType d,
HyperFile hf,
Int32  level 
)
pure virtual

Called to read the custom data type from a file.

Parameters
[in,out]dThe custom data type instance to read. Cinema 4D owns the pointed data.
[in]hfThe hyper file to read the custom data type from. Cinema 4D owns the pointed hyper file.
[in]levelThe plugin level is similar to a version number. The default level is 0.
Increase this for new revisions of a plugin to allow for forward and backward compatibility.

As an example you may have updated a plugin. If you now need to write additional information for new settings or changed types for old settings increase the level.
During loading either a 0 is passed (if the file was written by the old plugin) or 1 (if the file was written by the new plugin). This allows to easily write/read new values.
For forward and backward compatibility to work any existing read order from a given level must not be changed. Cinema 4D skips any new settings automatically if they have not been read.
Returns
true if the custom data type was read successfully, otherwise false.

§ GetResourceSym()

virtual const Char* GetResourceSym ( )
pure virtual

Called to get the symbol to use in resource files, for example "GRADIENT".

Note
Only 7-bit ASCII characters are allowed, hence the Char type.
Returns
A pointer to a global const Char* string with the resource symbol.

§ GetProperties()

virtual CustomProperty* GetProperties ( )
virtual

Called to get the properties that the custom data type accepts in resource files.

See also
CustomProperty.
Returns
A pointer to a global array of CustomProperty elements, ended with a CUSTOMTYPE_END property:
CustomProperty bitmapbuttonprops[] =
{
{ CUSTOMTYPE_END, 0, nullptr }
};

§ GetDefaultProperties()

virtual void GetDefaultProperties ( BaseContainer data)
virtual

Called to provide default properties for the custom data type.
These properties will be used if the user does not specify anything else.
It is common to add DESC_ANIMATE and DESC_CUSTOMGUI to the default properties:

Parameters
[in]dataThe container to fill with the default properties.

§ GetConversionsFrom()

virtual Int32 GetConversionsFrom ( Int32 *&  table)
virtual

Called to retrieve a pointer to a global array representing the data types that the custom data type can be converted from.

Note
Include the custom data type ID, since it is a possible conversion.
Here is an example:
static Int32 MyDataTypeConversionsFrom[] =
{
MYDATATYPE_ID,
};
Int32 MyDataTypeClass::GetConversionsFrom(Int32*& table)
{
table = MyDataTypeConversionsFrom;
return CUSTOMGUIARRAY_SIZE(MyDataTypeConversionsFrom);
}
Parameters
[out]tableSet this to point to the custom data type conversion from table.
Returns
The size of the assigned conversion from table.
Use CUSTOMGUIARRAY_SIZE for convenience. See example above.

§ ConvertFromGv()

virtual GvError ConvertFromGv ( Int32  src_type,
const void *const  src,
Int32  cpu_id,
CustomDataType dst 
)
virtual

Converts the Graph View data given by src_type and src[cpu_id] to the custom data type in dst.

Parameters
[in]src_typeThe source type. One of the IDs given by GetConversionsFrom().
[in]srcThe source data array. Depends on src_type. Cinema 4D owns the pointed array.
[in]cpu_idThe CPU index, i.e. the position in the src array.
[out]dstThe destination custom data type. Points to an instance of the internal data type. Write the converted data to this object. Cinema 4D owns the pointed data.
Returns
The conversion result: GvError

§ GetConversionsTo()

virtual Int32 GetConversionsTo ( Int32 *&  table)
virtual

Called to retrieve a pointer to a global array representing the data types that the custom data type can be converted to.

Note
It is not need to include the custom data type ID.

Here is an example:

Int32 MyDataTypeConversionsTo[] =
{
};
Int32 MyDataTypeClass::GetConversionsTo(Int32 *&table)
{
table = MyDataTypeConversionsTo;
return CUSTOMGUIARRAY_SIZE(MyDataTypeConversionsTo);
}
Parameters
[out]tableSet this to point to the custom data type conversion to table.
Returns
The size of the assigned conversion to table.
Use CUSTOMGUIARRAY_SIZE for convenience. See example above.

§ ConvertToGv()

virtual GvError ConvertToGv ( Int32  dst_type,
const CustomDataType src,
void *  dst,
Int32  cpu_id 
)
virtual

Called to convert the custom data type in src to the Graph View data given by dst_type and dst[cpu_id].

Parameters
[in]dst_typeThe destination type. One of the IDs given by GetConversionsTo().
[in]srcThe source custom data type. Points to an instance of the internal data type. Cinema 4D owns the pointed data.
[out]dstThe destination data array. Depends on dst_type. Write the converted data to this object. Cinema 4D owns the pointed array.
[in]cpu_idThe CPU index, i.e. the position in the dst array.
Returns
The conversion result: GvError

§ ConvertToGeData()

virtual GvError ConvertToGeData ( Int32  dst_type,
const CustomDataType src,
GeData dst 
)
virtual

Called to convert the custom data type in src to GeData dst.

Parameters
[in]dst_typeThe destination type. One of the IDs given by GetConversionsTo().
[in]srcThe source custom data type. Points to an instance of the internal data type. Cinema 4D owns the pointed data.
[out]dstThe destination data. Depends on dst_type. Write the converted data to this object. Cinema 4D owns the pointed data.
Returns
The conversion result: GvError

§ GetCalculationFlags()

virtual GvValueFlags GetCalculationFlags ( )
virtual

Called to retrieve the valid calculations for the custom data type.

Note
Used for calls to Calculate().
Returns
A combination of the following: GvValueFlags

§ Calculate()

virtual GvError Calculate ( Int32  calculation,
const CustomDataType src1,
const CustomDataType src2,
CustomDataType dst,
Float  parm1 
)
virtual

Called to carry out a calculation.

Parameters
[in]calculationThe calculation: GvValueFlags
[in]src1The first source custom data type. Depends on calculation. Cinema 4D owns the pointed data.
[in]src2The second source custom data type. Depends on calculation. Cinema 4D owns the pointed data.
[out]dstThe destination custom data type. Depends on calculation. Cinema 4D owns the pointed data.
[in]parm1A Float parameter. Depends on calculation.
Returns
The calculation result: GvError

§ GetGvValueHandler()

virtual GV_VALUE_HANDLER* GetGvValueHandler ( )
virtual

Called to retrieve the internal GV_VALUE_HANDLER struct for the custom data type.

Warning
It is normally never needed to override this method.
Returns
The internal GV_VALUE_HANDLER struct.

§ ConvertGeDataToGv()

virtual Bool ConvertGeDataToGv ( const GeData src,
void *  dst,
Int32  cpu_id 
)
virtual

Called to convert the data in src to the Graph View data given by dst[cpu_id].

Warning
It is normally never needed to override this method.
Parameters
[in]srcThe source data. Cinema 4D owns the pointed data.
[out]dstThe destination data array. Cinema 4D owns the pointed array.
[in]cpu_idThe CPU index, i.e. the position in the dst array.
Returns
true if the conversion was successful, otherwise false.

§ ConvertGvToGeData()

virtual Bool ConvertGvToGeData ( const void *const  src,
Int32  cpu_id,
GeData dst 
)
virtual

Called to convert the internal data in src as an array referenced by cpu_id to a GeData in dst.

Warning
It is normally never needed to override this method.
Parameters
[in]srcThe source data array. Cinema 4D owns the pointed array.
[in]cpu_idThe CPU index, i.e. the position in the src array.
[out]dstThe destination data. Cinema 4D owns the pointed data.
Returns
true if the conversion was successful, otherwise false.

§ GetDescription()

virtual Bool GetDescription ( )
virtual

Dummy virtual method to get the virtual warning.

Returns
Always false.

§ _GetDescription()

virtual Bool _GetDescription ( const CustomDataType data,
Description res,
DESCFLAGS_DESC flags,
const BaseContainer parentdescription,
DescID singledescid 
)
virtual

Called to add sub-parameters to the description for the custom data type.
Modify the passed description res object as needed, set the appropriate flags and then make sure to include a call to the parent at the end:

return SUPER::GetDescription(data, description, flags, parentdescription);
Parameters
[in]dataThe custom data type to get the description for. Points to an instance of the internal data type. Cinema 4D owns the pointed data.
[out]resThe description to add the parameters to.
[in,out]flagsThe flags for the description operation: DESCFLAGS_DESC
[in]parentdescriptionThe description container for the parent's description, encoded as described in Description.
[out]singledescidPrivate.
Returns
true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

§ GetParameter()

virtual Bool GetParameter ( const CustomDataType data,
const DescID id,
GeData t_data,
DESCFLAGS_GET flags 
)
virtual

Called to override the reading of parameters.
Modify the passed t_data if the right id was provided, and set the appropriate flags. Then make sure to include a call to the parent at the end:

return SUPER::GetParameter(data, id, t_data, flags);
Parameters
[in]dataThe custom data type to get the parameters for. Points to an instance of the internal data type. Cinema 4D owns the pointed data.
[in]idThe ID of the parameter.
[out]t_dataThe current data for the parameter.
[in,out]flagsThe flags for the description operation: DESCFLAGS_DESC
Returns
true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

§ SetDParameter()

virtual Bool SetDParameter ( CustomDataType data,
const DescID id,
const GeData t_data,
DESCFLAGS_SET flags 
)
virtual

Called to override the writing of parameters.
Read the passed t_data if the right id was provided, store the data, and set the appropriate flags. Then make sure to include a call to the parent at the end:

return SUPER::SetDParameter(data, id, t_data, flags);
Parameters
[in]dataThe data to set the parameter for. Points to an instance of the internal data type. Cinema 4D owns the pointed data.
[in]idThe ID of the parameter.
[out]t_dataThe data to write.
[in,out]flagsThe flags for the description operation: DESCFLAGS_DESC
Returns
true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

§ GetEnabling()

virtual Bool GetEnabling ( const CustomDataType data,
const DescID id,
const GeData t_data,
DESCFLAGS_ENABLE flags,
const BaseContainer itemdesc 
)
virtual

Called to decide which parameters should be enabled or disabled.
Read the passed t_data if the right id was provided, and return true to enable the parameter or false to disable it depending on the value. Then make sure to include a call to the parent at the end:

return SUPER::GetEnabling(data, id, t_data, flags, itemdesc);
Parameters
[in]dataThe data to enable or disable. Points to an instance of the internal data type. Cinema 4D owns the pointed data.
[in]idThe ID of the parameter.
[in]t_dataThe current data for the parameter.
[in]flagsNot used.
[in]itemdescThe description, encoded to a container as described in Description.
Returns
true if the parameter should be enabled, otherwise false. It is recommended to include a call to the parent function as last return.

§ InterpolateKeys()

virtual Bool InterpolateKeys ( GeData res,
const GeData t_data1,
const GeData t_data2,
Float  mix,
Int32  flags 
)
virtual

Override this method to animate the custom data type.
Set res to t_data1*mix + t_data2*(1-mix) in a way that makes sense for the custom data type.

Parameters
[in]resThe animated value.
[in]t_data1The first value.
[in]t_data2The second value.
[in]mixThe mixing factor.
[in]flagsNot used.
Returns
true if the data was animated, otherwise false.

§ CheckData()

virtual void CheckData ( const BaseContainer bc,
GeData data 
)
virtual

Called to let validate the values of data with the settings in bc.
Modify data accordingly so that it is valid.

Parameters
[in]bcThe settings container.
[in,out]dataThe data value to check.

Member Data Documentation

§ defaultconversiontype

Int32 defaultconversiontype
private

§ valuehandler

GV_VALUE_HANDLER* valuehandler
private