IG Application Template

Unigine IG uses Interpolated Snapshots (IS) to tackle with the problem of lost packets between the IG and hosts. It works by taking two old, but known positions and interpolating the object between them. It is accomplished by having a buffer of received positions and rotations, along with the time they represent. We usually take our current local time minus some predefined amount — interpolation period (40 ms by default), then go into our buffer, find the two indices that are just before and just after this time and interpolate.

If we don't have a received position and rotation for the time we're looking for, the extrapolation (guessing) is used. It also has a limited time — extrapolation period (200 ms by default). If the extrapolation period is over but there are still no packets received, all objects will freeze.

In most cases, this method provides a very accurate representation of the world to each slave, as in general only already known positions of remote objects are rendered and in rare cases the system will try to extrapolate (guess) where an object is. This, however, comes at a cost, as we always render 40 ms (interpolation period) behind current time, so that new packets have time to arrive with data.

• The IG plugin API section for more details on managing IG via code (C++).
• The Setting Up Properties article for more details on adjusting properties for new entities.
• The IG Configuration article for more details on setting up your IG.
• The Environment Settings article for more details on configuring sky and weather parameters.

A connector is actually a custom C++ Plugin used to communicate messages between the host and the IG. This plugin reads packages and calls the corresponding methods of the IG Plugin (listed in include/plugins/UnigineIG.h).

Files listed below can be used as a template for your custom connector:

• Plugin include file to be put to the include/plugins folder:

  CUSTOMConnectorInterface.h

  Source code (C++)

  #ifndef __CUSTOM_CONNECTOR_INTERFACE_H__
  #define __CUSTOM_CONNECTOR_INTERFACE_H__
  
  namespace IG
  {
  	namespace CUSTOM
  	{
  		class ConnectorInterface
  		{
  		public:
  			virtual ~ConnectorInterface() {}
  			
  			// client initialization
  			virtual int init(/*initialization parameters*/) = 0;
  			// client shutdown
  			virtual int shutdown() = 0;
  			
  			// other methods
  			// ...
  			
  			// callbacks
  			//virtual void setConnectCallback(Unigine::CallbackBase* func) = 0;
  			//virtual Unigine::CallbackBase* getConnectCallback() const = 0;
  			// ...
  		};
  	}
  }
  
  #endif /* __CUSTOM_CONNECTOR_INTERFACE_H__ */

