Skip to content

ConfigReference

Jump to bottom Edit New page
Alessandro Febretti edited this page Feb 6, 2015 · 53 revisions

Last revision: ver. 6.0-beta6 - 9 January 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:

  • pythonShellEnabled (bool): enables the interactive python console. After version 6.0 the shell can also be enable dusing the -i command line option, so this setting is somewhat redundant unless you want to ensure the interactive shell is enabled for all applications.

  • initCommand (string): 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.

  • (v5.3) initScript (string): 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, default false): draw 2D pointers on screen.

  • pointerSize (bool, default 32): the size in pixels of 2D pointers.

  • deathSwitchTimeout (int, default 60): the timeout in seconds before slave instances automatically shutdown if no update is received.

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.

(v6.0) 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, 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.

  • verbose (bool, default false) - when set to true, the Display system will output additional diagnostic messages during startup and shutdown.

  • geometry (String, required) - sets the geometry class of this display system (Supported values in omegalib 3.0 and higher are Planar, Cylindrical, and Custom)

  • numTiles (int array, 2 values) - 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 array, 2 values) - the index of the tile whose center will be considered the origin point of the display system reference frame.

  • referenceOffset

  • tileSize (float array, 2 values) - the size of a display tile in meters, including the bezels.

  • bezelSize (float array, 2 values) - the width and height of the display bezels, in meters.

  • autoOffsetWindows

  • tileResolution

  • windowOffset

  • latency

  • stereoMode (string, default Mono) - Sets the default stereo mode for the display system. Supported values are Mono, SideBySide, Interleaved. This value can be overridden by each tile, if tiles need to use different stereo modes.

  • invertStereo (bool, default false) - when set to true and stereo is enabled, invert left and right eyes. This setting overrides the equivalent per-tile setting.

  • fullscreen (bool) - enable fullscreen for all tiles. When set to true also disables window borders.

  • borderless (bool) - Disable window borders for all tiles (unless specified in tile configuration)

  • disableConfigGenerator (Boolean) - when set to true, the Equalizer display configuration file will not be regenerated. Useful when debugging configurations, or to tweak Equalizer parameters in experimental configurations.

  • nodeLauncher (string) - the comand used to launch slave instances in a cluster configuration. See sectionbelow for more information.

  • nodeKiller (string) the command used to kill slave instances in a cluster configuration. See section below for more information.

  • basePort

  • launcherInterval

  • enableSwapSync (bool) - when set to true all tiles in a cluster configuration will swap-sync

  • tiles (section) - This configuration section contains one or more node configuration entries

  • (v6.0) canvasPosition (int 2D array) - the pixel position of the startup viewport.

  • (v6.0) canvasSize (int 2D array) - the pixel size of the startup viewport.

Node launcher and Node killer commands

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

Node Configuration

The display 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
  • 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.
  • (v6.0) 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")
  • (v6.0) 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;
	};

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;
		};
	};

camera section

The camera section configures the default camera.

  • position (Vector3): sets the initial navigational position of the camera.

  • orientation (array with pitch, yaw, roll in degrees): sets the initial navigational orientation of the camera.

  • controller (String - one of wand gamepad mouse mousekeyboard)

  • trackerSourceId (int): 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.

  • (v6.3) trackingEnabled (bool): When set to true, enable head tracking. If trackerSourceId is specified and is different from -1, tracking will always be enabled.

  • headOffset (Vector3): 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 - button name): sets the button used by the camera controller for navigation. Supported by wand camera controller.

  • overrideButton (String - button name): 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.

  • (6.0-beta6) freeFly (boolean): if a camera has a controller attached, this flag enables/disables freefly mode. See [CameraController] for more information. By default freefly is disabled.

Example:

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

interactor section

The interactor section configures the standard interactor mode for the application

  • 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. Example:
	interactor:
	{
		style = "Wand";
		moveButton = "Button3";
	};

defaultFont section

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

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

console section

The console section configures the on-screen console.

  • 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.

Example:

	console:
	{
		font:
		{
			filename = "fonts/segoeuimod.ttf";
			size = 32;
		};
	};

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.

  • initScript (String): name or path to a script that will be launched at startup. Default is orun_init.py
  • appStartFunction (String): 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()

Example:

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

(v6.0) '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