内存管理

• 用于UnigineScript的Garbage集
• 用于外部类的内存管理

使用下列系统函数，脚本可对内部C++类示例的所有权进行处理：

• class_append()将内部实例的所有权分配给当前脚本模块。所有附加的实例将在脚本关机中被自动删除或者可使用delete运算符将其删除。例如：
  源代码 (UnigineScript)

  // 克隆一个现存节点。克隆的节点将被进行孤行处理
  Node clone = node.clone();
  // 为节点设置脚本所有权
  class_append(clone);
  // 在有必要的情况下稍后删除克隆节点
  delete clone;

  此时clone()会返回一个孤行的新节点。为了防止内存泄露的发生，脚本会承担所有权关系并以安全的方式将节点删除。
• class_manage()表明应为内部实例执行引用计数。当指向实例的引用数达到0时，先前为实例分配的内存会被自动删除，这样开发者不必再对指向实例的生命期进行细致的管理。在调用此函数之前，应将内部实例附加在脚本上。
  源代码 (UnigineScript)

  //  创建一副将被脚本自动拥有的图像
  Image image = new Image();
  // 为图像启用引用计数
  class_manage(image);
  // 当无用于图像的引用时，图像将被删除
  image = 0;

  此时图像会自动为脚本所拥有，因为使用了new运算符创建出此图像。由于无用于图像的引用，因此此图像将被删除。
• class_release()会将所有引用移至内部C++类的实例中。此方法可移除最小的内存泄露。
  源代码 (UnigineScript)

  // 创建将自动被脚本所拥有的新节点
  NodeDummy node = new NodeDummy();
  // 删除节点的引用
  node = class_release(node);

• class_remove() 释放实例的所有权。需要将所有权重新分配给任意的模块（在发布所有权之前或之后进行操作）使所有权不会成为孤行状态。例如可将其传递给节点 层级中的引擎编辑器以便将来能实时调整。
  源代码 (UnigineScript)

  Body body = class_remove(new BodyRigid(object)); // 被分配到的对象会自动对实体进行管理
  ShapeSphere shape = class_remove(new ShapeSphere(body,radius)); // 被分配到的实体会自动对形状进行管理
  JointFixed joint = class_remove(new JointFixed(body,body0)); // 被分配到的实体会自动对结合点进行管理

• class_cast()将用于所给类型的内部实例的指针转换成另一种类型 。
  注意

  指针转换这一操作并不安全且可对指定任意的转出类型，因为不会对指针以及指针类型进行检查。
  在转化为另一种类型时，并不会构建一种新的内部实例，因此无法使用delete运算符对其进行删除。
  源代码 (UnigineScript)

  // 获取一个节点
  Node node = engine.world.getNode(id);
  // 将节点强制转换成ObjectMeshStatic类型
  ObjectMeshStatic mesh = class_cast("ObjectMeshStatic",node);
  // 调用节点被强制转换成的类成员函数
  string name = mesh.getMeshName();

  如果要通过delete运算符将上述实例中阐述的网格删除，会发生错误。然而如果删除此节点，此网格也同样会被删除。

存在一组函数让您能以安全的方式对分层节点 及所有子节点进行处理。可在Unigine SDK的data/core/unigine.h文件中找到这些函数。

• Node node_append(Node node) 对所给节点及节点后代的脚本所有权进行注册。
  源代码 (UnigineScript)

  // 加载一个节点。脚本会自动拥有此节点。
  Node node = engine.world.loadNode("my.node");
  
  // ...
  // 释放实例的脚本所有权
  
  // 将一个孤行子节点添加到加载的节点上
  node.addChild(class_remove(new NodeDummy()));
  // 为父节点及子节点设置脚本所有权
  node_append(node);

  此处，脚本会拥有my节点及其子节点(NodeDummy)的所有权。
  注意

  专门创建示例中呈现的场景这样才能显示出node_append()为整个节点层设置脚本的所有权。因此在添加一个子节点到应用程序的某个节点上之前，不必调用class_remove()。
• Node node_remove(Node node)释放所给节点及子节点的脚本所有权并将这些节点强制转换为相应类型。例如使用此函数来设置为脚本所拥有的节点引擎编辑器所有权。
  注意

  如果存在地话，记得为孤行节点设置另一个所有者。
  源代码 (UnigineScript)

  // 创建自动被脚本所拥有的静态网格
  ObjectMeshStatic mesh = new ObjectMeshStatic("samples/common/meshes/statue.mesh");
  // 释放脚本所有权并将引擎编辑器设置为一个新的所有者
  engine.editor.addNode(node_remove(mesh));

