Introduction

Getting Started with VS C++ 2008 Express Edition

In this tutorial you will learn how to compile the sample plugins that ship with Cinema4D using Visual Studio C++ 2008 Express Edition. You will also learn how to create your own plugin project template to use for other plugins, a simple bitmap saver plugin and also how to ensure your plugin will not clash with other plugins by obtaining a unique ID for your plugin.

For the purposes of these tutorials we will be using Windows 7 as our development environment with Cinema 4D version 11.5. You can also develop with other version of Windows including Vista and XP. Because the tutorials are based on Windows 7 there may be some extra “Warning” dialog steps mentioned that you may not encounter on other systems (mainly XP).

You can also develop using an older version of Cinema, the only difference maybe that I may inadvertently use a feature from the 11.5 SDK that is not in one of the older versions. I will try to stick to standard calls to the SDK and hopefully this will not be a problem.

These tutorials will also use the free version of Visual Studio C++ 2008 to develop the plugins.

You can also develop using Xcode under the mac. These projects will all work on the mac as well as windows, I am just using Windows as I personally prefer to develop using Visual Studio.

Install Cinema 4D

This goes without saying really, but you should have a copy of Cinema 4D installed on your computer. If you do not then you can get the free 42 day trial from the MAXON website. Just following the following URL

http://www.maxon.net/downloads/downloads/demo-version.html

Installing Visual Studio 2008 Express Edition

You will require either Visual Studio 2005, Visual Studio 2008 or Visual Studio C++ 2008 Express Edition to develop plugins for Cinema 4D. For the purposes of this tutorial I am going to assume that you are using Visual Studio C++ 2008 Express Edition for your plugin development.
Open the browser of your choice and download Visual Studio C++ 2008 Express Edition from the following URL

http://www.microsoft.com/express/download/

Just follow the normal installation. You don’t need to install Server 2008.

Getting the Cinema 4D SDK documentation

You will also need the documentation to the Cinema 4D SDK, which does not ship with the product. You can find the latest version at the following URL

http://www.maxon.net/support/for-developers/sdk-downloads.html

Download the file called “C++ SDK 11.5 (.chm)” to your computer.

Its also useful to download the latest notes from the DevKitchen, which at the time or writing was “DevKitchen2008.pdf”. This will give you some useful tips and Do’s and Don’ts that you should be aware of when writing your plugin, but we will talk more about these in later tutorials.

Compiling your first plugin

 By now you should have Visual Studio C++ 2008 Express Edition Installed (or a similar version) and the SDK documentation should also be on your computer somewhere. Next step is to check that everything is working correctly. To do this we will open up the example plugin in the SDK and ensure that it compiles.

Starting Visual Studio

First thing to do is start up visual studio. If you are developing under Vista or Windows 7 you will need to do this with Administrator Rights, since you will be opening up a project that is within the Program Files folder on your system. To do this just right click on the Visual Studio C++ 2008 Express Edition icon and choose “Run as administrator”.

Opening the sample project and converting it to VS 2008

With Visual Studio running, choose File->Open->Project/Solution. Navigate to the Program Files/MAXON/CINEMA 4D R11.5/plugins/cinema4dsdk/cinema4dsdk.sln

You may be prompted with the Visual Studio Conversion Wizard. This will convert old projects from previous versions of Visual Studio to be compatible with Visual Studio 2008. Just press Finish followed by Close to let it do its thing.

Converting the _api library project to VS 2008

When the project is loaded you may also notice that the first project in the solution, called _api, has the text “unavailable” written next to it...  “_api (unavailable) “.  This is because it also was built with a previous version of Visual Studio and also needs to be upgraded.

Before we can upgrade it we first need to make sure we can write over the old project files. To do this you must locate the folder “C:\Program Files\MAXON\CINEMA 4D R11.5\resource” on your computer. In this folder you will see a project called _api_lib. Right click on this folder and choose properties. When the properties dialog appears you should uncheck the “Read-only” attribute and press Apply, the OK to the Confirm Attribute Changes for applying to all subfolders. You may now be prompted with a “Access Denied” dialog saying you will need to provide Administrator permission, click the Continue button to carry on. Now you can press OK to close the Properties for this folder.

Now go back into Visual Studio and Right Click on the _api project and choose Reload Project. The conversion wizard will now be displayed. Again choose Finish followed by Close.

Fixing up some files for Visual Studio 2008.

You will need to hand fix one file in order to get things compiling under Visual Studio 2008.

First thing to do is you will need to close down Visual Studio.

Next navigate to the folder “C:\Program Files\MAXON\CINEMA 4D R11.5\resource\_api_lib” and open up the file “DebugWin32.vsprops” in the text editor of your choice. Now replace all occurrences of the text “$(WebDeployPath)” with “..\..\resource” (without the quotation marks of course). Save the file to disk.

