creating plugins for c4d: section 2 - building a plugin from scratch

In the previous section of this tutorial you built the cinema4dsdk example plugin. Now you're going to build one absolutely from scratch using Visual Studio 2008 on a PC.

First, you need to create the necessary folder structure for the new plugin. We'll call this plugin 'testplugin1' so create a structure that looks like this:

Cinema 4D Rxx\plugins\testplug1

(Where Cinema 4D Rxx is R10, R11, etc.)

Note that the 'source' folder will contain the plugin source code and wouldn't be distributed with a completed plugin.

creating a new project

In Visual Studio, go to File menu->New->Project and create a new empty C++ project. Call the project TestPlug1, uncheck the box 'Create directory for solution', and set the location to the plugins directory. (Not the testplug1 folder you created, the existing folder called plugins.)

After VS creates the project, you'll have five new files in the testplug1 folder. These are the project and solution files and you don't need to do anything to these.

Once the project is created, you can open the Property Manager (View menu, Other Windows, Property Manager) and you will see that VS has added two configurations for you, for DebugWin32 and ReleaseWin32. Right-click 'Debug | Win32' and choose 'Add Existing Property Sheet...'. Navigate to the folder Cinema 4D Rxx\resource\_api_lib and choose DebugWin32.vsprops. Back in Property Manager do the same for 'Release | Win32' but this time add the property sheet ReleaseWin32.vsprops. You'll see that this sheet automatically includes the win32 debug sheet.

At this point you should add the 64 bit versions as well. Firstly, add the 64 bit configuration using the Configuration Manager. Go to the Build menu and click Configuration Manager. Click the drop-down menu labelled 'Active solution platform:' and select 'New'. Another dialog appears; under 'Type or select the new platform' click on x64. Make sure 'Copy settings from:' is set to Win32, and that the box 'Create new project platforms' is checked. Then click OK. Note that the x64 platform is now marked to be built (the box labelled 'Build' is checked). You can turn this off to build only the win32 version first, but make sure that the 'Build' box is checked for the Win32 platform. Before you close Configuration Manager, make sure that the 'Active solution platform' is set to Win32. Finally, click 'Close'.

You can see that VS has automatically added the property sheets for the Win64 builds, but the property sheets to load are not correct. In Property Manager, under Debug | x64, right-click the DebugWin32 property sheet and select Remove. Right-click Debug | x64 and select 'Add existing property sheet...'. Load the DebugWin64.vsprops file; you see that it automatically includes the DebugWin32.vsprops file, so you don't have to enter the include directories again. Do the same for the Release | x64 configuration - remove ReleaseWin32 and add ReleaseWin64.vsprops. Now you're done with the property sheets.

modifying the compiler and linker options

Before we do anything else, you need to add a C++ source file to the project. If you don't do this, you can't set any C++ compiler options. So, in the Solution Explorer, right-click the 'source' folder and choose 'Add new item'. In the dialog, select the item type as Visual C++, change to the Code tab, and select C++ file (.cpp). Set the location to the \plugins\TestPlug1\source folder, and name the file 'main.cpp'. Click OK and VS will create an empty file for you; this can be closed now since we don't need it yet.

Now right-click the project TestPlug1 in the solution explorer and select Properties. The same configuration dialog opens which you saw when editing the property sheet. Anything you set in here may override the settings in the property sheet, so be careful what you do.

Set project properties as follows:

  1. set the Configuration drop-down menu to Debug, and the platform to Win32
  2. in Configuration Properties\General, set Configuration type to Dynamic Library (.dll)
  3. in Configuration Properties\Debugging, set to debug in C4D (this is optional; if you want to do it, the SDK documentation tells you how in the page headed 'Debugging')
  4. in C/C++\code generation, set Runtime Library to Multi-threaded Debug (/MTd), NOT the default Multi-threaded Debug DLL (/MDd)
  5. in C/C++\Command Line, check that the command line includes the options /vmg and /vms (it should do as these are specified in the property sheet you added)
  6. in Linker\General, you need to make a choice regarding the Output File. You MUST change the extension from .dll to .cdl, or C4D won't recognise it as a plugin. If you otherwise leave the output file as it is, the built plugin will be stored as TestPlug1.cdl in the folder \plugins\testplug1\debug. This works fine, and C4D will find and load it, but if you ever copy the plugin file into the \plugins\testplug1 folder, which is where the plugin would normally be located, you run the risk of having two versions loaded when C4D runs - the one in the main plugin directory and the one in the debug sub-folder. To avoid this, I prefer to change the Output File to $(ProjectDir)\$(ProjectName).cdl; but you can get rid of those macros if you like and just change the output file to testplug1.cdl - the effect is the same in this instance.
  7. rather than recompile the _api project from the cinema4dsdk example plugin (because you already did that when building the example, and it's a waste of time to do it again) you're going to link to the compiled API library, so you need to tell the linker where that is. In Linker\General, set Additional Library Directories to the folder which contains the library file _api_Win32_Debug.lib (this is normally the path Cinema 4D Rxx\resource\_api_lib)
  8. in Linker\Input, you need to specify the API library file as a dependency, so add the file _api_Win32_Debug.lib to the 'Additional Dependencies' section (you already told the linker where this library can be found)
  9. in Linker\Advanced, change Randomized Base Address to Disable Image Randomization (DYNAMICBASE:NO)

That's it, you're done with the options for the debug release. Click OK to close the properties dialog.

options for the Release version

However... you now need to do the same for the release version, and some project properties are different from the debug version. Right-click the project TestPlug1 in the solution explorer and select Properties again.The steps to take are:

  1. change the Configuration drop-down to Release
  2. as step 2 above
  3. not applicable since there won't be any debug information in the built plugin
  4. set this to Multi-threaded (/MT) NOT the default Multi-threaded DLL (/MD)
  5. as step 5 above
  6. as step 6 above
  7. as step 7 above
  8. as step 8 above, except that the library will be _api_Win32_Release.lib
  9. as step 9 above

Close the properties dialog by clicking OK.

options for the 64 bit version

You now need to set the compiler and linker properties for the 64 bit debug and release versions. Right-click the project name in solution explorer and in the options dialog set configuration to debug and platform to x64. Follow the steps for the win32 debug version, except that in step 6, the output file must have the extension .cdl64, and in step 8, the library to link is _api_x64_Debug.lib. For the release version, the only changes from the win32 release are the ouput file name (extension .cdl64) and the API library, which is _api_x64_Release.lib. That completes the compiler and linker options for all four versions!

If you think about it, what you now have is a generic template for any new plugin, with all the options set. You could save a copy of the entire testplug1 folder somewhere and just copy it into the \plugins directory when you want to create a new plugin. You would need to change the solution and project names of course, and the output file name but other than that it should work for any win32 plugin you build.

So far there's nothing in the project at all. So the next thing is to add some code, and simple code to add a plugin will be in the next section.

Back to main tutorials page