• void node_delete(Node node)删除父节点及子节点。在调用此函数之前，应为脚本附加此节点以此获得所有权。
  源代码 (UnigineScript)

  // 加载节点。此节点会自动为脚本所拥有。
  Node node = engine.world.loadNode("my.node");
  
  // ...
  // 释放节点的脚本所有权
  
  // 将孤行子节点添加到加载的节点上
  node.addChild(class_remove(new NodeDummy()));
  // 为节点及子节点设置脚本所有权
  node_append(node);
  
  // 在此处执行某些操作
  
  // 删除节点及子节点
  node_delete(node);

  此处删除节点及子节点。
  注意

  专门创建示例中呈现的场景这样才能显示出node_delete()删除了整个节点层。因此在应用程序内添加一个子节点之前不必调用class_remove()。
• Node node_clone(Node node)克隆此节点。因此创建一个新的内部C++类实例。如其它所有clone()函数，创建的实例会被进行孤行处理且其所有权会被传给某个模块。例如当节点为拥有实体和结合点的对象时，此函数就很有用。通常使用的clone() 函数并不能创建连接的结合点。
  源代码 (UnigineScript)

  // 创建一个自动为脚本所有的节点
  ObjectMeshStatic mesh = new ObjectMeshStatic("samples/common/meshes/statue.mesh");
  // 为克隆节点设置脚本所有权
  node_append(node_clone(mesh));

  此处由于使用new运算符来创建第一幅网格对象，因此其会自动为脚本所拥有，而拷贝的网格对象应进行手动附加的操作。

  用于非层节点的函数：

• Node node_cast(Node node) 让您可以安装安全的方式将所给的基础节点转换为派生类型节点。
  注意

  在转化为另一种类型时，并不会构建一种新的内部实例，因此无法使用delete运算符对其进行删除。
  源代码 (UnigineScript)

  // 获取一个节点，此节点会自动为脚本所有
  Node node = engine.world.getNode(id);
  // 将节点强制转换成ObjectMeshStatic类型
  ObjectMeshStatic mesh = node_cast(node);
  //调用ObjectMeshStatic类成员函数
  int num_targets = mesh.getNumSurfaceTargets(0);

  向下转换之后，节点可调用ObjectMeshStatic 类成员函数。 如果要通过delete运算符将上述实例中阐述的网格删除，会发生错误因为并无这样额内部实例。然而如果删除此节点，此网格也同样会被删除。

内部实例的所有权可在脚本之间进行传递：世界对象脚本，系统脚本和编辑器脚本。对于将要交互的脚本，使用下列函数：

• engine.world.call()中的一个函数用来调用世界脚本的函数。
• engine.system.call() 中的一个函数用来调用系统脚本的函数。
• engine.editor.call()中的一个函数用来调用编辑器脚本的函数。

例如您可以在世界脚本中创建一个内部实例接下来将此实例的所有权传递给系统脚本：

1. 在世界脚本中创建一个实例并释放此对象的世界脚本所有权，这样系统脚本才能抓取此对象的所有权。接下来通过engine.system.call()函数将此对象传递给系统脚本函数。
   源代码 (UnigineScript)

   int init() {
   	
   	// 1. 创建一个新的虚拟对象。此虚拟对象所指向的内部实例将自动得以创建
   	ObjectDummy dummy = new ObjectDummy();
   	// 2. 释放此对象的世界脚本所有权
   	class_remove(dummy);
   	// 3. 将此对象传递给系统脚本函数
   	engine.system.call("receive_dummy_ownership",dummy);
   	
   	return 1;
   }

2. 在系统脚本函数中，为所接收的孤行实例设置系统脚本所有权。现在可使用delete运算符删除此实例；否则此实例将在系统脚本关机时被自动删除。
   源代码 (UnigineScript)

   void receive_dummy_ownership(ObjectDummy dummy) {
   	// 1. 设置在世界脚本中构建的虚拟对象系统脚本所有权
   	class_append(dummy);
   	
   	// 2. 系统脚本可删除虚拟对象指向的内部实例，或者此实例会在系统脚本关机时被删除
   	delete dummy;
   }

首选如下：使用世界对象脚本创建并处理的节点被传递给接收智能指针的C++函数。

