Skip to content

ConfigReference

Jump to bottom Edit New page
Alessandro Febretti edited this page Aug 28, 2016 · 53 revisions

✔️ Last revision: ver. 14.0 - 9 April 2015

Omegalib applications use configuration files to learn about the the hardware they run on. Configuration files describe the capabilities and geometry of the display system, supported input devices, and network configurations for clustered systems. The omegalib distribution contains several configration files to test applications out of the box (i.e. to run them windowed on a standard PC). Programmers and system administrators can learn about configuration files to customize omegalib applications for other display and input systems.

Configuration file types

Omegalib applications are usually based on two distinct configuration files: the system configuration file and the application configuration file.

The system configuration file determines the properties of the system the application will run on such as:

  • What input devices are available and how they are to be set up
  • The resolution of displays, their geometry, and network configuration for cluster systems
  • The defaults for observer position, navigation styles and interaction keymappings Examples for several different system configuration files can be found in the data/system folder.

The application configuration file contains application-specific options, as determined by the application itself. See the Config class reference for more information on how to read configuration values. The simplest possible application configuration file is: config: { systemConfig = "system/desktop.cfg"; }; This application configuration specifies no option other than which system configuration file to use (in this case, system/desktop.cfg)

Loading configuration files

By default, applications try to open an application configuration file with the application name and a cfg extension. If not found, the library will search for default.cfg. The default configuration file can be changed by passing a different file as the first argument to an omegalib application.

System configuration syntax

Configuration files follow the syntax of libconfig. Each section has a name and is delimited by curly braces. Section contain name-value pairs. Values can be of different types (Boolean, String, Integer, Floating point, Vector of integers or floating points).

A system configuration file contains several sections. A few of them (like the display section) are mandatory, while other are optional. The following paragraphs describe the structure of each supported section.

Global configuration options

These options go directly into the config section of the configuration file. In this reference, the syntax after an option name indicated the datatype. If an option is followed by = value, that is the default value for the option.

pythonShellEnabled

bool pythonShellEnabled

Enables the interactive python console. The shell can also be enabled using the -i command line option, so this setting is somewhat redundant unless you want to ensure the interactive shell is enabled for all applications.

📝 NOTE the pythonShellEnabled setting can be specified in the application config file as well. Setting in the application configuration overrides the setting in system configuration.

initCommand

string initCommand

Specifies a python command that will be executed at initialization time by all applications. Only works if omegalib is built with python support enabled. The init command is helpful to load or setup optional modules.

📝 NOTE initCommand, like initScript runs before display system initialization. It can be used to register new display systems but it cannot interact with the display system itself since it has not been initialized yet.

initScript

string initScript

Specifies a python script that will be executed at initialization time by all applications. Eventual initialization commands specified with initCommand will be executed after this script is run.

drawPointers

bool drawPointers = false

⚠️ DEPRECATED

Draw 2D pointers on screen.

pointerSize

bool pointerSize = 32

⚠️ DEPRECATED

The size in pixels of 2D pointers.

deathSwitchTimeout

int deathSwitchTimeout = 60

The timeout in seconds before slave instances automatically shutdown if no update is received.

platform section

The platform section Contains generic information about the platform (software, hardware and runtime), obtained by parsing the 'config/platform' section in the system configuration file. Platform settings are globally accessible and are hints that user code can use to customize its execution on different platforms. Values saved in this section can be accessed in C++ through the Platform class.

🎓 EXAMPLE

platform:
{
    // Flag: will be accessible through Platform::is("CAVE2")
    CAVE2 = true;
    // Common option: will be accessible through Platform::scale
    scale = 4.0;
}

display section

The display configuration section describes the display system geometry, resources and rendering modes used by omegalib. The display section contains the following entries:

type

string type (required)

The type of the display system manager running the display system. Can be one of the following values: - "Equalizer": Uses Equalizer to manage the display system.

openGLCoreProfile

bool openGLCoreProfile = false

