Memory Management

• Garbage collection for UnigineScript
• Memory Management for Extern Classes

The fisrst variant is the following: a node that is created and handled by the world script is passed to the extern function as a smart pointer.

1. Create a custom function on the C++ side, to which a NodePtr smart pointer will be passed. Then a function need to be registered with Unigine interpreter, so that the script could call it in its runtime.
   Source code (C++)

   //main.cpp
   #include <Unigine.h>
   #include <UnigineInterpreter.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   
   // 1. Create an extern function that receives a script node as a smart pointer NodePtr
   void my_node_set(NodePtr node) {
   	// 1.1. Call the node member function exposed through the C++ API
   	node->setTransform(translate(vec3(1.0f,2.0f,3.0f)));
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. Register the function for export into Unigine
   	Interpreter::addExternFunction("my_node_set",MakeExternFunction(&my_node_set));
   	
   	// 3. Initialize the engine
   	Engine *engine = Engine::init(UNIGINE_VERSION,argc,argv);
   	
   	// 4. Enter the engine main loop
   	engine->main();
   	
   	// 5. Shut down the engine
   	Engine::shutdown();
   	
   	return 0;
   }
   

2. Create a node in the world script and call the registered C++ function. The ownership of the node will belong to the script, so only it could call delete operator to destroy the node.
   Source code (UnigineScript)

   //world script (myworld.cpp)
   
   int init() {
   	// 1. Create a new dummy object and cast it to the Node type, so it could be passed to the extern C++ function as NodePtr
   	Node node = class_cast("Node",new ObjectDummy());
   	// 2. Call the registered C++ function
   	my_node_set(node);
   	
   	// 3. Delete the node if no longer needed; otherwise, the node will be automatically deleted by the script shutdown
   	delete node;
   
   	return 1;
   }
   

This variant is similar to the previous one, except that it is valid for the following objects:

• Unigine::Object
• Unigine::ObjectMeshDynamic
• Unigine::ObjectMeshSkinned

1. Create a custom function on the C++ side, which will receive a NodePtr smart pointer. An object as it is cannot be passed between the script and C++ part — only a node pointer can. After that, the object is cast to its specific type using create() function and calls its member function. The extern function should be registered to be called by the script.
   Source code (C++)

   //main.cpp
   #include <Unigine.h>
   #include <UnigineObject.h>
   #include <UnigineInterpreter.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   // 1.0. Create an extern function that receives a script object as a smart pointer NodePtr
   void my_object_update(NodePtr node,float time) {
   	
   	// 1.1. Cast the given object from the NodePtr type to the ObjectMeshDynamicPtr smart pointer type
   	ObjectMeshDynamicPtr object = ObjectMeshDynamic::create(node);
   	// 1.2. Call the member function of the ObjectMeshDynamic
   	object->updateSurfaces();
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. Register the function for export into Unigine
   	Interpreter::addExternFunction("my_object_update",MakeExternFunction(&my_object_update));
   	
   	// 3. Initialize the engine
   	Engine *engine = Engine::init(UNIGINE_VERSION,argc,argv);
   	
   	// 4. Enter the engine main loop
   	engine->main();
   	
   	// 5. Shut down the engine
   	Engine::shutdown();
   	
   	return 0;
   }
   

2. On the script side, create an object and cast it to the node type. After that, the registered extern C++ function call receive it, when called by the script. Ownership remains by the script, so it can delete the object.
   Source code (UnigineScript)

   //world script (myworld.cpp)
   
   int init() {
   	// 1. Create a new ObjectMeshDynamic
   	Object object = new ObjectMeshDynamic();
   	// 1.1. Call the member function
   	object.setMaterial("mesh_base","*");
   	// 2. Cast the object into a node type for the extern function to recieve it 
   	Node node = class_cast("Node",object);
   	
   	// 3. Call the registered extern C++ function
   	my_object_update(node,engine.game.getTime());
   	
   	// 4. The script can delete the object, as it was the one that allocated it
   	delete node;
   
   	return 1;
   }
   

