Programming
Fundamentals
Setting Up Development Environment
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Unigine::Syncker

Warning
Syncker system is deprecated and no longer supported. We can't guarantee the stable work of the system.

Syncker is a multi-node rendering system that makes it easy to create an immersive CAVE system or a large-scale visualization wall on a computer cluster synchronized over the network in real-time.

Simply connect multiple computers into one high-resolution seamless display using LAN. And it does not matter if these computers are running on Windows, Linux and Mac OS X at the same time, as Syncker works even across different platforms. Moreover, the created virtual environments can be of any monitor configuration, since all viewports are fully configurable.

Syncker

Computers in LAN connected via Syncker

See Also

Structure

Syncker allows you to render a world with a fixed FPS (by default, 60  FPS) across different computers synchronized over LAN. These computers can be of two types:

Master Master application is the main computer. This engine instance always renders the main viewport, and is not included into monitor configuration set up for CAVE rendering. Instead, its purpose is to perform calculation:
  • Nodes are moved according to the application logic.
  • Nodes are moved in the editor as the world is set up.

All other applications are synchronized with a master.
Slaves Slave applications are all other applications connected over the network. There can be an unlimited number of slaves connected to one master (as long as network bandwidth allows it). The purpose of such applications is to render all nodes that are seen in their viewports.
  • All rendering is done directly on a slave GPU.
  • Animations are updated on the master computer, while slaves only get calculated bone transformations.
  • Particles systems are updated on the slave but according to parameters sent from the master.
  • Physics in slave applications should be disabled not to override position and orientation of nodes sent over the network from a master.

Configuration of slaves is set up to fit positioned monitors.

Syncker Pipeline

To connect computers and synchronize them, the following pipeline is used.

  1. First, a master is sending broadcast messages that it is available using a UDP protocol.
  2. All slaves in LAN listen to a default UDP port. Upon receiving this message, they connect to a master via a TCP protocol.
  3. After the connection was established, both UDP and TCP protocols are used to exchange data between the master and slaves.
    • Over UDP protocol non-critical messages are sent. This includes messages on render parameters (for example, ambient color or HDR exposure), position of a player and all nodes that are synchronized. It also includes frame-related information (if the game is enabled, the current frame number, frame duration, a time scale and even the game seed for random number generators).
    • Over TCP protocol critical messages are sent. These are messages on creation and deletion of nodes.

Screen Configurations

There are 3 ways to specify the screen configuration that can be used with Syncker:

  • As a grid of monitors, where each slave renders its viewport on the corresponding monitor.

    Grid of 4 monitors
  • As a mesh that is created in a 3rd-party 3D editor. When preparing a mesh in a 3D editor, the following requirements must be met:
    • Each surface of the mesh must correspond to one of the monitors.
    • Names of the mesh surfaces should match names of the corresponding slaves.
    • Coordinate system of the mesh must be expressed in meters.
    • Position and orientation of each monitor must be relative to the camera.
    • The pivot point of the mesh must correspond to the camera position.
    Notice
    Projection and modelview matrices are automatically calculated on the basis of the camera position and slave name.

    Screen configuration (the right picture) represented by a mesh (the left picture)
  • As a CAVE (Cave Automatic Virtual Environment) that is a special case of the mesh created in a 3rd-party 3D editor (see the previous paragraph). The pivot point of such mesh is the origin of coordinates for the head position.

  • As a projection onto a curved screen.

    Each slave projects its viewport onto the projection screen

Preparing Your Environment

It is recommended to use at least 1 Gb LAN. Otherwise, you may experience network lags (see Troubleshooting section).

All application you will use need to have access to all Unigine files and project data. So, you should copy your project onto all computers. If some nodes will be missing in the world file on the local computer, they will not be rendered.

Running Syncker

To run Syncker to synchronize Unigine-based applications over LAN, you can choose one of two ways:

