SDK Overview

Overview

The Cinema 4D SDK is the collection of frameworks and example projects available for third party developers to create Cinema 4D plugins. To use the SDK it is also necessary to get the Project Tool.

SDK Installation

The sdk.zip file containing the frameworks and example projects is delivered with each version of Cinema 4D. This ZIP file can be extracted to any location on the file system.

Note
The needed project files for frameworks, solutions and plugins must be created using the Project Tool.

Plugin development for Cinema 4D is currently supported on these platforms:

SDK Structure

The unzipped SDK contains two folders:

  • frameworks: Contains the header and source files for all frameworks. These frameworks define the MAXON API and give access to Cinema 4D's functionality.
  • plugins: Contains the SDK solution and plugin projects. New plugin projects must be added to this folder.

Solutions

The development solution includes plugin and framework projects. It is automatically generated based on the settings of a projectdefinition.txt file. The master solution is located in the "plugins/project" folder. Additional custom plugins can be added to or removed from this solution by editing its projectdefinition.txt file. Alternatively one can create a custom solution.

// Configuration of the development solution projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a Solution
Type=Solution
// included plugin projects
Solution=\
plugins/cinema4dsdk;\
plugins/newplugin

Custom Solutions

A new solution is simply added by creating a new sub-folder in the "plugins" folder. This folder must contain a custom projectdefinition.txt file.

For more details see projectdefinition.txt.

// Configuration of a custom solution in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a solution
Type=Solution
// included plugin projects
Solution=\
plugins/pluginA;\
plugins/pluginB
// include natvis files in Visual Studio solution file
AdditionalSolutionFiles=\
..\..\frameworks\core.framework\project\typeviewer\msvc\maxon.natvis;\
..\..\frameworks\cinema.framework\project\typeviewer\msvc\c4dapi.natvis

Frameworks

A framework is a collection of source and header files that define a part of the MAXON API. It includes symbols, functions, data structures and interfaces. If a plugin project wants to access the functionality defined in such a framework it must include it in the project file (see below). The functionality presented in such frameworks is implemented in the modules delivered with Cinema 4D.

The functions, symbols and classes defined in these frameworks are commented using Doxygen syntax. Functions marked as "private" or "internal" must not be used by third party developers.

For an overview over all MAXON API frameworks see MAXON API Frameworks.

Custom Frameworks

A new framework is created by adding a new sub-folder to the "frameworks" folder. Framework names are typically using the suffix ".framework" e.g. "custom.framework".

Such a framework folder must contain a "source" folder which will contain all source and header files of the framework. A "project" folder must contain the projectdefinition.txt file. For more details see projectdefinition.txt.

// Configuration of a custom framework in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a framework
Type=Lib
// this framework depends on the listed frameworks:
APIS=core.framework
// framework ID
ModuleId=com.examplecompany.myplugin.framework

A custom framework must be registered in a source code file in exactly one plugin (module). In this custom code a automatically generated hxx file must be included. The name of that hxx file is based on the framework's "ModuleId" (see Frameworks). E.g. for a framework named "com.examplecompany.myplugin.framework" the code would look like this:

#define MAXON_REGISTRATION_EXCLUDE_REFLECTION
#define MAXON_REGISTRATION_EXCLUDE_REFLECTION_NONVIRTUAL
#include "registration_com_examplecompany_myplugin_framework.hxx"

Example Plugins

The "plugins" folder contains these example plugin projects:

  • cinema4dsdk: This project contains the classic API examples as well as new examples that rely on both the classic API and MAXON API.
  • microsdk: This is a minimalist hybrid plugin that combines the classic API and MAXON API.
  • maxonsdk.module: This project contains the implementation of multiple MAXON API interfaces. It does not use the classic API at all.

Custom Plugins

A new plugin is added by creating a sub-folder in the "plugins" folder. The suffix ".module" is used to identify plugins that purely use the MAXON API and do not use any classic API code. See Plugins, Modules and Dependencies.

The "source" folder of such a plugin must contain the source code files. The "project" folder contains the projectdefinition.txt file that describes the plugin:

// Configuration of a custom plugin in the projectdefinition.txt file
// support Windows and macOS
Platform=Win64;OSX
// this is a plugin
Type=DLL
// this plugin depends on these frameworks:
APIS=\
cinema.framework; \
misc.framework; \
image.framework; \
core.framework
// defines the level of rigour of the source processor's style check
stylecheck.level=3
// plugin/module ID
ModuleId=com.examplecompany.myplugin

See also projectdefinition.txt and Plugin Development.

Scripts and Tools

The complexity of the MAXON API requires the automation of various processes using custom tools:

  • Project Tool : This tool automatically creates project files for solutions, framworks and plugins.
  • Source Processor : This collection of Python scripts analyses the source code of a plugin or framework and creates additional code.

Further Reading