MAXON API Introduction

The MAXON API is a brand new API for Cinema 4D with a different paradigm, with more power and flexibility.

This API is the one used for the Cinema 4D development itself. Meaning that our internal developers use and develop this API.

Previously the CLASSIC API was internally an extra layer in Cinema 4D ecosystem, which become costly to maintain or even sometime too limiting to implement a specific features.
In the long term (when everything will be ported to it) 3rd party developers will have the same amount of customization over Cinema 4D than Maxon developers.

See also

Foundations for the Future

Finally, the MAXON API provides nice few features:

  • Clear and consistent naming convention.

  • Modularity concept.

  • Consistent object creation.

  • Error handling; in Python, a exception is raised when something went wrong.

Warning

Currently the Python MAXON API, does not support named parameters. It’s a know issue. So all parameters need to be filled.

Basics

The MAXON API is made from these components:

Frameworks

A framework includes MAXON API components (interfaces, references, data types, etc…) for a specific feature e.g. the volume framework for the usage of OpenVDB based volume data.

Note

In Python, frameworks are exposed as a module under the maxon.frameworks module.
By default, they are not imported in the Cinema 4D eco-system. To use a framework, you first need to import it e.g. for the volume framework
import maxon
from maxon.frameworks import volume

# Access classes exposed by the volume framework
volume.VolumeInterface

See also

MAXON API - Frameworks

Interfaces

Note

In the MAXON API, interface classes end with the suffix Interface e.g. VolumeInterface.

The interface system of the MAXON API is a powerful toolset to define public APIs and to hide implementation details.

An interface defines a class that is the base for both the implementation and the reference class.

Warning

Currently the Python MAXON API doesn’t support the creation of a completely new implementation (the logic) for an interface, but only one that already exists in C++.

Warning

In the Python MAXON API, an interface should not be used directly. Instead, create a new instance of the reference class of the interface. See References.

See also

MAXON API - Interfaces

References

Note

In the MAXON API, References classes ends with the suffix Ref e.g. VolumeRef.

In some case a Reference class can be named as the Interface without the Interface suffix e.g. Object is the reference class of ObjectInterface.
This means that the reference is a COW-Reference (Copy-On-Write), meaning until you modify something in the reference this is the same object used in the memory.
As a python developer you don’t have to deal with it, just be aware that sometime the Ref suffix might be not there.
A reference is nothing more than an instance of an interface (class). In Python, this is not as important, since Python is already based on references.
In C++, this ensures that no memory leaks will occur.

To create a new instance of an interface, you retrieve a reference instance to this interface.
VolumeRef() creates an instance of the reference of a VolumeInterface.

See also

MAXON API - References

Data Types

The MAXON API provides new data types. They are optimised to work with the MAXON API and match the MAXON API C++ data types.
Almost all builtin Python Type have an equivalent Python Type available as a Python Maxon API Type here a no-exhaustive list:
With that’s said, it’s sometimes useful to convert a Maxon data type to Python built-in data type. This can be done with maxon.MaxonConvert().

See also

MAXON API - Data Types

Registries

MAXON API relies on registries. Theas means that each MAXON API component (interfaces, daty types, etc…) is inserted in a registry.
Registries are also a MAXON API component, meaning they are also present in a registry.

A registry is a dictionary where the key is a maxon.Id and the entry can be anything e.g. a class (Interface,Reference, refistry, etc…), an attribute, a constant value, etc…

The main purpose of a registry is to store a anything related to a given category with the possibility to be dynamic.
For example maxon.Loggers is a registry that store all the different loggers available.
Adding a new entry of the correct type with the correct option to this dictionary, will automatically expose this logger to the Cinema 4D Console.

Warning

Currently the MAXON Python API doesn’t support the creation of a completely new implementation (the logic) for an interface. Only existing implementations (created in C++) can be used.
This means that Python users can use registries only to receive a list of implementations.

With the C++ API, it is possible to add new implementation to any registry.
This allows 3rd party developers to add new components in a more modular way, as registry are widely used in Cinema 4D and will be used more and more.
Previously, only a few areas where possible to extend.

See also

MAXON API - Registries and Enums