creating plugins for c4d: section 1 - compiling the SDK examples

using Visual Studio 2008 to create C4D plugins

If you have some knowledge of C++, you might want to develop plugins for C4D using the Maxon SDK. If you aren't happy with C++ you can still produce plugins using C4D's inbuilt COFFEE scripting language. Having done that, I wanted to change to using C++ because there are some limitations on COFFEE which mean that, for example, tool plugins can't be developed.

However, once you start looking at the SDK, you realise that while it's quite a good reference, there's very little on how to start writing a plugin - and in particular on how to set up the compiler to produce the finished plugin. After some work on this, and a lot of reading of the SDK and compiler documentation, I was able to produce a working plugin. I wrote these pages so I wouldn't forget the necessary steps in future and thought that they might be helpful, warts and all, to other aspiring plugin developers. So here they are. As far as I know they are accurate, in that at least I get a working plugin on completion... but if you find errors, please let me know and I will correct them. Feel free to laugh at my mistakes if you're an experienced developer!

Visual Studio 2008

One caveat before we start: I am using a 64-bit Windows PC and Microsoft Visual Studio 2008 as the compiler. These pages will be of most use if you are using a similar system. You can use VS 2005 if you have that; in fact that seems to be the current (as of August 2009) preferred version as far as Maxon is concerned, and you may actually find it a little easier to use than VS 2008 due to compiler changes between versions. There won't be much difference though other than in some compiler options and how they are set in the VS IDE.

If on the other hand you are developing on a Mac then these pages will still be of some use to you, but you will have to find the equivalent compiler options for Xcode or whatever development system you are using; not all will be relevant to Macs and undoubtedly Macs will have issues not relevant to a PC. If you use a Mac, see this addendum page for some hints about Xcode and the differences between C4D versions on the Mac.

requirements

So, what do you need to get started? You require:

Once you have installed VS 2008 successfully, the first thing to do is compile the SDK examples. These are located in the Cinema 4D installation directory, at \plugins\cinema4dsdk. Once you compile it, you get a huge plugin with a lot of different examples that you can dissect and see how they work. It's also a great test to make sure that you are able to compile plugins at all before starting on your own.

compiling the SDK examples: 1

Maxon implies that compiling the SDK examples is a simple matter of building the solution. Well, it may be for some people, and perhaps it is if you are using VS 2005, but there are some gotchas and problems if you use VS 2008. I'm assuming from here on that you are using VS 2008, but if you use VS 2005, you may not need to do anything other than just build the solution.

Firstly, load the SDK example solution into VS. The file you want is the solution file, which is located at plugins\cinema4dsdk\cinema4dsdk.sln. Your first issue hits you right away, because VS will tell you that this is in an older version and needs to be converted to the 2008 version:

Conversion wizard

Go ahead and let VS do the conversion. Visual Studio will chunter away for a while, and then produce a report (which you can find at plugins\cinema4dsdk\UpgradeLog.xml if you ever need to look at it again). This report will probably tell you that 'some errors' occurred during conversion:

Conversion errors

If you look at the conversion log, one of these problems relates to user access control (UAC) under Vista, and if you have turned UAC off as most Vista users do, these shouldn't bother you any more. The other one looks innocuous. It says:

WebDeployPath warning

This one will bite you shortly. For now, note that the solution contains two projects, called _api and cinema4dsdk. The actual plugin code is in cinema4dsdk. Project _api contains the code to compile the API object files; the linker will link the compiled code in cinema4dsdk with the API library so that the plugin can access the Cinema 4D API. Building the solution will compile both projects and produce the final linked version. There is a LOT of source code in these two projects!

compiling the SDK examples: 2

Once the conversion has taken place, go ahead and build the solution. What you are doing is compiling the plugin and the API library, linking them to produce a plugin with the name cinema4dsdk.cdl. Initially, if you haven't changed anything, you are building the 32 bit debug version, but that's fine for the present.

The first thing that happens is that the build fails with an error - in fact, a lot of errors, but almost all of them relate to a failure to find an include file, c4d.h, in most (all?) of the source files in the project cinema4dsdk. Take a look at one of them, such as the file main.cpp, and it does indeed include file c4d.h, but clearly the compiler can't find it. If you look at the compiler options (right-click the cinema4dsdk project, choose Properties, and a big dialog box opens) and go to the C/C++ tab, General page, there is a slot marked 'Additional include directories', which is empty:

Include files settings