Compiling the plugin

Right everything should be ready to go now. Load up Visual Studio again and load in the cinema4dsk solution file.

Now that everything has been converted and loaded successfully into VS the next thing we want to do is actually build the plugin. Make sure your project is in “Debug” mode by looking at the menu bar, on the menu bar you will see “Debug” in a little drop down menu. If it does not say “Debug” then click the drop down menu and choose “Debug” from the list.

Next from the Build menu choose “Build Solution”.

You should get a “Build: 1 succeeded” showing at the bottom of your output window. If so then congratulations you have compiled your first plugin, if not then I think you may have missed a step above and I advise you to go back over them again.

Running the plugin in debug mode

Now that the plugin is compiled lets run it, in debug mode, to make sure everything is working ok.

Choose the following menu item “Debug->Start debugging”. You will be prompted for an Executable file name to run. Use the dialog to browse to the following directory C:\Program Files\MAXON\CINEMA 4D R11.5 and select the file “Cinema 4D” (if you have specifically changed your compile setting to x64 then you will need to choose “Cinema 4D 64 Bit” instead, note that you only do this IF you changed it to x64, most of you will have left the settings as they are and will be running in win32 mode).  With your executable file name set press the OK button on the dialog to continue.

Another dialog will appear talking about “No Debugging Information”. Ignore this dialog and press YES to continue. You can also check the “Don’t show this dialog again” button.

If everything has gone according to plan you should now see Cinema 4D running on your screen.

Under the Plugins->Cinema4dsdk menu you will see a list of all the sample plugins that you just built.

Try selecting the “Liquid Painting Tool” from the menu and then with your left mouse button down start drawing around in the viewport. You should see a liquid like polygon mesh being produced.

At this point you can give yourself a pat on the back and congratulate yourself for getting everything running up till this point. Now onto the fun part... creating your own plugin.

Copy and Rename cinema4dsdk folder

Now that we know everything is installed and working correctly we now want to create our own plugin. The Easiest way to do this is to just copy the entire cinema4dsdk folder and then give it a new name like “PluginTemplate”.  

If your on Vista on Window7 you will get the familiar “Access Denied” dialog when pasting it, just press continue and ignore the dialog. From this point onwards I am going to assume that you do this everytime this warning appears. It will appear when ever you make a change inside the plugins folder, this inludes renaming the folder (which is the next step).

Rename the copied folder to “PluginTemplate”.

Delete some files

Go into the PluginTemplate folder and delete the following

• obj folder
• everything inside the res/description folder
• everything inside the res/ dialogs folder
• everything inside the res / scene folder
• everything inside the res/strings/description folder
• everything inside the res/strings/dialogs folder
• everything inside the source folder EXCEPT the main.cpp file.
• all the FILES in the res folder EXCEPT for the c4d_symbols.h file

Files you should now have

You should now only have the following files/folders

• cinema4dsdk.sln - The Microsoft Visual Studio Solution
• cinema4dsdk.vcproj - The Microsoft Visual Studio Project
• source/main.cpp
• res/strings_us/c4d_strings.str
• res/strings_us/description
• res/strings_us/dialogs
• res/description
• res/dialogs
• res/scene
• res/c4d_symbols.h

Fixing up the project

Rename the cinema4dsdk.sln file to plugintemplate.sln

Rename the cinema4dsdk.vcproj file to plugintemplate.vcproj

Open the plugintemplate.sln file.

You will get a warning saying that cinema4dsdk.vcproj could not be loaded. This is ok, press the OK buttons and ignore the warnings.

Next select the cinema4dsdk project in the Solution Explorer on the right hand side of Visual Studio, right click and choose remove. Press OK on the dialog to confirm it should be removed.

Next right click on the solution and choose “Add->Existing Project”, select the plugin template project and press ok.

The plugintemplate project gets loaded into Visual Studio but it still has the name “cinema4dsdk” this is ok and we will change this next.

Right click on the cinema4dsdk project and choose rename and set its name to be plugintemplate.

Right click again and choose “Set as Startup Project”.

Right click one more time and choose “Project Dependencies”, check the _api checkbox and press ok to continue.

Expand the project and inside the SourceCode folder delete ALL the other folders leaving just the main.cpp file.

Open the main.cpp file and replace all the code with the following...

#include "c4d.h"
#include
// forward declarations
Bool PluginStart(void)
{
    return TRUE;
}
void PluginEnd(void)
{
}
Bool PluginMessage(LONG id, void *data)
{
    switch (id)
    {
        case C4DPL_INIT_SYS:
            if (!resource.Init()) return FALSE; // don't start plugin without resource
            return TRUE;
        case C4DMSG_PRIORITY:
            return TRUE;
    }
    return FALSE;
}

