About

New instances of Cinema API plugin classes are typically created using a static "Alloc" function. The initial values of this instance are defined in an "Init" function. When an instance is deleted, its "Free" function is called.

Note: The undo system will allocate new instances of a plugin class when a scene object is changed.; "Alloc"/"Free" functions should generally be used instead of class constructor/destructor, as they provide means to return an error if anything goes wrong.

Alloc

A static "Alloc" function creates a new instance of a plugin class. This "Alloc" function is referenced in the corresponding "Register" function (see Common Plugin Concepts).

// This is a plugin class with a static "Alloc" function:
 
class ObjectDataGenerator : public ObjectData
{
  public:
 
  static NodeData* Alloc(void)
  {
    return NewObjClear(ObjectDataGenerator);
  }
};
 
// This is a "Register" function referencing that static "Alloc" function:
 
RegisterObjectPlugin(123456, "Example Generator", OBJECT_GENERATOR, ObjectDataGenerator::Alloc, "Ogenerator", nullptr, 0);

Init

Each class derived from NodeData can implement NodeData::Init(). This "Init" function is called every time when an instance of the plugin class is allocated. In this "Init" function one can define the default values of parameters and internal data instead of using a class constructor.

  // This example implements NodeData::Init() in a plugin class.
  // It sets the default values of the plugin's parameters.
 
  virtual Bool Init(GeListNode* node, Bool isCloneInit)
  {
    if (node == nullptr || !SUPER::Init(node, isCloneInit))
      return false;
 
    // get the "real" object
    BaseObject* const obj = static_cast<BaseObject*>(node);
 
    // get data container
    BaseContainer& data = obj->GetDataInstanceRef();
 
    // set default parameter values
    data.SetBool(EXAMPLE_GENERATOR_PARAMETER_BOOL, true);
    data.SetInt32(EXAMPLE_GENERATOR_PARAMETER_VALUE, 123);
 

Note: If NodeData::Init() returns false the object won't be created.; If an entity should be modified when it was created the best solution is to catch the MSG_MENUPREPARE message.; There's no guarantee NodeData::Init() is called only once. In fact it may very well be called multiple times.

Free

Each class derived from NodeData can implement NodeData::Free(). This function is called when an instance gets freed. Implement this function to free internal data.

  virtual void Free(GeListNode* node)
  {
    DeleteMem(_memory);
    GeListHead::Free(_branchHead);
  }

Table of Contents

About

Alloc

Init

Free

Further Reading