1. Basic Concepts

Development of a project starts from creating it using SDK Browser. Follow the Creating a C++ Application article or the video tutorial below to create a new C++ project.

After configuring the development environment you can proceed to learning the basic concepts of the engine.

See Also

Basic Scene Objects

Coordinate System

Additional information:

• For more information on UNIGINE node types, see Built-in Node Types page.
• For more information on managing nodes via API, see Nodes classes page.

Printing messages to the log file and console helps to monitor overall progress of execution of your application and report errors which can be used in debugging. Log class makes it possible to print formatted string messages to the log file and the console. The code below demonstrates how to print various types of messages:

using namespace Unigine;

// auxiliary variables for messages
char *file_name = "file.txt";
int ID = 10;
	
// reporting an error message
Log::error("Loading mesh: can't open \"%s\" file\n", file_name);

// reporting a message
Log::message("-> Added %d UI elements.\n", 10);
	
// reporting a warning message
Log::warning("ID of the \"%s\" file: %d.\n", file_name, ID);
	
// reporting a fatal error message to the log file and closing the application
Log::fatal("FATAL ERROR reading \"%s\" file!\n", file_name);

Additional information:

• For more information on the console, see Console page.
• For more information on the Log class, see Log class page.

Some applications manage a single world, while other require several worlds to be managed. In any case, it is very useful to know how to save our current world and load some other. In order to solve this task, we should use the World class, which is designed as a singleton.

#include <UnigineWorld.h>

using namespace Unigine;
/* .. */

// loading world from the my_world.world file
World::loadWorld("my_world");

We can also do the same via the console by using the Console class, which is also designed as a singleton.

#include <UnigineConsole.h>

using namespace Unigine;
/* .. */

// saving current world to the my_world.world file
Console::run("world_save my_world");

// loading world from the my_world.world file
Console::run("world_load my_world");

Additional information:

• For more information on managing worlds via API, see World class page.
• For more information on the console and available commands, see Console page.
• For more information on managing the console via API, see Console class page.
• For more information on managing world nodes that are to be saved via API, see the methods of the Node class.

Any application needs to be closed at some moment. To close your application as well as to manage its window parameters, controls events, etc. you should use App class.

To close the application the following code is to be used:

#include <UnigineApp.h>
using namespace Unigine;

/* .. */
		
// closing the application 
App::exit();

Additional information:

• For more information on managing the application via API, see App class page.

In UNIGINE, instances of C++ API classes (such as: node, mesh, body, image, etc.) only store pointers to instances of internal C++ classes, they cannot be created and deleted via the standard new/delete operators. So they should be declared as smart pointers (Unigine::Ptr) that allow you to automatically manage their lifetime. UNIGINE has its own optimized memory allocator for faster and more efficient memory management.

To create an instance of an internal class we should declare a smart pointer for the class we are going to instantiate and call the create() method - class constructor - providing construction parameters if necessary.

// instantiating an object of an internal class
<Class>Ptr instance = <Class>::create(<construction_parameters>);

All objects are divided into two groups regarding the way their lifetime is managed:

• ownership objects
• non-ownership objects

Ownership Objects#

// creating a new image
ImagePtr img = Image::create();

// now two pointers point to our image (reference counter increment)
ImagePtr img2 = img;

// removing the image (as both pointers no longer point to it and reference counter is zero)
img2 = img = nullptr;

// another way to clear pointers
img.clear();
img2.clear();

Non-Ownership Objects#

NodePtr node;
void somefunc1(){
// creating a new dummy node
node = NodeDummy::create();
}

void somefunc2(){
// checking whether the node exists
if (node)
Log::message("The node is alive\n");

// deleting the node
node.deleteLater();
}

NodePtr node = NodeDummy::create();
NodePtr node2 = NodeDummy::create();

// the node shall be deleted on world shutdown
node->setLifetime(Node::LIFETIME_WORLD);
// the node2 shall remain alive even when another world is loaded
node2->setLifetime(Node::LIFETIME_ENGINE);

Additional information:

• For more information on managing smart pointers, see Working with Smart Pointers page.
• For more information on ownership management, see Memory Management page.

PROCEED TO THE NEXT SECTION >>