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(), GeGetCinemaInfo() and GeGetSystemInfo() 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())
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)
{
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