If set to true, requests an openGL core profile, with legacy OpenGL functions removed.

📝 NOTE The openGLCoreProfile option is just a hint to the display system. It's up to the display system implementation to decide what to do with it.

The GLFW display system included in the omegalib core support the profile hint and initializes OpenGL in the following way depending on the OS:

openGlCoreProfile OSX Windows, Linux
true 4.1 core 4.2 core
false 2.1 compatibility 3.2 compatibility

👀 ALSO SEE EngineModule::requestOpenGLProfile

verbose

bool verbose = false

When set to true, the Display system will output additional diagnostic messages during startup and shutdown.

geometry

string geometry (required)

Sets the geometry class of this display system (Supported values in omegalib 3.0 and higher are Planar, Cylindrical, and Custom

📝 Display Geometries Display geometries are a way to describle a display system structure without having to enter the coordinates of every single display tile manually. Display geometries are implemented by the DisplayConfigBuilder and derived classes.

The planar display geometry uses the tile indices (extracted by the tile name when tiles are named as tXxY with X, Y as the tile indices) to place tiles in a 2D grid. Each tile has a size specified in 'tileSize'. The 'referenceOffset' is the center of the reference tile wrt the world origin. The reference tile is specified in the referenceTile property.

A cylindrical configuration works in a similar way, but tiles are arranged in a cylindrical configuration specified using 'radius', 'sideAngleStart' and 'sideAngleIncrement'. For an example of a cylindrical configuration see the CAVE2 config. For an example of a planar config see the CAMI wall config.

radius

float radius (used by Cylindrical configurations)

The radius of the display cylinder (center = world origin)

sideAngleStart

float sideAngleStart (used by Cylindrical configurations)

The yaw of tiles on the first column (tile grid x = 0)

sideAngleIncrement

float sideAngleIncrement (used by Cylindrical configurations)

The yaw increment for each display tile column, starting at sideAngleStart

numTiles

int numTiles[2]

Two values specifying the number of tiles in the system in the format [columns, rows]. I.e. numTiles = [3, 2]; is used to describe a system with three columns and two rows of tiles.

referenceTile

int referenceTile[2] (used by Cylindrical and Planar configurations)

The index of the tile whose center will be considered the origin point of the display system reference frame.

referenceOffset

float referenceOffset[3] (used by Cylindrical and Planar configurations)

The position of the center of the reference tile, in the real world frame of reference.

tileSize

float tileSIze[2]

The size of a display tile in meters, including the bezels.

bezelSize

float bezelSize[2]

The width and height of the display bezels, in meters.

autoOffsetWindows

bool autoOffsetWindows

tileResolution

int tileResolution[2]

windowOffset

int windowOffset[2]

stereoMode

string stereoMode = "Mono"

Sets the default stereo mode for the display system. Supported values are Mono, SideBySide, RowInterleaved, ColumnInterleaved, PixelInterleaved, AnaglyphRedCyan, and AnaglyphGreenMagenta. This value can be overridden by each tile, if tiles need to use different stereo modes.

invertStereo

bool invertStereo = false

When set to true and stereo is enabled, invert left and right eyes. This setting overrides the equivalent per-tile setting.

fullscreen

bool fullscreen

Enable fullscreen for all tiles. When set to true also disables window borders.

borderless

bool borderless

Disable window borders for all tiles (unless specified in tile configuration)

nodeLauncher

nodeKiller

string nodeLauncher

string nodeKiller

The comand used to launch and kill slave instances in a cluster configuration.

The nodeLauncher and nodeKiller commands are used to respectively start and stop slave instances of omegalib in a cluster configuration. For instance, for a linux cluster config (assuming you can password-less ssh into the remote nodes from the head node), you probably want to use these lines:

nodeLauncher = "ssh -n %h cd %d; %c";
nodeKiller = "ssh -n %h killall %c";

Note that the following substitutions are performed on those strings:

  • %h -> host name
  • %d -> executable directory
  • %c -> executable name

basePort

int basePort

launcherInterval

enableSwapSync

bool enableSwapSync

When set to true all tiles in a cluster configuration will swap-sync

canvasPosition

int canvasPosition[2]

The pixel position of the startup viewport.

canvasSize

int canvasSize[2[]

The pixel size of the startup viewport.

This figure shows how the reference tile, reference offset, camera position and head offset are related to each other

tiles

This configuration section contains one or more node configuration entries

The tiles section contains the configuration of all the tiles in the display system. tiles are grouped by node. Each node represents a machine that is physically connected to a set of tiles in the display system.

A node configuration has the following entries:

  • hostname
  • port
  • (v6.0) enabled (bool, default true) When set to false, this node will not be started.

A node configuration also contains a set of sub-blocks: each one holds the configuration for a single physical tile.

🎓 EXAMPLE

	lyra-01:
	{
		hostname="lyra-01";
		// This is a tile configuration block
		t0x1: { device = 0; }; 
	};
tile configuration
  • stereoMode (string, default Mono) - Sets the default stereo mode for the display system. Supported values are Mono, SideBySide, Interleaved. If left unspecified, the stereo mode specified in the display section mode will be used.
  • invertStereo (bool, default false) - when set to true and stereo is enabled, invert left and right eyes.
  • device (int) - Sets DISPLAY device. Usually 0, but can be others values one Linux systems with multiple X servers.
  • center
  • yaw
  • pitch
  • position (2 ints) - The position of this tile window on the node display, in pixels.
  • resolution
  • offset (2 ints) - Offset of this tile content with respect to the global canvas, in pixels. Used in multi-tile configurations to draw 2D content in the right position.
  • offscreen (Boolean) - Render this tile offscreen.
  • cameraName
  • disableMouse (Boolean) - When set to true, disables mouse event generation for this tile.
  • borderless (Boolean) - Disable window borders for this tile.
  • isInGrid (Boolean) - indicates wheter this tile is part of the tile grid. The tile grid is used to address tiles by a 2D index, for instance when specifying the application workspace bounds using the -I command line option or using the isHostInTileSection and setTilesEnabled functions. Configuration generators like ConfigCylindrical and ConfigPlanar take care of this setting automatically. You need to specify it manually, together with gridX and gridY only for custom configuration (geometry = "ConfigCustom")
  • gridX, gridY (integer) the grid x, y indices for this tile. See isInGrid description.

🎓 EXAMPLE

	headTile:
	{
		resolution = [800, 800];
		device = 0;
		center = [0, 2, -2];
		tileSize = [1.2, 0.8];
		stereoMode = "Mono";
		//enabled = true;
	};

camera section

The camera section configures the default camera.

🎓 EXAMPLE

	camera:
	{
		controller ="Wand";
		trackerSourceId = 0;
	};

position

float position[3]

Sets the initial navigational position of the camera.

orientation

float orientation[3]

Sets the initial navigational orientation of the camera as a pitch, yaw, roll in degrees.

controller

string controller

One of wand gamepad mouse mousekeyboard

trackerSourceId

int trackerSourceId

The trackable ID of the object that tracks the head of the user associated with this camera. Tracker data will be used to set the camera head offset and orientation.

trackingEnabled

bool trackingEnabled

When set to true, enable head tracking. If trackerSourceId is specified and is different from -1, tracking will always be enabled.

headOffset

float headOffset[3]

The initial position of the head (relative to the camera position).

📝 NOTE: if tracking for this camera is enabled (trackerSourceId != -1), this value will be overwritten as soon as a trackable object starts sending events. Specifying headOffset is useful for systems without tracking, or to set a good initial viewing point while tracking is acquired.

navigationButton

string navigationButton

Sets the button used by the camera controller for navigation. Supported by wand camera controller.

overrideButton

string overrideButton

When this button is pressed, the controller will not process any input or change the camera. Useful to temporary map the same input buttons and axes to some different functionality. Supported by wand camera controller.

freeFly

bool freeFly

If a camera has a controller attached, this flag enables/disables freefly mode. See [CameraController] for more information. By default freefly is disabled.

ui section

  • menuRayPlaceEnabled (bool)
  • menuDefaultPosition (Vector3f)
  • menuDefaultScale (float)
  • menu3dEnabled (bool)
  • menuSuspendNavigation (bool)
  • menuToggleButton (String - button name)
  • confirmButton (String - button name): the name of the button used to confirm actions on a gamepad or wand
  • cancelButton (String - button name): the name of the button used to cancel actions on a gamepad or wand
  • clickButton (String - button name): the name of the button used to confirm actions when the event happens ON the widget (for pointer devices and wands)

sound section

  • soundServerIP
  • soundServerPort
  • assetCacheEnabled (bool) - when set to true enabled the asset cache manager. The application will try to copy sounds over to the sound server machine (assuming a cache server is running)
  • assetCachePort (int: default 22500) - the asset cache server port number

🎓 EXAMPLE

	sound:
	{
		soundServerIP = "xenakis.evl.uic.edu";
		soundServerPort = 57120;
		showMenuSound = "/Users/evldemo/sounds/menu_sounds/menu_load.wav";
		hideMenuSound = "/Users/evldemo/sounds/menu_sounds/menu_closed.wav";
		selectMenuSound = "/Users/evldemo/sounds/menu_sounds/menu_select.wav";
		scrollMenuSound = "/Users/evldemo/sounds/menu_sounds/menu_scroll.wav";
		// Optional sound parameters
		menuSoundVolume = 0.1;
		menuSoundWidth = 1.0;
		menuSoundMix = 0.1;
		menuSoundReverb = 0.0;
	};

services section

The services section can be alternatively called input for compatibility reasons. This section lists all the event services that should run at startup, and their configuration.

🎓 EXAMPLE

	services:
	{
		NetService:
		{
			serverIP = "CAVE2Tracker.evl.uic.edu";
			msgPort = 28000;
			dataPort = 7001;
		};
	};

interactor section

The interactor section configures the standard interactor mode for the application

🎓 EXAMPLE

	interactor:
	{
		style = "Wand";
		moveButton = "Button3";
	};
  • style (String - one of wand mouse)
  • moveButton String - button name): sets the button used by to move objects. Supported by wand interactor.
  • rotateButton String - button name): sets the button used by to rotate objects. Supported by wand interactor.