1. 在C++上创建一个自定义函数用来接收NodePtr智能指针。接下来随同Unigine解析器一同对此函数进行注册，这样脚本才能在运行期间调用此函数。
   源代码 (C++)

   //main.cpp
   #include <UnigineEngine.h>
   #include <UnigineInterpreter.h>
   #include <UnigineInterface.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   
   // 1. 创建一个用来接收智能指针NodePtr的外部函数
   void my_node_set(NodePtr node) {
   	// 1.1. 通过C++API调用节点成员函数
   	node->setTransform(translate(vec3(1.0f,2.0f,3.0f)));
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. 将函数注册以便能导出到Unigine
   	Interpreter::addExternFunction("my_node_set",MakeExternFunction(&my_node_set));
   	
   	// 3. 将引擎初始化，会自动将引擎关闭
   	EnginePtr engine(UNIGINE_VERSION,argc,argv);
   	
   	// 4. 进入引擎主循环
   	engine->main();
   	
   	return 0;
   }

2. 在世界对象脚本张创建一个节点并调用C++函数。节点的所有权属于脚本，因此仅脚本能调用delete运算符来销毁此节点。
   源代码 (UnigineScript)

   // 世界对象脚本 (myworld.cpp)
   
   int init() {
   	// 1.创建一个新的虚拟对象，这样才能将此对象传递给外部C++函数
   	Node node = new NodeDummy();
   	// 2. 调用注册的C++函数
   	my_node_set(node);
   	
   	// 3. 在不需要此节点时删除此节点，否则在关闭脚本时会自动删除此节点
   	delete node;
   
   	return 1;
   }

这种情况下，节点会被传递给一个C++函数，此函数接收此节点并将其作为一个智能指针并且此函数会获取此节点的所有权，这样函数才会对节点的删除负责。

1. 在C++上创建一个自定义函数用来接收NodePtr智能指针并获取其所有权。接下来随同Unigine解析器一同对此函数进行注册，这样脚本才能在运行期间调用此函数。
   源代码 (C++)

   #include <UnigineEngine.h>
   #include <UnigineInterpreter.h>
   #include <UnigineInterface.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   
   // 1. 创建用来接收脚本节点并将此节点作为智能指针NodePtr的外部函数
   void my_node_set(NodePtr node) {
   	
   	// 1.1. 获取此接收指针的所有权
   	node->grab();
   	
   	// 1.2. 通过C++API调用节点成员函数
   	node->setTransform(translate(dvec3(1.0f,2.0f,3.0f)));
   	
   	// 1.3. 在有必要的情况下删除此节点
   	node->destroy();
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. 注册此函数以便能导入到Unigine中
   	Interpreter::addExternFunction("my_node_set",MakeExternFunction(&my_node_set));
   	
   	// 3. 初始化引擎。此引擎会被自动关闭
   	EnginePtr engine(UNIGINE_VERSION,argc,argv);
   	
   	// 4. 进入引擎主循环
   	engine->main();
   	
   	return 0;
   }

2. 在世界对象脚本张创建一个节点，释放脚本所有权并调用注册的C++函数。节点的所有权属于外部函数，因此不必调用delete运算符来销毁此节点。
   注意

   Script ownership must be released either on the script or C++ side. Otherwise, there will be 2 owners of the node and it will cause engine crash.
   源代码 (UnigineScript)

   int init() {
   		
   	// 1. 创建一个新的虚拟对象，这样才能将此对象传递给C++函数
   	Node node = new NodeDummy();
   	// 2. 释放脚本所有权这样此所有权才能被C++函数获取
   	class_remove(node);
   	// 3. 调用注册的C++函数
   	my_node_set(node);
   	// 4. 检查函数执行结果
   	log.message("%s\n",typeinfo(node.getTransform()));
   	
   	return 1;
   }

此变体与第一种类型相似：世界对象坐标创建并处理的节点会被传递给C++函数，此函数接收此节点并将其作为某种特定类型的智能指针。此处的“某种特定类型”指C++API类，此类被智能指针所包住(例如ObjectMeshStaticPtr， DecalDefferedMeshPtr等等)。

1. 在C++上创建一个自定义函数，用来接收ObjectMeshDynamicPtr智能指针。应对外部函数进行注册以供脚本调用。
   源代码 (C++)

   //main.cpp
   #include <UnigineEngine.h>
   #include <UnigineInterpreter.h>
   #include <UnigineObjectMeshDynamic.h>
   #include <UnigineInterface.h>
   #include <UnigineLog.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   // 1.0. 创建用于接收智能指针ObjectMeshDynamicPtr的外部函数
   void my_object_update(ObjectMeshDynamicPtr object,float time) {
   	
   	// 1.1. 调用ObjectMeshDynamic的成员函数
   	object->updateSurfaceBegin(0);
   	object->updateSurfaceEnd(0);
   	Log::message("Surface indices was updated\n");
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. 将函数注册以便能导出到Unigine
   	Interpreter::addExternFunction("my_object_update",MakeExternFunction(&my_object_update));
   	
   	// 3. 初始化引擎。此引擎会被自动关闭
   	EnginePtr engine(UNIGINE_VERSION,argc,argv);
   	
   	// 4. 进入引擎主循环
   	engine->main();
   	
   	return 0;
   }

