Introduction

The C++ language has many powerful features, but this power brings with it complexity, which in turn can make code more error-prone and harder to read and maintain. The goal of this guide is to help you manage this complexity by describing in detail the major dos and don'ts of writing C++ code for Cinema 4D plugins. We recommend you enforce consistency to keep your code base manageable. Creating common idioms and patterns makes code much easier to understand. In some cases there might be good arguments for changing certain style rules, but nonetheless it is best to preserve consistency as much as possible. A major benefit is it will allow us to better understand your code when asking for help on the Plugin Cafe forum or via direct support.

Another issue this guide addresses is that of C++ feature bloat. C++ is a huge language with many advanced features. In some cases we constrain, or even ban, the use of certain features. We do this to keep code simple and to avoid the various common errors and problems that these features can cause. This guide lists these features and explains why their use is restricted.

1. Basic C++ Language

1.1 C++ 11

The following C++ 11 features are currently supported:

Move semantics / R-Value references
std::is_pod, std::is_scalar, std::is_base_of, std::is_function, std::is_polymorphic, std::is_convertible
static_assert
auto
decltype
Range-based for loops
Extern template
Lambda expressions and closures
Explicit overrides and final
Right angle brackets
nullptr
Thread-local storage
Strongly typed enums
Brace-or-equal initializers (in-class member initializers)

Note: Any other C++ 11 features must not be used. See also C++ Techniques.

1.2 For Increments

Do not use "for" statements that use floating point values as an increment. Float increments can lead to infinite loops or unexpected behavior.

  const maxon::Float maxRange  = 1.0;
  const maxon::Float minRange  = 0.0;
  const maxon::Float increment = 0.1;
 
  if (increment == 0.0)
    return false;
 
  const maxon::Int cnt = SAFEINT((maxRange - minRange) / increment);
 
  for (maxon::Int i = 0; i < cnt; ++i)
  {
    const maxon::Float currentPosition = minRange + (maxRange - minRange) * maxon::Float(i) / maxon::Float(cnt);
    DiagnosticOutput("Position: @", currentPosition);
  }

1.3 ANSI C Routines

Don't use ANSI C routines in your code if there is a library replacement. E.g. memset, memcpy, printf, scanf etc. should never be touched.

1.4 Casts

Even though they look a little messy use static_cast and const_cast for all non-arithmetic datatypes. This has several advantages: casts can be searched easier and they also are much safer as you cannot cast into a completely different type accidentally.

  // arithmetic datatype
  const maxon::Float b = (maxon::Float)a;
 
  const MyObject* const constObj = static_cast<const MyObject*>(inputObject);
  MyObject* const       obj = const_cast<MyObject*>(constObj);

1.5 Goto

The goto statement should only be used if it is absolutely the best choice for an algorithm's implementation. Generally, your code should be structured so that it can return at any point and that it makes sure everything is cleaned up properly.

2. Cinema 4D C++ Specifics

2.1 External Libraries

Do not use external libraries (e.g STL or BOOST) unless absolutely necessary.

2.2 Threading

Be aware of threading! It's recommended to stick to the following directions:

GUI interaction must never happen in a thread. Instead, offload jobs to the main thread queue.
Input states (e.g. from the keyboard or mouse) must never be queried in a thread.
Do not write to global structures from a thread.
Any shared resources must be properly protected by SpinLocks or Semaphores.
Be aware of how deadlocks are created.

2.3 Global Static Classes

Static or global variables of class type (e.g. using something like String g_mySharedStringVariable) are forbidden due to the indeterminate order of construction and destruction. The same applies to AutoMem.

2.4 Array Classes

Only use the classes BaseArray, BlockArray, PointerArray or derived classes. Whenever you access arrays make sure that any access is within boundaries, otherwise you'll provoke a crash and undefined behaviour. You can only omit those checks for speed critical areas. In that case, you should document in the routine's header that a variable needs to be within a certain range.

// pass an array with 100 elements
maxon::Result<maxon::Int> MyRoutine(maxon::Float x, maxon::BaseArray<maxon::Int>& arr)
{
  const maxon::Int index = maxon::Int(x * 100.0);
 
  // by casting to UInt you can merge two checks into one as any negative value casted to UInt exceeds 100
  if ((maxon::UInt)index >= 100)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  return arr[index];
}

2.5 Range-Based for Loops and Iterators

When iterating, use references (unless specifically needed otherwise) so that no unnecessary data will be copied. Always use const if no modification is necessary. If it doesn't compile, fix your classes so they properly support constness. If you need additional functionality obtain an auto-iterator with ForEach::Get() or an erase-iterator with ForEach::EraseIterator.

  // create
  maxon::BaseArray<maxon::Vector> arr;
  arr.Resize(100) iferr_return;
 
  // fill
  for (maxon::Vector& value : arr)
  {
    value = maxon::Vector { 1.0 };
  }
 
  // add value
  arr.Append(maxon::Vector { 1.0, 0.0, 0.0 }) iferr_return;
 
  // read all values
  for (const maxon::Vector& value : arr)
  {
    DiagnosticOutput("@", value);
  }
 
  const maxon::Vector valueToErase { 1.0, 0.0, 0.0 };
 
  // EraseIterator allows you to still use range-based for loops
  for (auto it = maxon::Iterable::EraseIterator(arr); it; ++it)
  {
    if (*it == valueToErase)
      it.Erase();
  }

