Plugin Messages

Table of Contents

• About
• Order
• PluginStart
• PluginMessage
  • Priority
  • Initialize Resources
  • Start
  • Menu Layout
  • Command Line Arguments
  • Device Change
  • Shutdown
• PluginEnd
• Further Reading

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:

• Message C4DMSG_PRIORITY is sent to let the plugin define its priority.
• Message C4DPL_INIT_SYS is sent to let the plugin initiate its resources.
• PluginStart() is called.
• Message C4DPL_STARTACTIVITY is sent after PluginStart() of all plugins was called.
• Message C4DPL_BUILDMENU is sent to modify Cinema 4D's menus.
• Message C4DPL_PROGRAM_STARTED is sent after the program started and is ready for work.
• Message C4DPL_COMMANDLINEARGS is sent to handle command line arguments.
• At this point a document specified on command line gets loaded.

Events during runtime:

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

Shutdown:

• Message C4DPL_ENDPROGRAM is sent when Cinema 4D is about to close.
• Message C4DPL_ENDACTIVITY is sent before PluginEnd() of each plugin is called.
• PluginEnd() is called.

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.

Bool PluginStart(void)
{
  // 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:

• GePluginMessage(): Sends a plugin message to other plugins.

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.

• C4DMSG_PRIORITY is send to get the priority of the receiving plugin.

The priority is set using this macro:

• SetPluginPriority: Sets the priority for the plugin.

case C4DMSG_PRIORITY:
{
  SetPluginPriority(data, C4DPL_INIT_PRIORITY_XTENSIONS + 1);
  return true;
}

The priorities are:

• C4DPL_INIT_PRIORITY_XTENSIONS: Base priority for extensions.
• C4DPL_INIT_PRIORITY_OBJECTS: Base priority for objects.
• C4DPL_INIT_PRIORITY_MODELING: Base priority for modeling.
• C4DPL_INIT_PRIORITY_SHADER: Base priority for shader modules.
• C4DPL_INIT_PRIORITY_ADVANCEDRENDER: Base priority for the Advanced Render module.
• C4DPL_INIT_PRIORITY_MOCCA: Base priority for MOCCA.
• C4DPL_INIT_PRIORITY_NEWMAN: Base priority for Cinema 4D managers.
• C4DPL_INIT_PRIORITY_SLA: Base priority for SLA.
• C4DPL_INIT_PRIORITY_MODULES: Base priority for modules.
• C4DPL_INIT_PRIORITY_PLUGINS: Base priority for plugins.

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().

• C4DPL_INIT_SYS is sent to initialize the system.

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().
 
    case C4DPL_INIT_SYS:
    {
      // 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:

• C4DPL_STARTACTIVITY is sent to all plugins after PluginStart() of all plugins was called. Here code can be executed that relies on all other plugins to be loaded.
• C4DPL_PROGRAM_STARTED is sent when the application has been started and is ready.

    // This example inserts a cube object into the active scene after Cinema has started.
 
    case (C4DPL_PROGRAM_STARTED):
    {
      BaseDocument* const doc = GetActiveDocument();
      if (doc != nullptr)
      {
        BaseObject* const cube = BaseObject::Alloc(Ocube);
        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.

• C4DPL_BUILDMENU is sent when the menus are built during startup.

    // This example adds a new "Custom Menu" entry to Cinema's menu bar.
 
    case (C4DPL_BUILDMENU):
    {
      BaseContainer* const mainMenu = GetMenuResource("M_EDITOR"_s);
      if (mainMenu == nullptr)
        return false;
 
      // create a custom menu entry
      BaseContainer menu;
      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.

• C4DPL_COMMANDLINEARGS is sent to let plugins parse the command line arguments.

The data of the message is C4DPL_CommandLineArgs:

• C4DPL_CommandLineArgs::argc: Number of arguments in argv.
• C4DPL_CommandLineArgs::argv: Argument array.
• C4DPL_CommandLineArgs::argc_w: Number of arguments in argv_w (Unicode encoding, Windows only).
• C4DPL_CommandLineArgs::argv_w: Argument array (Unicode encoding, Windows only).
• C4DPL_CommandLineArgs::orig: The complete argument string.
• C4DPL_CommandLineArgs::orig_w: The complete Unicode argument string (Unicode encoding, Windows only).

    // This example catches the command line argument "-custom"
    // It must look like this: "-custom someString"
 
    case (C4DPL_COMMANDLINEARGS):
    {
      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.

• C4DPL_DEVICECHANGE is sent when a device has changed.

The data of the message is C4DPL_DeviceChange:

• C4DPL_DeviceChange::name: The name of the device.
• C4DPL_DeviceChange::eject: True if the device was ejected, otherwise false.

    // This example detects when a new device is added.
 
    case (C4DPL_DEVICECHANGE):
    {
      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

• General Plugin Functionality Overview
• Common Plugin Concepts