Entity Creation and Destruction Manual (Classic)

About

Primitive data types and structures can be created on the stack. Complex data types, classes and dynamic memory have to be allocated using Cinema 4D's memory management system. Using Cinema 4D's memory management system increases the stability and speed of a plugin.

Warning
The creation of objects and references in the context of the MAXON API is described here: Entity Creation.

Object Allocation

New instances of generic classes should be allocated and freed with these functions:

  • NewObj(): Creates an object with the given constructor parameters.
  • DeleteObj(): Deletes the given object.
Note
Always check for nullptr when allocating memory.
// This example allocates a new instance of the given object class.
// A constructor parameter is handed over.
// After the object is used it will be deleted.
CustomClass* newObject = NewObj(CustomClass, 123) iferr_return;
if (newObject != nullptr)
{
const Int32 number = newObject->GetNumber();
ApplicationOutput("Number: @", number);
DeleteObj(newObject);
}
Note
None of these functions will throw an exception in case of an error.

Alloc and Free

Most complex classes of the classic API provide a static "Alloc" and "Free" function. These functions have to be used to create new instances of these classes.

// This example allocates a BaseObject with BaseObject::Alloc().
// If the object cannot be inserted into a document it will be deleted.
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
if (doc == nullptr)
{
return maxon::NullptrError(MAXON_SOURCE_LOCATION);
}
doc->InsertObject(cube, nullptr, nullptr, true);
Note
It is recommended to use AutoAlloc (see below) as much as possible to avoid memory leaks.

AutoAlloc

AutoAlloc is a smart pointer that allocates and deallocates a new instance of a class using its static "Alloc" and "Free" functions based on scope.

Note
There is only a limited number of AutoAlloc constructors. If no available constructor fits use the class' "Alloc" function and manage the ownership with AutoFree.
// This example allocates a BaseObject with AutoAlloc.
// If something goes wrong one can leave the function and AutoAlloc will free the BaseObject.
// If everything goes right the ownership of the BaseObject is handed over
// to the given BaseDocument.
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
cube->SetName("The new cube"_s);
// if something is wrong, just return
if (doc == nullptr)
return maxon::NullptrError(MAXON_SOURCE_LOCATION);
// release ownership and insert into the document
BaseObject* const releasedCube = cube.Release();
doc->InsertObject(releasedCube, nullptr, nullptr, true);

AutoFree

AutoFree is a smart pointer that deallocates the stored object with its static "Free" function based on scope.

// This example allocates a BaseObject with BaseObject::Alloc().
// The ownership is given to an AutoFree object that
// will delete the object when the scope is left.
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// AutoFree takes ownership
cubeFree.Assign(cube);
cubeFree->SetName("The new cube"_s);
// if something is wrong, just return
if (doc == nullptr)
return maxon::NullptrError(MAXON_SOURCE_LOCATION);
// release ownership and insert into the document
BaseObject* const releasedCube = cubeFree.Release();
doc->InsertObject(releasedCube, nullptr, nullptr, true);

Further Reading