The third variant is to create an object in the script (for example, the image) and pass it to the extern C++ function as a variable. The extern function is called by the script thereafter.

1. Create a custom function on the C++ side, which will receive a variable. The variable is cast to the ImagePtr smart pointer type using the dedicated function getImage(). After that, the extern function should be registered to be called by the script.
   Source code (C++)

   //main.cpp
   #include <Unigine.h>
   #include <UnigineImage.h>
   #include <UnigineInterpreter.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   // 1. Create an extern function that recieves a variable
   void my_image_get(const Variable &v) {
   
   	// 1.1. Cast the recieved variable to the ImagePtr type
   	ImagePtr image = v.getImage();
   	
   	// 1.2. Call the image member functions exposed through C++ API
   	return image->getFormatName();
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. Register the function for export into Unigine
   	Interpreter::addExternFunction("my_image_get",MakeExternFunction(&my_image_get));
   	
   	// 3. Initialize the engine
   	Engine *engine = Engine::init(UNIGINE_VERSION,argc,argv);
   	
   	// 4. Enter the engine main loop
   	engine->main();
   	
   	// 5. Shut down the engine
   	Engine::shutdown();
   	
   	return 0;
   }
   

   There also exists another way to cast the variable into the image pointer type using VariableToType function:

   Source code (C++)

   //main.cpp
   ...
   // 1. The same extern function
   void my_image_get(const Variable &v) {
   
   	// 1.1. Another way of casting the variable value into ImagePtr:
   	ImagePtr image = VariableToType<ImagePtr>(v).value;
   
   	return image->getFormatName();
   }
   ...
   

2. On the script side, the image needs to be created and simply passed to the extern function. The image will be converted into the ImagePtr smart pointer automatically.
   Source code (UnigineScript)

   //world script (myworld.cpp)
   int init() {
   
   	// 1. Create a new image
   	Image image = new Image();
   	// 1.1. Specify parameters of the image and fill it with black color
   	image.create2D(256,256,IMAGE_FORMAT_R8);
   	
   	// 2. Call the registered extern function and simply pass the image to it
   	my_image_get;
   	
   	// 3. The script can delete the image explicitly, if necessary
   	delete image;
   	
   	return 1;
   }
   

Smart pointers allow the extern function not only to recieve the objects created by the script, but also create instances of a native Unigine C++ classes, which are allocated in the Unigine memory pool.

Here, a script calls an extern function that creates a new image using ImgPtr.

1. First of all, it is necessary to define ImgPtr as a global variable. Otherwise, if it is a local variable defined inside the function block, the image will not be visible outside the function scope. Though it can be passed to the script, the pointer will be dangling, i.e. it will not point to the valid image object.
   Then a custom function calls API function create() and is registered with the Unigine interpreter.
   Source code (C++)

   //main.cpp
   #include <Unigine.h>
   #include <UnigineImage.h>
   #include <UnigineInterpreter.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   // 0. ImagePtr must be defined as a global variable
   ImagePtr image;
   
   // 1. Create an extern function that returns an ImagePtr smart pointer
   ImagePtr my_image_create_0() {
   
   	// 1.1. Create an image in the Unigine memory pool through ImagePtr smart pointer
   	image = Image::create();
   	// 1.2. Specify parameters of the image and fill it with black color
   	image->create2D(128,128,Image::FORMAT_RG8);
   	
   	return image;
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. Register the function for export into Unigine
   	Interpreter::addExternFunction("my_image_create_0",MakeExternFunction(&my_image_create_0));
   	
   	// 3. Initialize the engine
   	Engine *engine = Engine::init(UNIGINE_VERSION,argc,argv);
   	
   	// 4. Enter the engine main loop
   	engine->main();
   	
   	// 5. Shut down the engine
   	Engine::shutdown();
   	
   	return 0;
   }
   

