Plugin Functions Manual

About

Cinema 4D communicates with a loaded plugin (cdl64 or dylib file) by calling three basic functions that have to be implemented by that plugin. Typically these functions are implemented in the plugin's main.cpp file.

  • PluginStart(): This function is called when the plugin is loaded. Typically the plugin classes are registered here.
  • PluginMessage(): This function is called several times during startup, shutdown and while Cinema 4D is running.
  • PluginEnd(): This function is called when the plugin is unloaded.

Order

Several messages are sent to PluginMessage(). The order in which these messages are sent and the order in which the functions are called is the following:

Startup:

Events during runtime:

  • Message C4DPL_DEVICECHANGE is sent when a device was added to or removed from the machine.

Shutdown:

For the full list of messages see C4DPL_MESSAGES.

PluginStart

PluginStart() will be called after Cinema 4D loaded the plugin. Typically custom plugin classes are installed here using the corresponding "Register" function. PluginStart() may also be the right place to start a background thread or to check the validity of a keyfile.

{
// register plugins
const Bool success = RegisterObjectPlugin(123456, "Example Generator", OBJECT_GENERATOR, ExampleGenerator::Alloc, "Oexamplegenerator", nullptr, 0);
if (!success)
return false;
return true;
}
Note
One can check with GeGetVersionType() and GeGetCinemaInfo() the version of the host Cinema 4D application to make sure plugins are only loaded in a suitable environment.
Currently the return value of PluginStart() is not evaluated.

PluginMessage

PluginMessage() receives various messages during startup, shutdown and while Cinema 4D is running.

It is possible to send a custom message to PluginMessage() of all loaded plugins with:

Bool PluginMessage(Int32 id, void* data)
{
switch (id)
{
//...
}
return false;
}

Priority

The PluginStart() and PluginEnd() functions of all plugins are called one after another. The plugin priority defines the order in which these functions are called. This is useful to make sure that a given plugin is called before or after a certain other plugin. For most plugins this is typically not needed.

The priority is set using this macro:

The priorities are:

Note
Higher priorities are initialized first.
C4DMSG_PRIORITY is not relevant for Python plugins.

Initialize Resources

If a plugin uses any resource files in its "res" folder, these resources have to be loaded when Cinema 4D starts. This is done using GeResource::Init().

As this is one of the earliest message, this is the best time to register custom data types and SNHook plugins. This message is not sent to Python plugins.

// This example loads the plugin's resources when
// C4DPL_INIT_SYS is sent to PluginMessage().
{
// don't start plugin without resource
if (g_resource.Init() == false)
return false;
return true;
}

After the C4DPL_INIT_SYS message, PluginStart() will be called.

Start

During startup the following messages are sent:

// This example inserts a cube object into the active scene after Cinema has started.
{
if (doc != nullptr)
{
if (cube == nullptr)
return false;
doc->InsertObject(cube, nullptr, nullptr);
}
return true;
break;
}

Menu Layout

Before Cinema 4D finishes its start (C4DPL_PROGRAM_STARTED) it is possible to modify its menus to add new menu entries.

// This example adds a new "Custom Menu" entry to Cinema's menu bar.
{
BaseContainer* const mainMenu = GetMenuResource("M_EDITOR"_s);
if (mainMenu == nullptr)
return false;
// create a custom menu entry
menu.InsData(MENURESOURCE_SUBTITLE, "Custom Menu");
// adds the command to create a cube to the custom menu
const String commandString = "PLUGIN_CMD_" + String::IntToString(Ocube);
menu.InsData(MENURESOURCE_COMMAND, commandString);
// add new menu entry
mainMenu->InsData(MENURESOURCE_SUBMENU, menu);
return true;
break;
}

Command Line Arguments

Warning
Command line arguments can be defined and accessed with MAXON API configuration variables. See Configuration Variables.

The command line arguments used to start Cinema 4D can be parsed after the application has started.

The data of the message is C4DPL_CommandLineArgs:

// This example catches the command line argument "-custom"
// It must look like this: "-custom someString"
{
const C4DPL_CommandLineArgs* const args = static_cast<C4DPL_CommandLineArgs*>(data);
if (args == nullptr)
return false;
// loop through all command line arguments
for (Int32 i = 0; i < args->argc; i++)
{
// check if argument is set
if (!args->argv[i])
continue;
// check if this is the "custom" argument
if (strcmp(args->argv[i], "-custom") == 0)
{
// set to nullptr so it won't confuse other modules
args->argv[i] = nullptr;
// get the argument that is the next command line element
i++;
const String argument = String(args->argv[i]);
// print result
ApplicationOutput("Argument: " + argument);
// set to nullptr so it won't confuse other modules
args->argv[i] = nullptr;
}
}
return true;
break;
}

Device Change

When a device is added to or removed from the machine, a plugin message is sent.

The data of the message is C4DPL_DeviceChange:

