Common Plugin Concepts

Table of Contents

• About
• Plugin Classes
• Registration
• Basic Classes and Plugin Classes
• Further Reading

About

Custom plugin classes are added to Cinema 4D using plugin hooks. A plugin class is derived from a base class and implements its virtual functions.

Warning

MAXON API plugin classes are based on interfaces. See Interface Basics.

Plugin Classes

This is how a typical plugin class looks like:

// A simple example generator object plugin class.
 
class ExampleGenerator : public ObjectData
{
  INSTANCEOF(ExampleGenerator, ObjectData)
 
  public:
 
  static NodeData* Alloc(void) { return NewObjClear(ExampleGenerator); }
 
  virtual Bool Init(GeListNode *node)
  {
    return true;
  }
 
  virtual BaseObject* GetVirtualObjects(BaseObject* op, HierarchyHelp* hh)
  {
    return BaseObject::Alloc(Onull);
  }
 
  virtual Bool Message(GeListNode* node, Int32 type, void* data)
  {
    return SUPER::Message(node, type, data);
  }
};

• The class is derived from a base class, in this case ObjectData which in return is derived from NodeData.
• The INSTANCEOF macro defines a connection between the plugin class and the base class. Using this macro one can use the SUPER macro to call functions of the base class.
• Specific plugin functionality is defined by implementing virtual functions.
• A static "Alloc" function creates and returns a new instance of the plugin class. See also NodeData::Init() / Alloc and Free Manual.

Registration

Cinema 4D has to be informed about the new plugin class. This is typically done using a "Register" function. Examples are:

• RegisterObjectPlugin(): Registers an ObjectData plugin.
• RegisterTagPlugin(): Registers a TagData plugin.
• RegisterShaderPlugin(): Registers a ShaderData plugin.
• etc.

Such "Register" functions are typically used in a plugin's PluginStart() function. See PluginStart.

RegisterObjectPlugin(123456, "Example Generator", OBJECT_GENERATOR, ExampleGenerator::Alloc, "Oexamplegenerator", nullptr, 0);

The arguments of a "Register" function vary from type to type but usually are:

• Plugin ID: This ID must be unique and be obtained from www.plugincafe.com. For test purposes the ID range of 1000001 to 1000010 is available.
• Plugin name: To avoid hardcoded strings it is advised to load a string from a resource file using GeLoadString().
• Plugin flags: In this case OBJECT_GENERATOR which means that the registered class is a generator object.
• Function pointer: A pointer to the function that allocates a new instance of the class.
• Plugin symbol: This is used to identify the associated resource files.
• Plugin icon: In this case a nullptr is handed over for no icon. A BaseBitmap for the icon can easily be loaded with AutoBitmap.
• Plugin level: Defines a version of this plugin (handled in NodeData::Read() and NodeData::Write()).

These flags can be used in the "Register" function of all NodeData based plugin classes:

• PLUGINFLAG_HIDE: Hide the plugin in certain dialogs.
• PLUGINFLAG_SMALLNODE: Create a small node (the node will derive from GeListNode, rather than from BaseList2D).
• PLUGINFLAG_HIDEPLUGINMENU: Hide the plugin's menu entry in the "Plugins" menu.

ShaderData plugins can be placed in the "Effects" or "Surfaces" submenu, MaterialData plugins can be placed in the "Shaders" menu. To place them there the category name has to be added to the plugin name that is used with the "Register" function.

• GeGetDefaultFilename(): Retrieves the default file name for the given category.
  • DEFAULTFILENAME_SHADER_SURFACES: Surfaces.
  • DEFAULTFILENAME_SHADER_EFFECTS: Effects.
  • DEFAULTFILENAME_SHADER_VOLUME: Volume.

Basic Classes and Plugin Classes

Many plugin classes are based on NodeData. But typical Cinema 4D classes are based on C4DAtom, GeListNode and BaseList2D. The NodeData based plugin class is used as the "core" of such C4DAtom based class and implements its functionality.

The NodeData "core" can be obtained from objects and within a NodeData based plugin class it is possible to get the corresponding GeListNode.

• GeListNode::GetNodeData(): Gets the internal NodeData based plugin class.
• NodeData::Get(): Returns the corresponding GeListNode.

For convenience the corresponding GeListNode is also handed over in the virtual functions of NodeData.

The corresponding functions are:

NodeData	C4DAtom / GeListNode / BaseList2D
NodeData::Message()	C4DAtom::Message()
NodeData::GetDEnabling()	C4DAtom::GetEnabling()
NodeData::GetDDescription()	C4DAtom::GetDescription()
NodeData::SetDParameter()	C4DAtom::SetParameter()
NodeData::GetDParameter()	C4DAtom::GetParameter()
NodeData::Read()	C4DAtom::Read()
NodeData::Write()	C4DAtom::Write()
NodeData::CopyTo()	C4DAtom::CopyTo()
NodeData::IsInstanceOf()	C4DAtom::IsInstanceOf()
NodeData::TranslateDescID()	C4DAtom::TranslateDescID()
NodeData::GetDocument()	GeListNode::GetDocument()
NodeData::GetBranchInfo()	GeListNode::GetBranchInfo()
NodeData::IsDocumentRelated()	GeListNode::IsDocumentRelated()
NodeData::GetBubbleHelp()	BaseList2D::GetBubbleHelp()

Note

While most elements of the classic Cinema 4D API are build with the API and return a NodeData based class, some elements are not based on NodeData (like GUI elements).

Further Reading

• General Plugin Functionality Overview
• Plugin Messages