2. 在脚本上创建一个对象并将此对象传递给外部函数。此后在使用脚本调用时，注册的外部C++函数调用会对其进行接收。通过脚本所有权得以保留，因此脚本可删除此对象。
   源代码 (UnigineScript)

   // 世界对象脚本(myworld.cpp)
   
   int init() {
   	// 1. 创建一个新的ObjectMeshDynamic
   	Object object = new ObjectMeshDynamic();
   	// 1.1. 调用成员函数
   	object.setMaterial("mesh_base","*");
   
   	// 3. 调用注册的外部C++函数
   	my_object_update(object,engine.game.getTime());
   	
   	// 4. 脚本可删除此对象，因为脚本对此对象进行分配
   	delete object;
   
   	return 1;
   }

第三种变体便是在脚本中创建内部实例(例如图像)并将此实例传递给C++函数，此函数用来接收一个变量。其后使用脚本调用外部函数。

1. 在C++上创建一个自定义函数用来就收一个变量。使用专用函数getImage()将此变量强制转换成ImagePtr智能指针类型。此后应将C++函数注册以便脚本能够进行调用。
   注意

   在调用 getImage()函数时，应设置脚本运行时间：通过Unigine::Interpreter::get()函数将指针传递给当前解译器。
   源代码 (C++)

   //main.cpp
   #include <UnigineEngine.h>
   #include <UnigineInterpreter.h>
   #include <UnigineImage.h>
   #include <UnigineInterface.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   // 1. 创建接收变量的外部函数
   const char* my_image_get(const Variable &v) {
   
   	// 1.1. 将接收的变量强制转换为ImagePtr类型
   	ImagePtr image = v.getImage(Interpreter::get());
   	
   	// 1.2. 通过C++ API调用图像成员函数
   	return image->getFormatName();
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. 将函数注册以便能导出到Unigine
   	Interpreter::addExternFunction("my_image_get",MakeExternFunction(&my_image_get));
   	
   	// 3. 初始化引擎。此引擎会被自动关闭
   	EnginePtr engine(UNIGINE_VERSION,argc,argv);
   	
   	// 4. 进入引擎主循环
   	engine->main();
   	
   	return 0;
   }

   使用VariableToType() 函数，还有另一种方法将此变量强制转换为图像指针类型

   源代码 (C++)

   //main.cpp
   ...
   // 1. 相同的外部函数
   const char* my_image_get(const Variable &v) {
   
   	// 1.1. 将变量强制转换为ImagePtr类型的另一种方法：
   	ImagePtr image = VariableToType<ImagePtr>(Interpreter::get(),v).value;
   
   	return image->getFormatName();
   }
   ...

2. 在脚本内，需创建图像并将此图像传递给C++函数。图像将自动被转换为ImagePtr智能指针类型。
   源代码 (UnigineScript)

   //世界对象脚本(myworld.cpp)
   int init() {
   
   	// 1. 创建一副新图像
   	Image image = new Image();
   	// 1.1. 指定图像参数并使用黑色进行填充
   	image.create2D(256,256,IMAGE_FORMAT_R8);
   	
   	// 2. 调用注册的外部函数并将此图像传递给函数
   	my_image_get(image);
   	
   	// 3. 在有必要的情况下，脚本可以外显的方式删除此图像
   	delete image;
   	
   	return 1;
   }

智能指针不仅能让C++函数接收由脚本创建的内部C++类的实例还可以创建这样的实例。

此处脚本调用一种外部函数，使用ImagePtr创建一副新的图像。