• Plugin source files to be put to the source/custom_connector folder:

  CUSTOMConnectorPlugin.cpp

  Source code (C++)

  #include <UniginePlugin.h>
  
  #include "CUSTOMConnector.h"
  #include "CUSTOMConnectorInterpreter.h"
  
  using namespace Unigine;
  
  //////////////////////////////////////////////////////////////////////////
  // CUSTOMConnectorPlugin
  //////////////////////////////////////////////////////////////////////////
  
  class CUSTOMConnectorPlugin : public Plugin
  {
  public:
  	CUSTOMConnectorPlugin();
  	virtual ~CUSTOMConnectorPlugin();
  
  	const char *get_name() override;
  	void *get_data() override;
  
  	int init() override;
  	int shutdown() override;
  	void update() override;
  
  private:
  	IG::CUSTOM::Connector *connector;
  };
  
  CUSTOMConnectorPlugin::CUSTOMConnectorPlugin()
  	: connector(nullptr)
  {
  }
  
  CUSTOMConnectorPlugin::~CUSTOMConnectorPlugin()
  {
  	CUSTOMConnectorInterpreterShutdown();
  	delete connector;
  }
  
  const char *CUSTOMConnectorPlugin::get_name()
  {
  	return "CUSTOMConnector";
  }
  
  void *CUSTOMConnectorPlugin::get_data()
  {
  	return static_cast<IG::CUSTOM::ConnectorInterface *>(connector);
  }
  
  int CUSTOMConnectorPlugin::init()
  {
  	connector = new IG::CUSTOM::Connector();
  	connector->init();
  	CUSTOMConnectorInterpreterInit();
  	return 1;
  }
  
  int CUSTOMConnectorPlugin::shutdown()
  {
  	connector->shutdown();
  	return 1;
  }
  
  void CUSTOMConnectorPlugin::update()
  {
  	connector->update();
  }
  
  //////////////////////////////////////////////////////////////////////////
  // Plugin export
  //////////////////////////////////////////////////////////////////////////
  
  extern "C" UNIGINE_EXPORT void *CreatePlugin()
  {
  	return new CUSTOMConnectorPlugin();
  }
  
  extern "C" UNIGINE_EXPORT void ReleasePlugin(void *plugin)
  {
  	delete static_cast<CUSTOMConnectorPlugin *>(plugin);
  }

  CUSTOMConnector.h

  Source code (C++)

  #ifndef __CUSTOM_CONNECTOR_H__
  #define __CUSTOM_CONNECTOR_H__
  
  #include <plugins/CUSTOMConnectorInterface.h>
  #include <plugins/UnigineIG.h>
  #include <UnigineInterface.h>
  #include <UnigineLogic.h>
  
  namespace IG
  {
  namespace CUSTOM
  {
  	class CUSTOMWorldLogic;
  
  	class Connector : public ConnectorInterface
  	{
  	public:
  		Connector();
  		virtual ~Connector() {}
  		// singleton
  		static Connector *get() 
  		{
  			if (connector == nullptr)
  				Log::fatal("%s:: CUSTOM connector is NULL\n", __FUNCTION__);
  			return connector;
  		};
  
  		// automatic initialization on plugin load
  		void init();		
  
  		// update/shutdown client
  		void update();
  		void shutdown();
  		
  		// methods to be called by the CUSTOMWorldLogic class at the corresponding stages of the execution sequence
  		void onWorldInit();
  		void onWorldShutdown();
  	private:
  		static Connector *connector;
  		IG::Manager *ig_manager = nullptr;
  		CUSTOMWorldLogic *world_logic;
  	};
  	
  	// WorldLogic class
  	class CUSTOMWorldLogic : public Unigine::WorldLogic
  	{
  	public:
  		CUSTOMWorldLogic() {}
  		virtual ~CUSTOMWorldLogic() {}
  
  		virtual UNIGINE_INLINE int init() override { Connector::get()->onWorldInit(); return 1; }
  		virtual UNIGINE_INLINE int shutdown() override { Connector::get()->onWorldShutdown(); return 1; }
  	};
  }
  }
  
  #endif /* __CUSTOM_CONNECTOR_H__ */

  CUSTOMConnector.cpp

  Source code (C++)

  #include "CUSTOMConnector.h"
  #include <UnigineEngine.h>
  #include <UnigineNode.h>
  
  using namespace Unigine;
  using namespace Math;
  using namespace IG;
  using namespace CUSTOM;
  
  Connector::Connector() {
  	world_logic = new CUSTOMWorldLogic();
  	Engine::get()->addWorldLogic(world_logic);
  }
  
  void Connector::init()
  {
  	const auto host = "127.0.0.1";
  	const auto port = 3000;
  	
  	int ig_plugin_index = Engine::get()->findPlugin("IG");
  	if (ig_plugin_index == -1)
  	{
  		Log::error("IG::CUSTOM::Connector::init(): IG plugin isn't loaded\n");
  		return;
  	}
  	ig_manager = (IG::Manager*)Engine::get()->getPluginData(ig_plugin_index);
  	
  	// IG setup
  	ig_manager->setCoordinateSystem(IG::Manager::COORDINATE_SYSTEM::NED);
  	
  }
  
  void Connector::update()
  {
  	// read & write packets
  }
  
  void Connector::shutdown() 
  {
  	// shutdown client
  	shutdown();
  	
  	// clear static link
  	connector = nullptr;
  	
  	// ...
  }
  
  void Connector::onWorldInit() 
  {
  	// actions to be performed when a new world is loaded
  }
  
  void Connector::onWorldShutdown() 
  {
  	// actions to be performed when current world is closed
  }

  CUSTOMConnectorInterpreter.h

  Source code (C++)

  #ifndef __CUSTOM_CONNECTOR_INTERPRETER_H__
  #define __CUSTOM_CONNECTOR_INTERPRETER_H__
  
  #include <UnigineBase.h>
  
  void CUSTOMConnectorInterpreterInit();
  void CUSTOMConnectorInterpreterShutdown();
  
  #endif /* __CUSTOM_CONNECTOR_INTERPRETER_H__ */

  CUSTOMConnectorInterpreter.cpp

  Source code (C++)

  #include <UnigineEngine.h>
  #include <UnigineInterface.h>
  
  #include <plugins/CUSTOMConnectorInterface.h>
  #include "CUSTOMConnector.h"
  
  using namespace Unigine;
  using namespace IG;
  
  void CUSTOMConnectorInterpreterInit()
  {
  	int id = Interpreter::addGroup("CUSTOMConnectorInterpreter");
  
  	// defines
  	Interpreter::addExternDefine("HAS_CUSTOM_CONNECTOR", id);
  
  	// enums
  	// Interpreter::addExternVariable("CUSTOM_VERSION_10", MakeExternConstant<int>(CUSTOM_VERSION_10), id);
  
  	// functions
  	Connector *connector = Connector::get();
  	Interpreter::addExternLibrary("engine.custom", id);
  	//Interpreter::addExternFunction("engine.custom.init", MakeExternObjectFunction(connector, &Connector::init), id);
  	//Interpreter::addExternFunction("engine.custom.shutdown", MakeExternObjectFunction(connector, &Connector::shutdown), id);
  }
  
  void CUSTOMConnectorInterpreterShutdown()
  {
  	Interpreter::removeGroup("CUSTOMConnectorInterpreter");
  }

  CUSTOMConnectorWrapper.cpp

  Source code (C++)

  //push ignore deprecated warnings
  #ifdef __GNUC__
  #pragma GCC diagnostic push
  #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  #elif defined(_MSC_VER)
  #pragma warning(push)
  #pragma warning(disable: 4996)
  #endif
  
  #include <UnigineEngine.h>
  #include <plugins/CUSTOMConnectorInterface.h>
  
  using namespace Unigine;
  
  extern "C" 
  {
  	//UNIGINE_EXPORT void CUSTOMConnector_method(CUSTOMConnector *self) { if (self) self->method(); }
  }
  
  //pop ignore deprecated warnings
  #ifdef __GNUC__
  #pragma GCC diagnostic pop
  #elif defined(_MSC_VER)
  #pragma warning(pop)
  #endif