API Migration

Working with Engine’s singletons has become safer and simpler. Previously, to access their functionality, you would first type get() before specifying the desired method. This was not thread safe, as calling get() methods from several threads could potentially lead to initialization issues. Now the functionality of Engine’s singletons is accessed via static methods of the corresponding class, improving thread safety, as well as reducing the number of symbols and making your code look better:

Earlier Versions

float ifps = Game::get()->getIFps();

// ...
Physics::get()->setGravity(vec3(0.0f, 0.0f, -9.8f * 2.0f));
Physics::get()->setFrozenLinearVelocity(0.1f);

2.10

float ifps = Game::getIFps();

// ...
Physics::setGravity(vec3(0.0f, 0.0f, -9.8f * 2.0f));
Physics::setFrozenLinearVelocity(0.1f);

Please mind the following exceptions, that are operated as before via the get() method:

• Engine class in C++ API (in C# it is also static).
• Gui class as it may be both a singleton as well as not a singleton.

The App class was previously used to control Unigine application (change window parameters, manage graphic context and keyboard/mouse events, etc.) as well as to create a custom user application by inheriting a new class from it.

To make the functions more distinct and manage them clearly, we‘ve split this functionality into two classes:

• App class - used to control your application;
• CustomApp class - used to create custom user applications via inheriting from it and implementing necessary functionality.

Historically node management (i.e. finding, adding, removing nodes, etc.) was performed by the Editor class, which was sometimes confusing for new users. For example, in order to be able to find a node by its name, you’d first have to add it to the Editor (even if you think you don’t actually use it).

To make node management process clearer we removed this functionality from the Editor class (it does not manage nodes anymore) and passed it to the World class, as you usually add nodes to a world and remove them from it.

So, now all new nodes are added to the current world, and you can find them via the corresponding method of the World class without any additional operations:

2.8 and Earlier Versions

// creating a player and setting its name
PlayerSpectatorPtr spectator = PlayerSpectator::create();
spectator->setName("my_player");


// adding the node to the Editor
spectator->release();
Editor::get()->addNode(spectator->getNode());

// trying to find our node by its name
NodePtr node = Editor::get()->getNodeByName("my_player");

// deleting a node with all its hierarchy
Editor::get()->removeNode(node);

// -------------------------------------------
// a case of managing nodes without the Editor
class SomeClass
{
public:
    SomeClass()
    {
        dummy = ObjectDummy::create();
        //...
    }

private:
    ObjectDummyPtr dummy;
    // ...
};

2.10

// creating a player and setting its name
PlayerSpectatorPtr spectator = PlayerSpectator::create();
spectator->setName("my_player");

// trying to find our node by its name
NodePtr node = World::getNodeByName("my_player");

// deleting a node with all its hierarchy
node.deleteLater();

// -------------------------------------------
// a case of managing nodes without the Editor
class SomeClass
{
public:
    SomeClass()
    {
        dummy = ObjectDummy::create();
        // ...
    }

    ~SomeClass()
    {
       // explicit deletion is required
        dummy.deleteLater();
        // ...
    }

private:
    ObjectDummyPtr dummy;
    // ...
};

// creating a player and setting its name
PlayerSpectatorPtr spectator = PlayerSpectator::create();
spectator->setName("my_player");

// trying to find our node by its name
NodePtr node = Editor::get()->getNodeByName("my_player");

// deleting a node with all its hierarchy
Editor::get()->removeNode(node);

// creating a player and setting its name
PlayerSpectatorPtr spectator = PlayerSpectator::create();
spectator->setName("my_player");

// trying to find our node by its name
NodePtr node = World::getNodeByName("my_player");

// deleting a node with all its hierarchy
node.deleteLater();

All methods related to node management were removed from the Editor class, with the following ones transferred to the World class:

• clearBindings()
• getNodeByName()
• getNodesByName()
• getNodeById()

The following stages of the Main Loop were renamed for better understanding:

• render() -> postUpdate()
• flush() -> updatePhysics()
• destroy() -> destroyRenderResources()

UNIGINE’s smart pointers were significantly refactored in order to avoid dangling pointers, unexpected object deletions (e.g. when getting out of scope) as well as double deletions (in case an object has more than one owner) leading to crashes.

2.8 and Earlier Versions

Vector<PlayerPtr> players;

void createMyActor()
{
  PlayerActorPtr actor = PlayerActor::create();
  players.append(actor->getPlayer());

  // this pointer (in the players vector) will be bad after leaving the scope
}

void createMySpectator()
{
  PlayerSpectatorPtr spectator = PlayerSpectator::create();
  spectator->release();
  PlayerPtr player = spectator->getPlayer();
  player->grab();
  players.append(player);
  // this pointer (in the players vector) will be ok after leaving the scope
}

2.10

Vector<PlayerPtr> players;

void createMySpectator()
{
    players.append(PlayerSpectator::create());
}

void createMyActor()
{
    players.append(PlayerActor::create());
}

// all pointers in the players vector will be ok after leaving the scopes

UNIGINE’s smart pointers are based on reference counting. We can now divide all objects into two groups regarding the way their lifetime is managed:

• ownership objects (Image, Texture, Mesh, Tileset, etc.) these objects are managed in accordance with reference counter, as it was before: the object is deleted as the counter reaches zero (if the object is owned by the pointer). In this case it is assumed that the object is no longer needed (the Engine doesn’t know anything about it, and the user has got no pointer to be able to use it) and, therefore, it is deleted. (e.g. such objects declared within a scope will be automatically deleted when leaving the scope).
• non-ownership objects (Node, Widget, Material, Property, etc.) - these objects interact with the Engine and become managed by it since the moment of their creation (they are engaged in the main loop, can be retrieved by names, etc.). The lifetime of these objects is not determined by the reference counter, they provide the mechanism of weak references, so you can check whether an object was deleted or not. To delete such objects you should use deleteLater() or a corresponding manager’s method (e.g.: Materials::removeMaterial()).

NodePtr node1;
NodePtr node2;
init()
{
  node1 = World::getNodeByName("my_player");
  node2 = World::getNodeByName("my_player");
  node1.deleteLater();
}

void update()
{
  if (node2 == nullptr)
    Log::message("my_player is deleted"); // no dangling pointer
}

Instead of managing references for nodes manually, now you can simply choose lifetime management policy for it:

• World-lifetime - in this case a node has the same lifetime as the world, and shall be deleted when the world is closed. This policy is used by default for each new node.
• Engine-lifetime - in this case a node has the same lifetime as the Engine, and shall be deleted automatically on Engine shutdown (can be used for nodes that should be kept when changing worlds).
  Source code (C++)

  // loading a node from a file (by default its lifetime is the same as the lifetime of the current world)
  NodePtr node = World::loadNode("mynode.node");
  
  // changing node's lifetime to Engine to prevent its deletion when changing worlds
  node->setLifetime(Node::LIFETIME_ENGINE);

Lifetime of each node in the hierarchy is defined by its root (either parent or possessor). Setting lifetime management type for a child node different from the one set for the root has no effect.

Deleting Objects#

Multithreading#

Upcasting and Downcasting#

PlayerPersecutorPtr player = PlayerPersecutor::create();
Game::get()->setPlayer(player->getPlayer());

// ------------
gui->addChild(widget_button->getWidget(), Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

// ------------
ObjectMeshDynamicPtr OMD;
BodyRigidPtr body = BodyRigid::create(OMD->getObject());
body->addShape(ShapeBox::create(size)->getShape(), translate(vec3(0.0f)));

PlayerPersecutorPtr player = PlayerPersecutor::create();
Game::setPlayer(player);

// ------------
gui->addChild(widget_button, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

// ------------
ObjectMeshDynamicPtr OMD;
BodyRigidPtr body = BodyRigid::create(OMD);
body->addShape(ShapeBox::create(size), translate(vec3(0.0f)));

PlayerPtr camera= Player::cast(Editor::getNodeByName("main_camera"));
camera->setFov(60.0f);

if(stream->getType() == Stream::FILE)
    FilePtr file = File::cast(stream);

PlayerPtr camera = checked_ptr_cast<Player>(World::getNodeByName("main_camera"));
camera->setFov(60.0f);

if(stream->getType() == Stream::FILE)
    FilePtr file = static_ptr_cast<File>(stream);

NodePtr node1 = World::getNodeByName("my_player");
NodePtr node2 = World::getNodeByName("my_player");
assert(node1.get() == node2.get());

void foo(PlayerPtr);
foo(PlayerPtr());

void foo(PlayerPtr);
foo(nullptr);

Apart from setting lifetime management policy, you can also choose for each node whether it should be displayed in the Editor’s hierarchy or saved to a *.world file by simply setting the corresponding flags: ShowInEditorEnabled (instead of calling Editor::addNode(node, is_runtime)) and SaveToWorldEnabled (instead of setting is_runtime = 0). By default both these options are disabled.

2.8 and Earlier Versions

// create a static mesh
ObjectMeshStaticPtr mesh = ObjectMeshStatic::create("my_mesh.mesh");

// assign a material to the mesh
mesh->setMaterial("mesh_base","*");

// adding the node to the Editor to display it in the World Hierarchy
// and setting is_runtime = 0 to enable saving the node to a .world file
mesh->release();
Editor::get()->addNode(mesh->getNode(), 0);

// change the node name
mesh->setName("my_node");
// change node transformation
mesh->setWorldTransform(translate(Vec3(0.0f, 0.0f, 2.0f)));

// save node changes in the .world file
Console::get()->run("world_save");

// delete the static mesh node
Editor::get()->removeNode(mesh->getNode());

2.10

// create a static mesh
ObjectMeshStaticPtr mesh = ObjectMeshStatic::create("my_mesh.mesh");

// assign a material to the mesh
mesh->setMaterial("mesh_base","*");

// enable saving the node to a .world file
mesh->setSaveToWorldEnabled(true);

// enable showing the node in the Editor’s World Hierarchy
mesh->setShowInEditor(true);

// change the node name
mesh->setName("my_node");
// change node transformation
mesh->setWorldTransform(translate(Vec3(0.0f, 0.0f, 2.0f)));

// save node changes in the .world file
Console::run("world_save");

// delete the static mesh node
mesh.deleteLater();

// create a static mesh
ObjectMeshStaticPtr mesh = ObjectMeshStatic::create("my_mesh.mesh");

// assign a material to the mesh
mesh->setMaterial("mesh_base","*");

// releasing the node (as it was added with is_runtime = 1 on creation)
// and adding it to the Editor again with is_runtime = 0 to display it
// in the World Hierarchy and enable saving the node to a .world file
Editor::get()->releaseNode(mesh->getNode());
Editor::get()->addNode(mesh->getNode(), 0);

// change the node name
mesh->setName("my_node");
// change node transformation
mesh->setWorldTransform(translate(Vec3(0.0f, 0.0f, 2.0f)));

// save node changes in the .world file
Console::get()->run("world_save");

// delete the static mesh node
Editor::get()->removeNode(mesh->getNode());

// create a static mesh
ObjectMeshStaticPtr mesh = ObjectMeshStatic::create("my_mesh.mesh");

// assign a material to the mesh
mesh->setMaterial("mesh_base","*");

// enable saving the node to a .world file
mesh->setSaveToWorldEnabled(true);

// enable showing the node in the Editor’s World Hierarchy
mesh->setShowInEditor(true);

// change the node name
mesh->setName("my_node");
// change node transformation
mesh->setWorldTransform(translate(Vec3(0.0f, 0.0f, 2.0f)));

// save node changes in the .world file
Console::run("world_save");

// delete the static mesh node
mesh.deleteLater();

Earlier deleting a root of the hierarchy didn’t affect children, leading to memory leaks. So, in order to remove large hierarchies of objects (e.g., created via World::loadNode()) or widgets, you had to either manually delete all children recursively, or use the Editor class (in case of nodes).

Now, all child nodes and widgets are deleted automatically when deleting their parent, so you don’t have to manage hierarchies manually. Moreover, all created widgets are automatically deleted on Engine’s shutdown, so there will be no more annoying messages about widgets and related memory leaks.

2.8 and Earlier Versions

// ------------------- NODES -------------------------------------

// loading a node from a file and passing it to the Editor
NodePtr node = World::get()->loadNode("my_node.node");
node->release(); 
Editor::get()->addNode(node);

// deleting a node with all its hierarchy
Editor::get()->removeNode(node);

// ------------------- WIDGETS -------------------------------------
// creating widgets
gui = Gui::get();
label = WidgetLabel::create(gui);
button = WidgetButton::create(gui, "BUTTON");
label->setPosition(10, 10);
button->setPosition(10, 240);

gui->addChild(label->getWidget(), Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);
gui->addChild(button->getWidget(), Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

// removing widgets
button.clear();
editline.clear();
window.clear();

2.10

// ------------------- NODES -------------------------------------
// loading a node from a file
NodePtr node = World::loadNode("my_node.node");

// deleting a node with all its hierarchy
node.deleteLater();

// ------------------- WIDGETS -------------------------------------
// creating widgets
gui = Gui::get();
label = WidgetLabel::create(gui);
button = WidgetButton::create(gui, "BUTTON");
label->setPosition(10, 10);
button->setPosition(10, 240);

gui->addChild(label, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);
gui->addChild(button, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

// all widgets are removed automatically

// ------------------- NODES -------------------------------------

// loading a node from a file
NodePtr node = World::get()->loadNode("my_node.node");

// deleting a node with all its hierarchy
Editor::get()->removeNode(node);

// ------------------- WIDGETS -------------------------------------
// creating widgets
gui = Gui::get();
label = WidgetLabel::create(gui);
button = WidgetButton::create(gui, "BUTTON");
label->setPosition(10, 10);
button->setPosition(10, 240);

gui->addChild(label->getWidget(), Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);
gui->addChild(button->getWidget(), Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

// removing widgets
button.clear();
editline.clear();
window.clear();

// ------------------- NODES -------------------------------------
// loading a node from a file
NodePtr node = World::loadNode("my_node.node");

// deleting a node with all its hierarchy
node.deleteLater();


// ------------------- WIDGETS -------------------------------------
// creating widgets
gui = Gui::get();
label = WidgetLabel::create(gui);
button = WidgetButton::create(gui, "BUTTON");
label->setPosition(10, 10);
button->setPosition(10, 240);

gui->addChild(label, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);
gui->addChild(button, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

// all widgets are removed automatically

A set of new classes and functions were added to improve synchronization in multithreaded applications:

• Added a set of atomic functions: AtomicCAS(), AtomicAdd(), AtomicSet(), and AtomicGet().
• Implemented exponential backoff mechanism for the SpinLock reducing the impact on CPU performance.
• Added a new Mutex class representing a simple mutex, based on atomic CAS and wrapping volatile int.
• AtomicLock operating with volatile int was replaced with the ScopedLock, based on the new simple mutex (Mutex).
• Added an RWMutex with write-preferred locking along with a couple of scoped locks for it (ScopedReaderLock and ScopedWriterLock).
• Added a new Atomic<T> class enabling to read and write the value atomically.
• Added a new ReentrantMutex, enabling a mutex to be locked multiple times by the same thread, without causing a deadlock along with a ScopedReentrantLock for it.

All engine plugins are now in the Unigine::Plugins namespace. Naming for header files of all plugins has changed:

Pointers to plugin interfaces can now be easily taken via the new Engine::getPlugin() method. Moreover, main classes of all plugins now have a static get() method that returns a pointer to the plugin interface. So, you don't have to get the interface via Engine::getPluginData() anymore.

// get plugin interface pointer and call a method
PluginClass *interface = Engine::get()->getPlugin<PluginClass>("PluginName");
interface->pluginMethod();

// or call plugin's method like this
Unigine::Plugins::PluginClass::get()->pluginMethod();

Earlier Versions

#include <plugins/LeapMotionInterface.h>
int init()
{
	// find LeapMotion plugin index
	int index = Engine::get()->findPlugin("LeapMotion");
	if (index == -1)
	{
		Log::error("LeapMotion isn't loaded!\n");
		return 1;
	}

	// get the LeapMotion interface
	leapmotion = (LeapMotionInterface*)Engine::get()->getPluginData(index);
	int images_count = leapmotion->getNumImages();

	return 1;
}

2.10

#include <plugins/UnigineLeapMotion.h>

int init()
{
	// get a pointer to the LeapMotion interface
	auto *leapmotion = Unigine::Plugins::LeapMotion::get();

	// if the plugin is loaded
	if (leapmotion)
	{
		int images_count = leapmotion->getNumImages();
		// ...
	}

	return 1;
}

Stronger typing promotes safer and more expressive code. So, we‘ve extended the use of enums and bool values instead of int values in C++ API.

Public API implementation of UnigineBounds is now the same as the internal one eliminating divergence.

The following workflow is recommended when migrating the code base of your projects to the new API:

• Replace all calls to methods of Engine’s singleton classes via the get() method with static ones (except for the Engine class in C++ API and the Gui class):

  Earlier Versions

  Source code (C++)

  float ifps = Game::get()->getIFps();
  Physics::get()->setFrozenLinearVelocity(0.1f);
  MaterialPtr mesh_base = Materials::get()->findBaseMaterial("mesh_base");
  // ...

  2.10

  Source code (C++)

  float ifps = Game::getIFps();
  Physics::setFrozenLinearVelocity(0.1f);
  MaterialPtr mesh_base = Materials::findBaseMaterial("mesh_base");
  // ...

• Replace all cast() methods of derived classes used for downcasting with the ones described above (checked, static, or dynamic).
• Remove all upcasting methods (e.g. getPlayer(), getWidget(), getObject(), etc.).
• Rename Main-Loop-related methods render(), flush(), and destroy() to postUpdate(), updatePhysics(), and destroyRenderResources() respectively.
• Replace int values returned and accepted by methods with enums and bool values where necessary.
• If you’re creating a custom user application, change the base class for your custom class to the CustomApp class, instead of the App.
• Get rid of all grab() and release() methods. The isOwner() method is unlikely to be useful either.
• You don't need the addNode() method of the Editor class anymore since all nodes are added to the world when created.
• Don't use the Editor's removeNode() and destroy(node). Instead, it's recommended to remove nodes via the deleteLater() method of the Ptr class.

The Component System does not remove components from nodes transferred between worlds anymore, as their lifetime is the same as the Engine’s (Lifetime == ENGINE).

You can now check the current Component System state (total number of components, nodes having components assigned, as well as methods registered for components) via the new ComponentSystem.GetStatistics() method.

Dispose pattern was implemented for each object (the Dispose() method) performing memory cleanup for Engine’s (native) resources.

A set of utilities enables you to get a pointer to a C++ object (GetPtr), check if an object exists (IsValidPtr) or was deleted with only a C# wrapper left (IsNullPtr).

Delayed object deletion is now available via the DeleteLater() method analogous to the C++ API.

Garbage Collector behavior (Engine.GCMode) has changed with a set of modes making garbage collection management more flexible. The following modes are available:

• DEFAULT (default) - default C# garbage collector mode. In this case heavy spikes and excessive memory consumption are imminent if you don’t manage your objects properly and do not use the Dispose() method.
• USE_MEMORY_PRESSURE - passes the information about C++ memory consumption to C#. This results in more frequent GC calls preventing the application from eating too much memory right after startup and removing heavy spikes.
• EVERY_FRAME - the garbage collector is called every frame. This results in overall performance reduction, but removes heavy spikes.
• WORLD_SHUTDOWN - the garbage collector is called on closing the world. This mode is ideal if the number of memory allocations is your code is insignificant.

class UnigineApp
{
  class AppSystemLogic : SystemLogic
  {
    // ...

    public override bool Init()
    {
      Engine.GCMode = Engine.GCMODE.EVERY_FRAME;
      // ...
      return true;
    }
    // ...
}

• setObject()