Well, that must be why the include file can't be found - there's no path to it in the compiler options. The obvious answer is to add one, so you search the Cinema 4D folder and eventually find file c4d.h in the folder \resource\_api. Add this folder to the compiler option (actually, you need to enter ..\..\resource\_api into the compiler options because that's the relative path from the solution file) and build the solution again.

Well... that didn't work either. Now it can't find a different include file! What's going on? If you look at the file c4d.h, all it really does is load a whole bunch of other include files, so the problem is that they also aren't being found. Now this solution is supposed just to compile, so clearly something happened during the conversion process that has caused a problem. The only thing that happened (other than the UAC warnings) was that the web deployment build tool was removed. Maybe that's the issue? If you look at the compiler errors again, you'll see a warning as well as all those errors, saying that the environment variable WebDeployPath doesn't exist.

Firstly, delete the include directory you just added, since that wasn't the answer. Go back to the compiler options and click on the slot labelled 'Additional include directories'. A button with three dots will appear:

Add include directory

Click this and a dialog box opens showing all the include directories the compiler will use. Assuming you deleted the one you added a moment ago, there won't be any in the top part of the dialog. But there's also a lower section showing include directories 'inherited from parent'. Most of these directories reference an environment variable called WebDeployPath, which we know from the compiler warning doesn't exist. If we could get rid of that, the warning would go away, but we can't edit that inherited list. Where has it come from?

The answer to this can be found in the VS 2008 documentation. In summary, a VS solution can make use of settings stored in a separate file (a property sheet) which is useful because then sets of options can easily be transferred between projects. The compiler options for the cinema4dsdk project will tell you (see the Configuration Properties\General page) that the property sheet ..\..\resource\_api_lib\DebugWin32.vsprops is used in this project. You can edit the file by hand (it's an XML file) but a better way is to do it in the Visual Studio IDE. Go to the View menu, Other Windows, and click Property Manager. This will open a new window showing all the property sheets used by the solution, and there are quite a lot (especially if running on a 64 bit system):

Property Manager

You need to look at the DebugWin32 property sheet; just double-click the file name and it will open a properties dialog identical to the project properties dialog which you've already seen. You will see that in the list of include directories there are some which use the WebDeployPath environment variable. All you need to do is click on each one in turn and use the browse button that appears to navigate to the correct directory. (I couldn't find one of these directories on my system, but deleting it from the list of include directories didn't seem to cause a problem.) Once you're done, you should no longer have any include files making use of the WebDeployPath environment variable.

Note: if you do as I just suggested, be aware that the include directories will be shown as absolute paths (e.g. as 'C:\Program Files\MAXON\CINEMA 4D R11\resource\_api' rather than as relative paths such as '..\..\resource\_api'. This won't matter at all unless you copy your entire C4D installation folder to a different drive, in which case the absolute paths will cease to be valid and you'll have to edit them again. Alternatively, you can edit these paths now to make them relative, which will work wherever C4D is installed.

Then click OK to save the property sheet and you're done. You won't need to do this again for future plugins, just include the relevant property sheets in your projects and the include directories are set.

If you build the solution now, it finally works without errors or warnings!

building the 64 bit version

Note that there are other .vsprops files in the folder _api_lib, and they refer to project options for Debug and Release versions in both 32 and 64 bit. The Property Manager will show you all those being used in the project. You don't need to modify the DebugWin64 property sheet if you are going to build the 64 bit version as well, because it includes the Win32Debug sheet (see the screenshot above). And you don't need to modify the 32 or 64 bit release version property sheets either because they in turn include the DebugWin32 property sheet, where you have already entered the list of include directories.

You can now compile the 64 bit version of the example plugin if you like - you'll need a 64 bit operating system and 64 bit C4D to test it. I am running Vista 64 and the 64 bit plugin compiled with no further modifications, although it did issue a compiler warning about a command line setting which is deprecated in VS 2008:

64 bit compiler warning

You can ignore this warning. Finally you have built the plugin, ready for distribution in Windows versions at least! If you run Cinema 4D, you'll see it in the plugins menu, with several sub-menu entries.

To build your own plugin you can copy the entire cinema4dsdk directory, rename it, delete what you don't want from the cinema4dsdk project and modify what's left. This is the recommended way, but the other way is to create your own plugin from scratch so you can see how it's done. Yes, it's more work but at the end you have a much better understanding of the process by starting with a completely empty project. So the next part of this tutorial will show how to build a simple plugin right from the ground up.

compiling the sdk on a Mac

Things are a bit different on the Mac, so I have added a separate addendum page to cover the use of Xcode in compiling the SDK examples.

Back to main tutorials page