// This example detects when a new device is added.
{
const C4DPL_DeviceChange* const dc = static_cast<C4DPL_DeviceChange*>(data);
if (dc == nullptr)
return false;
const String* const name = dc->name;
if (name == nullptr)
return false;
// check if name is valid
if (name->GetLength() > 0)
{
// check if the device was removed or added
if (dc->eject)
ApplicationOutput("Device " + *name + " was removed");
else
ApplicationOutput("Device " + *name + " was added");
}
return true;
break;
}
Note
This message is triggered twice per event.

Shutdown

The following messages are sent during Cinema 4D's shutdown.

  • C4DPL_ENDPROGRAM: Cinema 4D is about to close.
  • C4DPL_ENDACTIVITY is sent before PluginEnd() of any plugin is called. This allows to free any resources and close threads. At this point, all classes and plugins still exist. For example dialogs, BaseContainers, threads and complex data types should be deleted here. Preferences should be stored and all processes be terminated.
  • C4DPL_SHUTDOWNTHREADS: Sent to all plugins before the threading system of Cinema 4D is shut down. Afterwards no threads should be started.

PluginEnd

PluginEnd() is called before a plugin is unloaded and is the last opportunity to free resources. Here low level cleanup should be done e.g. for Strings and Filenames. Also imported DLLs should be unloaded here.

void PluginEnd(void)
{
// Free resources
}

Further Reading

MENURESOURCE_COMMAND
@ MENURESOURCE_COMMAND
Command, e.g. "IDM_NEU" or "PLUGIN_CMD_1000472".
Definition: gui.h:232
GetActiveDocument
BaseDocument * GetActiveDocument(void)
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
GeResource::Init
Bool Init()
C4DPL_CommandLineArgs::argc
Int32 argc
Number of arguments in argv.
Definition: c4d_plugin.h:78
BaseObject
Definition: c4d_baseobject.h:220
C4DPL_DEVICECHANGE
#define C4DPL_DEVICECHANGE
Sent when a device has changed. The data pointer should be cast to C4DPL_DeviceChange.
Definition: c4d_plugin.h:100
MENURESOURCE_SUBTITLE
@ MENURESOURCE_SUBTITLE
The title of the menu item or sub-menu.
Definition: gui.h:233
C4DPL_BUILDMENU
#define C4DPL_BUILDMENU
Use GetMenuResource() etc. to add menus here if necessary. See main.cpp in the SDK examples.
Definition: c4d_plugin.h:35
C4DMSG_PRIORITY
#define C4DMSG_PRIORITY
Called to query plugins about their loading time priority. Answer with SetPluginPriority(),...
Definition: c4d_plugin.h:34
C4DPL_COMMANDLINEARGS
#define C4DPL_COMMANDLINEARGS
Sent to let plugins parse the command line arguments used when starting Cinema&#160;4D....
Definition: c4d_plugin.h:64
GetMenuResource
BaseContainer * GetMenuResource(const maxon::String &menuname)
MENURESOURCE_SUBMENU
@ MENURESOURCE_SUBMENU
BaseContainer Sub-menu:
Definition: gui.h:230
Ocube
#define Ocube
Cube.
Definition: ge_prepass.h:1037
C4DPL_CommandLineArgs
Definition: c4d_plugin.h:76
C4DPL_INIT_PRIORITY_XTENSIONS
#define C4DPL_INIT_PRIORITY_XTENSIONS
Base priority for extensions.
Definition: c4d_plugin.h:42
String
Definition: c4d_string.h:35
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:492
SetPluginPriority
#define SetPluginPriority(data, i)
Definition: c4d_plugin.h:194
C4DPL_DeviceChange::eject
Bool eject
true if the device was ejected, otherwise false.
Definition: c4d_plugin.h:105
C4DPL_DeviceChange
Definition: c4d_plugin.h:102
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:45
C4DPL_CommandLineArgs::argv
char ** argv
Argument array.
Definition: c4d_plugin.h:79
C4DPL_DeviceChange::name
class String * name
The name of the device.
Definition: c4d_plugin.h:104
RegisterObjectPlugin
Bool RegisterObjectPlugin(Int32 id, const maxon::String &str, Int32 info, DataAllocator *g, const maxon::String &description, BaseBitmap *icon, Int32 disklevel)
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:209
BaseObject::Alloc
static BaseObject * Alloc(Int32 type)
BaseContainer::InsData
GeData * InsData(Int32 id, const GeData &n)
Definition: c4d_basecontainer.h:234
PluginMessage
Bool PluginMessage(Int32 id, void *data)
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:40
OBJECT_GENERATOR
#define OBJECT_GENERATOR
Generator object. Produces a polygonal or spline representation on its own. (e.g. primitive cube)
Definition: ge_prepass.h:887
g_resource
GeResource g_resource
Global resources for Cinema&#160;4D.
PluginEnd
void PluginEnd(void)
C4DPL_PROGRAM_STARTED
#define C4DPL_PROGRAM_STARTED
Sent when the application has been started.
Definition: c4d_plugin.h:114
C4DPL_INIT_SYS
#define C4DPL_INIT_SYS
Initialize system.
Definition: c4d_plugin.h:24
PluginStart
Bool PluginStart(void)
BaseDocument
Definition: c4d_basedocument.h:479
BaseContainer
Definition: c4d_basecontainer.h:42