defaultFont section

The defaultFont section configures the fond used by default by all ui elements.

🎓 EXAMPLE

	defaultFont:
	{
		filename = "fonts/segoeuimod.ttf";
		size = 42;
	};
  • filename (String): path to a font file
  • size (int): font size

console section

❌ DEPRECATED

The console section configures the on-screen console.

🎓 EXAMPLE

	console:
	{
		font:
		{
			filename = "fonts/segoeuimod.ttf";
			size = 32;
		};
	};
  • font (Subsection): configures the console font, following the same syntax used for the defaultFont section.
  • lines (int): sets the number of lines displayed by the console.

missionControl section

🎓 EXAMPLE

	missionControl:
	{
		serverEnabled = true;
		clientEnabled = false;
	};

Application configuration syntax

The application configuration file contains configuration sections associated to each application. Altough applications can read and use custom configuration parameters, we list here a few common ones

orun section

This section contains options used by the standard orun application used to launch omegalib python scripts.

🎓 EXAMPLE

	orun:
	{
		initScript = "customInitScript.py";
		// We add a print statement before calling a custom application start function.
		appStart = "print('Application Restart!'); _myOwnStartFunction()";
	};

initScript

string initScript

Name or path to a script that will be launched at startup. Default is orun_init.py

appStart

string appStart

Name of a function that will be launched every time orun resets the current application or loads a new one. This function is typically defined in the init script. Default is _onAppStart()

modules section

Used for config-initialized engine modules. See https://github.com/uic-evl/omegalib/issues/101

Add a custom footer
Add a custom sidebar
Clone this wiki locally