Set the output plugin name

Right click on the plugintemplate project in the VS Solution Explorer and choose Properties from the menu.

Under Configuration “Properties->Linker”change the “Output File” to “plugintemplate.cdl” and press ok on the dialog.

Test Build

Now we can do a test to make sure everything is working ok so far. From the Build menu choose “Build Solution”. You should get a “Build: 1 succeeded” at this point. The plugin does absolutely nothing at all but it at least compiles.

Writing the code for an image saver plugin

Writing your plugin code

Right click in the Source Code folder and choose Add->New Item. Choose “C++ File (.cpp)” and give it the name “myplugin”. Press Add on the dialog.

Add the following code to the myplugin.cpp files.

#include "c4d.h"
#define ID_MYBITMAPSAVER 123456789
class MyBitmapSaver : public BitmapSaverData
{
    public:
        virtual LONG Save(const Filename &name, BaseBitmap *bm, BaseContainer *data, LONG savebits);
};
LONG MyBitmapSaver::Save(const Filename &name, BaseBitmap *bm, BaseContainer *data, LONG savebits)
{
    return IMAGE_OK;
}
Bool RegisterMyBitmapSaver(void)
{    
    if(!RegisterBitmapSaverPlugin( ID_MYBITMAPSAVER, "MyBitmapSaver", PLUGINFLAG_BITMAPSAVER_SUPPORT_8BIT, gNew MyBitmapSaver, "mbs")) return FALSE;
    return TRUE;
}

Register your plugin within Main.cpp

Next add the following code to the Main.cpp file.

// forward declarations
Bool RegisterMyBitmapSaver();
Bool PluginStart(void)
{
    if(!RegisterMyBitmapSaver()) return FALSE;
    return TRUE;
}

Running the code

Now build the application and run it.  First select the menu option “Build->Build Solution”.

Once it has compiled put a break point in the Save method of your plugin on the line “return IMAGE_OK; “

Now select “Debug->Start Debugging” from the menu. You will be prompted again to choose the Cinema4d.exe to run. Select this and continue (for more information on this see the section above on “Running the plugin in debug mode”).

Now from within Cinema 4D change the layout to “BP 3D Paint”. Change to the Texture tab. Create a New Texture, do some painting if you want to and choose “File->Save Texture” from the menu on the Texture tab. In the drop down “Save File As:” choose the “MyBitmapSaver(*.mbs)” format and press OK. Type in a name for your file and press Save.

Your break point will be hit.

Getting a real plugin id

To be able to ship this great new plugin you will need to get an official ID for your plugin. In the above code you will have noticed I have the plugin the ID of 123456789. If another plugin ships using the same ID then you will get a conflict. To prevent this MAXON has setup a system to give developers their own ID’s for their plugins

Register on plugin cafe

Go to the following website and signup for a new account

http://www.plugincafe.com/developer_plugid.asp

Once you have your account, log in.

After you log in you will be taken to the Forum. But this is not where we want to go. Go back to the following website

http://www.maxon.net/en/support/for-developers/plugin-cafe.html

And on the right hand side select “Plugin ID’s”.

You will now see a dialog where you can type in the name of your plugin. This name is not used for anything other than to provide you, the developer, with a name that you can associate the ID with.

Choose a name for your plugin... perhaps MyBitmapSaver, and press the “Get PluginID” button.

A new number will be generated and shown in the list the dialog. Copy the new Plugin ID and paste it over the top of the 123456789 number in the myplugin.cpp file.

Now when you give your plugin to your friends, or sell it for thousands of dollars on the internet, you can be guaranteed that it will not clash with any other plugin out on the market (Unless of course the other developers did not get a unique ID themselves that is).

Conclusion

From this tutorial you have seen how to build the sample plugins that ship with Cinema4D using Visual Studio C++ 2008 Express Edition. You will have also built a plugintemplate that you can use again and again as a starting point for developing your new plugins. You wrote a skeleton plugin for your own bitmap saver and learnt how to get a unique ID for your plugin.

Downloadable Sample Code

You can download the final plugintemplate project from the following location. But you still MUST register for your own plugin id to distribute your plugin.

Unzip the plugintemplate.zip file to a plugintemplate folder in the “Cinema 4D R11.5/plugins” directory.

Also included in the zip file is the updated DebugWin32.vsprops file. You should copy this over the top of the file in the “C:\Program Files\MAXON\CINEMA 4D R11.5\resource\_api_lib” directory.

Attachments:

plugintemplate.zip

[ ]

9 Kb

10/26/2009 16:21