How To Run What Can be Run What Is the Profit Comments
On the application start-up Any Unigine project Fast This high-level method allows running Syncker out-of-the-box. You can load any samples, demos or your projects without implementing any initialization or synchronization logic for Syncker by using the following scripts:
  • data/core/systems/syncker/syncker_master.cpp - the Syncker script for the master.
  • data/core/systems/syncker/syncker_slave.cpp - the Syncker script for slaves.
These scripts should be used instead of the default editor script. However, this method is not performance-efficient, since it synchronizes states of all nodes and materials in the specific radius around the camera.

Notice
UnigineEditor (its Unigine-native GUI) functionality will not be available in both the master and slave applications.
Via a script Syncker samples in SDK or coded projects Performance-efficient The low-level method allows specifying which nodes and materials need to be synchronized. However, in this case, initialization and synchronization logic for Syncker must be implemented in your custom script. To avoid network lags especially for big projects, it is a preferred variant.

Examples can be found under the <Unigine SDK>/data/samples/syncker/ folder.

On Start-Up

Notice
UnigineEditor (its Unigine-native GUI) functionality will not be available in both the master and slave applications.

To run the high-level variant of Syncker directly on start-up:

  1. Run all slave applications that will be synchronized with the master.

    For that, specify the following options on the slave application start-up to override the default editor script with the Syncker script for slaves:

    Shell commands
    main_x64 -data_path "../" -editor_script "core/systems/syncker/syncker_slave.cpp" -console_command "editor_reload"
    The editor_reload console command is required to load the Syncker script for slaves.
    Notice
    Do not forget to add the other required start-up arguments.
    If you open the console, you will see that a slave application listens on two ports for packets from a master (this default values can be left unchanged):
    Output
    ---- Syncker::Slave ----
    Name: unknown
    UDP: 8890
    TCP: 8891
  2. Run a master Unigine application on the main computer with the default editor script overridden by the Syncker script for master.

    For that, specify the following options on the master application start-up:

    Shell commands
    main_x64 -data_path "../" -editor_script "core/systems/syncker/syncker_master.cpp" -console_command "world_load unigine_project && editor_reload"
    The editor_reload console command is required to load the Syncker script for the master.
    Notice
    Do not forget to add the other required start-up arguments.
    In the console, the current master network broadcast address will be shown:
    Output
    ---- Syncker::Master ----
    Address: 192.168.0.255
    UDP: 8890
    TCP: 8891
  3. To change the network broadcast address of the master, type the following console command:
    Notice
    Do not confuse with the IP-address of the computer on which the master application is run.
    Source code
    master_address xxx.xxx.xxx.xxx
    And then reload the Syncker script for the master as follows:
    Source code
    editor_reload
    After that, in the console, you will see messages that slaves have connected:
    Output
    Connection from "xxx.xxx.xxx.xxx" "unknown" accepted in 0.00 seconds
    In the console of the connected slaves, you will see the following:
    Output
    Connection to "xxx.xxx.xxx.xxx" accepted in 0.00 seconds

If any slaves are added after the Syncker master script was loaded (or slave names or addresses were changed), you will need to reload the master script via the console by using the editor_reload command.

You can open new worlds or quit from the current one in the master application and slaves will automatically do the same.

Notice
Console commands world_reload or world_load with the same world as currently loaded are not run on slaves after the master.

Changing Screen Configuration

By default all computers will be showing the same screen as a master computer does. The master viewport cannot be changed, it is used purely to control the world.
To set the screen configuration on slave computers used for rendering, all you need to do is specify your monitors setup for the master and all slaves (it is required that the same configuration is set for all computers connected via Syncker). After that, you can choose the viewport each slave computer shows, as well as compensate for the monitor angle.