2. Call the registered extern function. The image it returns can be simply passed to the script, as conversion from ImgPtr into the image will be done automatically. Remember, the script cannot delete the image, as the ownership belongs to the extern function. The smart pointer will be automatically released when the reference count reaches zero.
   Source code (UnigineScript)

   //world script (myworld.cpp)
   int init() {
   	
   	// 1. Call the extern function in the script
   	my_image_create_0();
   	
   	// 2. The script will automatically handle ImgPtr returned by the extern function as a simple image
   	image.getFormatName();
   	
   	return 1;
   }
   

This variant is similar to the previous one, except that the extern function creates a new image object as a variable. The script still calls the extern function.

1. ImgPtr should be defined as a global variable, just like in the previous case. Then the custom extern function can create an ImgPtr smart pointer, which will allocate a native Unigine image, and set it to the variable using the dedicated function setImage().
   Source code (C++)

   //main.cpp
   #include <Unigine.h>
   #include <UnigineImage.h>
   #include <UnigineInterpreter.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   // 0. ImagePtr must be defined as a global variable
   ImagePtr image;
   
   // 1. Create an extern function that returns a variable
   Variable my_image_create_1() {
   	
   	// 1.1. Create an image in the Unigine memory pool
   	image = Image::create();
   	// 1.2. Specify parameters of the image and fill it with black color
   	image->create2D(128,128,Image::FORMAT_RG8);
   	
   	// 1.3. Define the variable
   	Variable v;
   	// 1.4. Set the image smart pointer to the variable
   	v.setImage(image);
   	
   	return v;
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. Register the function for export into Unigine
   	Interpreter::addExternFunction("my_image_create_1",MakeExternFunction(&my_image_create_1));
   	
   	// 3. Initialize the engine
   	Engine *engine = Engine::init(UNIGINE_VERSION,argc,argv);
   	
   	// 4. Enter the engine main loop
   	engine->main();
   	
   	// 5. Shut down the engine
   	Engine::shutdown();
   	
   	return 0;
   }
   

   Another way to set the ImgPtr smart pointer to the variable is to use TypeToVariable function:

   Source code (C++)

   //main.cpp
   ...
   // 1. The same extern function
   Variable my_image_create_1() {
   	
   	image = Image::create();
   	image->create2D(128,128,Image::FORMAT_RG8);
   
   	// 1.3. Another way of setting the image smart pointer to the variable:
   	Variable v = TypeToVariable<ImagePtr>(image).value;
   	
   	return v;
   }
   ...
   

2. A script calls the registered extern function. After that, it handles the returned variable as a simple image, because conversion is done automatically. Remember, the script cannot delete the image, as the ownership belongs to the extern function. The smart pointer will be automatically released when the reference count reaches zero.
   Source code (UnigineScript)

   //world script (myworld.cpp)
   int init() {
   	
   	// 1. Call the extern function in the script
   	my_image_create_1();
   	
   	// 2. The scipt automatically handles the returned ImgPrt as a simple image
   	image.getFormatName();
   	
   	return 1;
   }
   

The last variant is to create a native Unigine Image object as a variable on the C++ side. However, it is not the script that calls the external function, therefore the context for the created variable should be set manually for the interpreter. It is done with the help of the following functions:

• Unigine::Engine::getWorldInterpreter()
• Unigine::Engine::getSystemInterpreter()
• Unigine::Engine::getWorldInterpreter()

//main.cpp
#include <Unigine.h>
#include <UnigineImage.h>
#include <UnigineInterpreter.h>

/*
 */
using namespace Unigine;

/*
 */
// 0. ImagePtr must be defined as a global variable
ImagePtr image;

// 1. Create an external function that returns a variable
Variable my_image_create_1() {
	
	// 1.1. Create an image in the Unigine memory pool
	image = Image::create();
	// 1.2. Specify parameters of the image and fill it with black color
	image->create2D(128,128,Image::FORMAT_RG8);
	
	// 1.3. Define the variable
	Variable v;
	
	// 1.4. Set the world script context, because setImage() requires a script environment
	Engine *engine = Engine::get();
	Interpreter *world = (Interpreter*)engine->getWorldInterpreter();
	// 1.5. Set the image smart pointer to the variable
	v.setImage(world,image);

	return v;
}
...
// Use the external function somewhere later
...