1. 在外部C++函数中，阐明ImagePtr，调用API函数的create()并将此指针传递给脚本。然而如果仅进行了指针的传递，此指针会一直处于悬挂摇摆状态，即其不会指向有效图像对象因为此对象在外部函数范围外不可见。为避免这种情况，应通过release() 函数将此指针的所有权传递给脚本。接着将自定义的函数注册以供脚本调用。
   源代码 (C++)

   //main.cpp
   #include <UnigineEngine.h>
   #include <UnigineInterpreter.h>
   #include <UnigineImage.h>
   #include <UnigineInterface.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   
   // 1. 创建会返回ImagePtr智能指针的外部函数
   ImagePtr my_image_create_0() {
   	// 1.1. 声明一个图像智能指针
   	ImagePtr image;
   	
   	// 1.2. 通过ImagePtr智能指针在Unigine内存池中创建一副图像
   	image = Image::create();
   	// 1.3. 指定图像参数并使用黑色进行填充
   	image->create2D(128,128,Image::FORMAT_RG8);
   	// 1.4. 将指针的所有权传递给脚本
   	image->release();
   	
   	return image;
   }
   
   /*
    */
   int main(int argc,char **argv) {
   	
   	// 2. 将函数注册以便能导出到Unigine
   	Interpreter::addExternFunction("my_image_create_0",MakeExternFunction(&my_image_create_0));
   	
   	// 3. 初始化引擎。此引擎会被自动关闭
   	EnginePtr engine(UNIGINE_VERSION,argc,argv);
   	
   	// 4. 进入引擎主循环
   	engine->main();
   	
   	return 0;
   }

2. 调用注册的C++函数。此函数返回的图像可被简单地传递给脚本，因为将自动完成将ImagePtr转换成Image的过程。由于图像的所有权已从外部函数传递给脚本，因此可随时使用脚本删除此图像（或者在引擎关闭时自动删除此图像）。
   源代码 (UnigineScript)

   //world script (myworld.cpp)
   int init() {
   	
   	// 1. 调用脚本中的外部函数
   	Image image = my_image_create_0();
   	// 2. 为图像设置脚本的所有权
   	class_append(image);
   	
   	// 3. 脚本会自动处理由C++函数作为一副简单图像返回的ImagePtr
   	log.message("%s\n",image.getFormatName());
   
   	// 4. 在有必要的情况下删除此图像
   	delete image;
   	
   	return 1;
   }

在此变体中，外部函数创建一副新的图像作为一个变量接下来脚本会调用此外部函数。

1. 在C++函数内，声明一个ImagePtr，调用API函数的create() 来创建一个智能指针，此指针会分配一副Unigine内部图像并使用专用函数setImage()将此图像设置到变量中。
   注意

   在调用setImage()函数时，应设置脚本运行时间，通过Unigine::Interpreter::get() 函数将此指针传递给当前解译器。 。
   源代码 (C++)

   //main.cpp
   #include <UnigineEngine.h>
   #include <UnigineInterpreter.h>
   #include <UnigineImage.h>
   #include <UnigineInterface.h>
   
   /*
    */
   using namespace Unigine;
   
   /*
    */
   
   // 1. 创建一个返回变量的外部函数
   Variable my_image_create_1() {
   	// 1.1. Declare an image smart pointer
   	ImagePtr image;
   	
   	// 1.2. 在Unigine内存池中创建一副图像
   	image = Image::create();
   	// 1.3. 指定图像参数并使用黑色进行填充
   	image->create2D(128,128,Image::FORMAT_RG8);
   	
   	// 1.4. 定义变量
   	Variable v;
   	// 1.5. 将图像智能指针设置到变量上
   	v.setImage(Interpreter::get(),image);
   	
   	return v;
   }
   
   /*
    */
   int main(int argc,char **argv) {
   
   	// 2. 注册此函数以便能导入到Unigine中
   	Interpreter::addExternFunction("my_image_create_1",MakeExternFunction(&my_image_create_1));
   	
   	// 3. 初始化引擎。此引擎会被自动关闭
   	EnginePtr engine(UNIGINE_VERSION,argc,argv);
   	
   	// 4. 进入引擎主循环
   	engine->main();
   	
   	return 0;
   }

   另一种将ImagePtr智能指针设置到变量上的方法会使用到 TypeToVariable函数：

   源代码 (C++)

   //main.cpp
   ...
   // 1. 相同的外部函数
   Variable my_image_create_1() {
   	
   	image = Image::create();
   	image->create2D(128,128,Image::FORMAT_RG8);
   
   	// 1.3. 将图像智能指针设置到变量上的另一种方法：
   	Variable v = TypeToVariable<ImagePtr>(Interpreter::get(),image).value;
   	
   	return v;
   }
   ...

2. 脚本调用注册的C++函数。此后由于自动完成了转换过程，因此脚本会将返回的变量作为简单图像进行处理。记住脚本无法删除图像，因为图像的所有权属于外部函数。当参考计数达到0时，智能指针会自动得到释放。
   源代码 (UnigineScript)

   //world script (myworld.cpp)
   int init() {
   	
   	// 1. 调用脚本中的外部函数
   	Image image = my_image_create_1();
   	
   	// 2. 脚本会自动处理作为简单图像而得以返回的ImagePrt
   	log.message("%s\n",image.getFormatName());
   	
   	return 1;
   }