Notice
You can specify the required screen configuration on the application start-up.
  1. First of all, set a monitor configuration on the master application via the following console command. The first argument specifies the number of monitors in a row and the second one specifies the number of columns. (Do not count in a master computer as its screen is non-configurable!)
    Source code
    master_grid 5 1
    For example, this command specifies that there are 5 slave monitors standing in a row.
  2. Set the same configuration for all slaves. This can be done in two ways. To specify it from master application for all slaves at once:
    Source code
    master_run slave_grid 5 1
    This would run the corresponding console command on all slaves.
    You can also run this console command in a usual way - by opening consoles on each slave computer and typing the following:
    Source code
    slave_grid 5 1
  3. Now you need to specify what each slave computer will show on its monitor by typing the following command into the console. For example, here is the slave that is the 1st in a row:
    Source code
    slave_view 0 0
    And here is a monitor in the middle (the 3rd monitor in the row):
    Source code
    slave_view 2 0
    And here is a slave that is the 5th in a row:
    Source code
    slave_view 4 0
    If we'd had two rows of monitors (grid 5x2), the computer in the right bottom would have slave_view configuration set to 4 1.
  4. You can check the viewport configuration of all slaves by the typing the master computer the following console command:
    Source code
    master_view
    It will output the configuration of all slave monitors.
  5. You can also specify if a slave monitor stands at a certain angle to other monitors. To set an angle for all slaves at once, type the following console command on the master computer:
    Source code
    master_angle 20
    You can also set an angle for each slave application individually via its console:
    Source code
    slave_angle 20
    The angles are specified in degrees.
    You cannot compensate for both vertical and horizontal turn of monitors. The engine automatically sets the compensation angle specified for a horizontal row or a vertical column depending on the number of monitors. If there are more monitors in a row (for example, 5 in a row and 2 columns), then the angle will be applied for horizontal compensation. If there are more monitors in a column (for example, 2 in a row and 6 columns), then the angle will be applied for vertical compensation.
  6. In addition to a monitor turning angle, it is also possible to compensate for a monitor frame around the screen (in order for objects not to teleport across the screens). To compensate for a bezel on all slave computers at once, type the following console command:
    Source code
    master_bezel 0.2 0
    This would specify that the screen of all computers should be rendered smaller horizontally (there is a frame between computers standing is a row). The specified value is range [0;1], where:
    • 0 is no bezel compensation
    • 1 is a half-screen size bezel
    For bezel compensation of computers standing in a column (i.e. to use only vertical bezel compensation), use the following:
    Source code
    master_bezel 0 0.2
    You can also set a bezel for each slave application individually via its console:
    Source code
    slave_bezel 0 0.2

Synchronizing Nodes in the World

If you run a high-level version of Syncker via the interface or on the start-up, you can see that only camera position is synchronized by default. To synchronize nodes and their materials within a certain radius, run the following command in the master application:

Source code
master_radius 10
master_materials 15
  • master_radius command specifies that all nodes loaded from a *.world file should be synchronized if they inside a 10-unit radius around the player. Both their position and orientation will be synchronized.
    Notice
    It is not possible to synchronize nodes created dynamically via a script or added in the editor.
  • master_materials command specifies that states and parameters of materials that get inside a 15-unit radius around the player are synchronized to a master computer.
    Notice
    It is not possible to synchronize materials created in the editor in run time and not loaded from a material library on the disk.

The method described above is good enough to try out Syncker features. It is not performance-friendly since it synchronizes all nodes and all materials each frame. When a Syncker is used for a release version of the project, run it via a script and synchronize nodes and materials selectively, only on demand.

Troubleshooting

If the network latency is too large despite 1Gb bandwidth or higher, it can be caused by a 100 Mb or 10 Mb device connected to a network. Data exchange rate will drop down to the maximum rate supported by such device, slowing down Syncker connection speed.

  • Some 100 Mb or 10 Mb devices can have a working network interface when they are turned off.
  • It is also possible that when turned off, 1 Gb devices have a network interface working at 100 Mb rate, which will slow down connection in LAN.

Useful Tool

If you have a source SDK, you can use a simple and useful tool to monitor the network messages exchange speed. It is server.usc found in source/tools/Interpreter/scripts/network/.

Last update: 2017-07-03