2.6 Magic Numbers

Use constants instead of magic numbers wherever possible. The meaning of arbitrary numbers is often not clear to the reader. An explicit name helps readability.

  const maxon::Int DAYS_IN_WEEK = 7;
  const maxon::Int DAY_MONDAY = 0;
  const maxon::Int DAY_SUNDAY = 6;
 
  const maxon::Int day = GetDay();
 
  if ((day % DAYS_IN_WEEK) == DAY_SUNDAY)
    CallJob();

3. Error Handling

3.1 Defensive Coding

Try adopting a defensive style - add additional checks, even if you are sure these conditions do not happen. At a later time, circumstances may change, making those particular conditions come true. Make sure your source code compiles free of warnings on all platforms and targets.

3.2 Exceptions & RTTI

C++ exceptions and RTTI will not be used in any of our projects unless external libraries require it (also RTTI operators typeid and dynamic_cast cannot be used).

3.3 Memory Checks

Every memory allocation must be checked. It is not sufficient to check and leave your scope though. You must make sure that a class is not in an uninitialized state and will still properly function according to specifications. It is highly recommended that you implement memory checks during development and not at the very end of a development cycle. Instead of using memory blocks always use arrays (e.g. BaseArray, BlockArray, PointerArray). They're much more flexible, safe (you get additional safety checks in debug builds), reduce code size and offer the same performance.

class Test
{
public:
  Test() { }
 
  maxon::Result<void> Init()
  {
    return arr.Resize(100);
  }
 
  maxon::Int GetCount() { return arr.GetCount(); }
 
private:
  maxon::BaseArray<maxon::Char> arr;
};

3.4 Memory Allocations

Any class allocation (except for system or library specific code) must be done using NewObj() and DeleteObj(). Any memory allocation must be done using NewMem() and DeleteMem(). Memory obtained with NewObj() and NewMem() is NOT initialized, so you must make sure that the class/struct constructors properly initialize all member variables. To obtain cleared memory, use NewMemClear(). For constructors, this is not available. As a side note, AutoMem is a convenient way to free memory when your scope is left in case of an error.

Circumventing Cinema 4D's memory management and using the standard libs allocators will result in lower speed and will keep you from utilizing Cinema 4D's leak detection utilities.

3.5 Divisions by zero

Any floating point division must be checked for 0.0 unless the algorithm specifically doesn't require this check. An example where it is not necessary is e.g. x /= (1.0 + vectorA * vectorA) where the divisor never can become 0.0. Otherwise, a test must be done. It cannot be stated often enough that floating point calculations are imprecise... (c - d below) can be different to 0.0 and then in the next code line be 0.0. This is not even uncommon with optimizing compilers. See the examples below that will always fail!

Any integer division must also be checked for 0, however the strict requirements aforementioned don't apply here.

  maxon::Float x, tmp = c - d;
  if (tmp != 0.0)
    x = (a - b) / tmp;
  else
    x = 0.0;

3.6 Type Conversions

Always be careful with type conversions as they are a frequent cause for crashes!

E.g. if you want to calculate an index within a 2-dimensional array. Let's assume both dimensions are larger than 32767 units. In that case the index needs to be of type Int (64-bit), otherwise you'd get an overflow. What is often overseen though is that it is not enough to just change the index to Int:

maxon::Int32 xRes = maxon::LIMIT<maxon::Int32>::MAX, y = maxon::LIMIT<maxon::Int32>::MAX, x = 0;

maxon::Int index = xRes * y + x;

If you take a look in the debugger you'll see the following:

xRes  2147483647
y   2147483647
index 1

The calculation is done with Int32 and then at the end the result is casted to Int (when it is too late).

So the only correct way to write this (in case you want to keep x, y and xRes as Int32) is:

index = (maxon::Int)xRes * y + x;

or

index = xRes * (maxon::Int)y + x;

but not

index = xRes * y + (maxon::Int)x;

Another frequent conversion problem is if you go from Float to Int. In many places a 3D point is projected onto the screen, converted to Int and then clipped against the screen boundaries. This will always fail!

Let's take a look why:

maxon::Float n = 1.0e10;

maxon::Int m = (maxon::Int)n;

In the debugger you will see:

n 1.0000000000000000e+020

m -9223372036854775808

So if you want to perform a proper clipping you have two possibilities:

a) Clip floating point values first (on a float basis) and then convert to Integer

maxon::Float xClamped = ClampValue(xInput, (maxon::Float)left, (maxon::Float)right);

maxon::Int x = (Int)xClamped;

Table of Contents