nDisplay Configuration File Reference

A reference companion for all the settings available in the nDisplay configuration file.

Windows
MacOS
Linux

You define most aspects of the nDisplay system in a single configuration file. This file includes the computers that make up your network, the characteristics of the windows and viewports you want the Unreal Engine to render on each computer, the parts of the virtual world each viewport should render, the types of input devices you want to accept, and more.

This page describes all the settings available in the nDisplay configuration file.

The best way to get started understanding the nDisplay configuration file, and creating your own, is to start from the example configurations provided by the nDisplay plugin. If you've created your Project from the nDisplay template, you'll find these files in your Project folder, under Content/ExampleConfigs. If not, you can find these files in the Unreal Engine installation folder, under Templates/TP_nDisplayBP/Content/ExampleConfigs.

The structure of the nDisplay configuration file is directly tied to the different types of components it uses to render the visualization.

  • Each different type of component that you configure has its own line in the file, and is identified by a string ID that you assign. You use these string IDs when one configuration section needs to refer to another.

  • Many of the components that you configure in this file have defined positions (and often rotations) in virtual 3D space. Each object's position and rotation is relative to that object's parent. By default, the parent of all objects is the VR space origin: an arbitrary point in 3D world space where VR space is considered to start. You can also configure specific named transforms in 3D space, called scene_nodes, which can act as parents for one or more components. This can help simplify the spatial layout of your screens, cameras and other components.
    To see how you can use scene_nodes to build a hierarchy of 3D transforms that all start from the same point in virtual space, see the Configuration File Scene Structure Example section below.

  • All parameters that refer to measurements in virtual 3D space or real-world physical space expect values in meters and degrees, unless otherwise indicated. This includes screens, scene nodes, cameras, and so on.

  • All parameters that refer to measurements in screen space expect values in pixels. This includes windows and viewports.

Cluster Node Configurations

For each different instance of your Unreal Engine application that you'll use in your nDisplay network, you need to define a cluster_node configuration. Each cluster_node configuration must contain a reference to a window configuration section that defines the properties of the main application window.

The cluster_node configuration also defines the hostname or IP address of the computer that will run that application instance. You may set up a different physical computer for each cluster_node configuration, or you may have multiple cluster_node configurations that run on the same host.

Example configuration:

This example configures a master node (one per network):

[cluster_node] id=node_front addr=192.168.0.1 window=wnd_LT sound=true port_cs=41001 port_ss=41002 master=true

This example shows a non-master cluster node:

[cluster_node] id=node_left addr=192.168.0.2 window=wnd_large sound=false

Parameters:

Parameter

Description

id

A unique name for this cluster node configuration.

addr

The IP address of the computer that will run this instance of Unreal Engine. This must be an IPv4 address. IPv6 is not supported.

window

The name of the window configuration that defines the size and position of the main window for this instance of your Unreal Engine application.

sound

Determines whether this instance of Unreal Engine plays sound. Optional; default value is false.

port_cs port_ss port_ce

Ports that the master node uses to communicate with other nodes in the cluster. port_cs is for cluster synchronization; port_ss is for swap synchronization; port_ce is for cluster events. Optional; default values are 14001, 14002, and 14003.

master

Determines whether this instance of Unreal Engine is the master node of the cluster. Only one cluster_node section can have this parameter set to true. Optional; default value is false.

eye_swap

Determines whether or not the images generated for the left and right eye are swapped. Optional; default value is false.

Window Configurations

Each window configuration defines a set of properties for the main window of an instance of your Unreal Engine application. You use it to configure things like the starting size and placement of the window when nDisplay launches your application, and whether or not the window should take up the full screen.

You also provide one or more viewport configurations, which identify specific areas within the main application window that nDisplay will fill with renderings of your scene.

Example configuration:

This example configures an application window that contains a single viewport:

[window] id=wnd_one fullscreen=false WinX=0 WinY=0 ResX=640 ResY=480 viewports=vp_LT

This example configures an application window that contains four separate viewports:

[window] id=wnd_four fullscreen=false WinX=0 WinY=0 ResX=640 ResY=480 viewports="vp_LT,vp_RB,vp_LB,vp_RT"

Parameters:

Parameter

Description

id

A unique name for this window configuration.

fullscreen

Determines whether this window should run in fullscreen mode or not. If you set this value to false, you must provide the WinX, WinY, ResX, and RexY settings described below.

Winx WinY

Specifies the position of the top left corner of the application window on the desktop, in pixels of screen space.

ResX ResY

Specifies the size of the application window in pixels of screen space.

viewports

Refers to one or more viewport configuration sections that define the areas of the main application window that nDisplay should fill with rendered views of the scene.
If you specify more than one viewport, you must use a comma-separated list of viewport configuration section names, enclosed in quotes. See the wnd_four example under the Example configuration section above. The order of this list does not affect the visual order or placement of the viewports. The placement of the viewports within the parent window are defined in the named viewport configurations.

Make sure that the viewport definitions you use do not exceed the size of the window.

Viewport Configurations

Each window configuration described above refers to one or more viewport configurations, each of which defines a rectangular area of the game window that nDisplay should fill with a rendered view of the scene.

Usually, a viewport starts at the upper left corner of the application window, and its width and height are set so that they fill the parent window. However, in some cases you may need to offset the viewport within its parent application window. For example, you might want to do this if you need to set up two projectors that partially overlap, or if you need one application window to host multiple separate viewports at different positions.

Example configuration:

[viewport] id=vp_LT X=0 Y=0 width=300 height=220 projection=proj_simple_LT

Parameters:

Parameter

Description

id

A unique name for this viewport configuration.

X Y

The coordinates of the top left corner of the viewport, in pixels, within the screen space of the main application window. Note that these values are relative to the top left corner of the application window, not relative to the top left corner of the screen itself.

width height

The width and height of the rendered frame, in pixels. This should not be larger than the size of the game window that is set by the size parameter of any window configuration using this viewport.

projection

The name of the projection configuration that defines the rendered view of the virtual world that should be drawn to this viewport.

Projection Configurations

Each viewport configuration described above refers to a projection configuration, which is responsible for defining the rendered image that needs to be drawn in the viewport.

In most common situations, you will use the simple projection type, which renders the virtual world from the current camera's position using a frustum that is defined by a screen configuration section elsewhere in this nDisplay configuration file.

Other projection types, such as easyblend and mpcdi, use other methods to define the rendered content for the viewport, and may introduce additional corrections or apply additional rendering techniques before rendering the image to the rectangular viewport. For example, the projection may squash, stretch, or distort the image so that it will look natural when displayed on a curved surface.

Example configuration:

The following example shows the simplest possible use case, which routes the frustum defined by the screen configuration named scr_LT directly to the viewport without distorting or modifying the rendered image.

[projection] id=proj_simple_LT type=simple screen=scr_LT

The following example shows how to use the easyblend projection type to render to a surface defined in a Scalable Display configuration file.

[projection] id=proj_easyblend_1 type="easyblend" file="D:\eb_data\ScalableData.pol_1" origin=easyblend_origin_1 scale=0.1

The following example shows how to use the mpcdi projection type to render to a surface defined in an MPCDI configuration file.

[projection] id=proj_mpcdi_LT type="mpcdi" file="D:\rot90_flat.mpcdi" buffer="Mosaic" region="Monitor_R" origin=mpcdi_origin

The following example shows how to use the mpcdi projection type to render to a curved surface defined by a specified .pfm geometry file, using an alpha blending map defined by a specified .png file.

[projection] id=proj_mpcdi_LT type="mpcdi" pfm="D:\geom_displayLeft1.pfm" alpha="D:\Left1blend.png" alpha_gamma=2 origin=mpcdi_origin

Parameters:

Parameter

Description

id

A unique name for this projection configuration.

type

The type of projection that defines how nDisplay generates the rendered image it draws in the viewport. This accepts the following values:

  • simple: Renders to the viewport a frustum on the virtual world defined by a screen configuration section.

  • easyblend: Renders to the viewport a view of the virtual world that you have calibrated using tools from Scalable Display Technologies.

  • mpcdi: Renders to the viewport a view of the virtual world that you have calibrated using MPCDI.

Projections where type=simple also accept the following additional parameters:

Parameter

Description

screen

The name of the screen configuration that defines the frustum of 3D space that the Unreal Engine application should render into this viewport.

Projections where type=easyblend also accept the following additional parameters:

Parameter

Description

file

The path and file name of the Scalable Display calibration file that defines the surface that this viewport will be projected on.

origin

The ID of a scene_node configuration section that defines the starting point for the projection. This maps the frame of reference defined in the Scalable Display calibration file to the virtual space in your Unreal Engine Level.

scale

The scaling factor to use for the projection.

Projections where type=mpcdi also accept the following additional parameters:

Parameter

Description

origin

The ID of a scene_node configuration section that defines the starting point for the projection. This maps the frame of reference defined in the MPCDI calibration file (or the .pfm geometry file) to the virtual space in your Unreal Engine Level.

file

The path and file name of the .mpcdi file that defines the geometry of the surface that this viewport will be projected on.

buffer

The ID of the buffer in the .mpcdi file that defines the projection area for this viewport.

region

The ID of the region within the buffer set above that you want to render to.

pfm

As an alternative to using the file, buffer, and region settings above to define the geometry of the surface that this viewport will be projected on based on data in an mpcdi file, you can use the pfm setting to provide geometry for the projection in a .pfm file that you specify.

scale

If you use the pfm setting, you can use the scale setting to provide a scaling factor to use for the geometry. Optional.

ue4space

If you use the pfm setting, you can use the ue4space setting if your .pfm file is already expressed in the Unreal Engine coordinate system. Optional.

alpha

The path and file name of a .png file to use as an alpha blend map, which defines the intensity of the projection. Optional.

alpha_gamma

If you use the alpha setting, you can use the alpha_gamma setting to provide a multiplier for the alpha gamma. Optional.

beta

If you use the alpha setting, you can also use the beta setting to provide the path and file name of the .png file to use as a beta blend map. This defines the black level adjustment. Optional.

nDisplay currently supports only MPCDI version 1.0, and only the 2D and A3D (or Advanced 3D) profile types.

Screen Configurations

Each different output display that uses the simple projection type renders the scene from the current camera's position using a frustum that is defined by a rectangle with a defined size and placement in the 3D VR space. Each of these rectangles is defined by a screen configuration. Usually, each of these projection screens has the same dimensions in VR space as the physical screen that you'll use to render it.

The pivot point of a screen is always in its exact midpoint.

Example configuration:

This definition describes a screen that is 3 meters by 3 meters screen, directly in front of its parent. Because the pivot point of the screen is at the center of the rectangle defined by the size parameter, we add a 1.5 meter offset on the Z axis to move the screen upward by half its height.

[screen] id=screen_front loc="X=1.5.Y=0,Z=1.5" rot="P=0,Y=0,R=0" size="X=3,Y=3" parent=screens

To define a screen on the left side of the viewer, we move it to the left (negative values on the Y axis), and rotate it around its local Y axis (yaw), 

[screen] id=screen_left loc="X=0,y=-1.5,Z=1.5" rot="P=0,Y=-90,R=0" size="X=3,Y=3" parent=screens

Parameters:

Parameter

Description

id

A unique name for this screen configuration.

loc

The location of the center of this screen in VR space, relative to its parent.

rot

The pitch (P), yaw (Y) and roll (R) angles of the screen's facing direction, in degrees.

size

The total size of the screen rectangle along its local X and Y axes, in meters.

parent

The name of a scene_node configuration that you want to act as the parent for this object. This parameter is optional. If you specify a parent, the values you set in the loc and rot parameters will be relative to the position of that parent. If you omit the parent, the values you set in the loc and rot parameters will be relative to the VR root.

Camera Configurations

All instances in the nDisplay cluster render the scene from the same position in the virtual world. Each of these potential viewpoints is defined by a camera configuration line.

You can switch between these viewpoints at runtime. Each camera viewpoint can also be driven by a tracking device.

Example configuration:

[camera] id=camera_static loc="X=0.Y=0,Z=1.7" tracker_id=VRPNTracking tracker_ch=0

Parameters:

Parameter

Description

id

A unique name for this camera configuration.

loc

The location of this camera in VR space, relative to its parent.

tracker_id

The name of the input configuration that defines the VR device you want to drive the position of the camera over time. Optional. If you omit this parameter, the camera's position will be static in VR space.

tracker_ch

When you provide a tracker_id, this parameter specifies the channel of that device that nDisplay will read tracking data from.

parent

The name of a scene_node configuration that you want to act as the parent for this object. This parameter is optional. If you specify a parent, the values you set in the loc parameter will be relative to the position of that parent. If you omit the parent, the values you set in the loc parameter will be relative to the VR root.

Scene Node Configurations

In your configuration file, you can define a hierarchy of scene nodes, each of which represents a transform in 3D space. Anything that you set up in the configuration file that requires a position and rotation in 3D space, such as a camera or a projection screen, can use one of these scene_node configurations as its parent. This can help you to define the spatial relationships between all of the different components of the visualization system.

Like cameras, scene nodes can also be driven by VR tracking devices.

Example configuration:

The following lines define a hierarchy of two nodes, where the child node has an offset of 2 meters in front of its parent.

[scene_node] id=vr_space_root loc="X=0.Y=0,Z=0" rot="P=0,Y=0,R=0"
[scene_node] id=walls_front_group loc="X=2.Y=0,Z=0" rot="P=0,Y=0,R=0" parent= vr_space_root

The following line shows a scene node that is configured to be driven by a VR tracking device:

[scene_node] id=cave_wand loc="X=0, Y=0,Z=1" tracker_id=CaveTracking tracker_ch=1

Parameters:

Parameter

Description

id

A unique name for this scene node configuration.

loc

The location of this scene node in VR space, relative to its parent.

rot

The pitch (P), yaw (Y) and roll (R) angles of the scene node's facing direction, in degrees.

parent

The name of another scene_node configuration that you want to act as the parent for this scene node. This parameter is optional. If you specify a parent, the values you set in the loc and rot parameters will be relative to the position of that parent. If you omit the parent, the values you set in the loc and rot parameters will be relative to the VR root.

tracker_id

The name of the input configuration that defines the VR device you want to drive the position of the scene node over time. Optional. If you omit this parameter, the scene node's position and rotation will be static in VR space with respect to its parent.

tracker_ch

When you provide a tracker_id, this parameter specifies the channel of that device that nDisplay will read tracking data from.

Input Configurations

You define an input section for each device that you need to provide input to the nDisplay system. For example, each camera and each scene_node may optionally be driven by a VR tracking device that you set up in an input section and refer to in the camera or scene_node configuration. Alternatively, you may want to set up trackers, controllers, and keyboards to send generic input events to the Unreal Engine input system, or bind their events and input values to generic nDisplay Blueprint nodes that you can respond to in your Project's gameplay scripts.

You can also use input_setup sections to control the way specific channels, buttons, or keys from these input devices are bound to specific types of input events and values within Unreal Engine.

For an overview of what you can do with nDisplay inputs, see Using VRPN Inputs.

Example configuration:

This configuration sets up nDisplay to get input from a VRPN location tracking device. Typically this kind of device is mounted to a camera or a viewer's head, or is held by a viewer. You can automatically drive the position of a camera or scene node from the trackerby referring to this input configuration in a camera or scene_node configuration. Or, you can retrieve the value of this tracker in your Project's Blueprint code.

[input] id=CaveTracking type=tracker addr=Tracker0@192.168.0.1 loc="X=-1.5,Y=0,Z=3.4" rot="P-0,Y=0,R=0" front=X right=Y up=-Z

This configuration sets up nDisplay to read keyboard input from a keyboard that is set up as a VRPN device, and to route that input through the built-in Unreal Engine keyboard inputs.

[input] id=ControlKeyboard type=keyboard addr=Keyboard0@192.168.0.1 reflect=ue4

Parameters:

Parameter

Description

id

A unique name for this input device configuration.

type

The type of this VRPN input device:

  • tracker for a tracking device.

  • analog for a device that produces axis data.

  • button for a device that produces Boolean button data.

  • keyboard for a standard computer keyboard.

addr

The address of the VRPN server that handles this particular device. The value must match the following format:
DEVICENAME@SERVER_ADDRESS:SERVER_PORT
where:

  • DEVICENAME is the VRPN name for this device.

  • SERVER_ADDRESS is the IPv4 address of the VRPN server.

  • :SERVER_PORT is the port the VRPN server listens on for incoming connections.
    This is optional. If you don't provide it, nDisplay uses port 3883 by default.

Devices where type=tracker also accept the following additional parameters:

Parameter

Description

loc rot

Similar to other configuration sections, the loc and rot parameters specify position and rotation offsets in local space for this input device. However, for an input device, you typically use these offsets to adjust the root position of a tracking device in VR space to match the location you expect it to be in your scene node hierarchy.

front right up

These parameters match each local axis of the tracker in Unreal (front, right, and up) with the corresponding axis in the tracker's coordinate system. Unreal uses a right-handed, Z-up coordinate system. If your tracker uses a different coordinate system, you can use these parameters to map the tracker's coordinate system to Unreal's.
For example, the following line maps the Y axis of the tracker to the front (X) axis in Unreal; the X axis of the tracker to the right (Y) axis in Unreal, and the negative Z axis of the tracker to the up (Z) axis in Unreal:
front=Y right=X up=-Z

Devices where type=keyboard also accept the following additional parameter:

Parameter

Description

reflect

Determines how the inputs from this keyboard are passed in to the Unreal Engine, and how you can respond to those events.
This setting accepts any one of the following values:

  • nDisplay

  • ue4

  • both

  • none

For more information, see Reflecting Keyboard Events.

Input Setup Configurations

Each input_setup configuration section provides additional configuration parameters for a specified input device, typically to bind a channel or key from that device to a generic nDisplay Blueprint input node.

Example configuration:

This configuration sets up the input device with ID controller so that when a button is pressed that generates an event on channel 0, an event is generated from the Input > N Display Events > nDisplay Button 0 node in Blueprint.

[input_setup] id=controller ch=0 bind="nDisplay Button 0"

This configuration is similar to the above, except that it binds an analog value (typically an axis from a controller) to an nDisplay analog value. You can use the Input > N Display Events > nDisplay Analog 0 node in Blueprint to detect when that controller axis is used, or Input > N Display Values > nDisplay Analog 0 to retrieve the value for the current frame.

[input_setup] id=test_axes ch=0 bind="nDisplay Analog 0"

If you're using a keyboard device, you don't have to specifically bind each of its keys. Instead, you simply use the reflect setting in the input section to determine whether the key events should be routed to built-in Unreal Engine keyboard events, or to nDisplay keyboard events. However, if you want to change a binding or add a new binding, you can. For example, this section makes the space bar trigger the Input > N Display Events > nDisplay Button 3 event.

[input_setup] id=keyboard0 key=Space bind="nDisplay Button 3"

Parameters:

Parameter

Description

id

Refers to the ID of the input configuration that this input_setup section configures.
Note that unlike most other sections in the nDisplay configuration file, this id value does not provide an ID for the input_setup section that contains it. Instead, it refers to the ID of an input section defined elsewhere in the file.

ch

Determines the channel of the specified input device that will be bound to the event that you set in the bind setting.

key

Similar to ch, but used only for input devices where type=keyboard.

bind

Determines the event in Unreal Engine that the channel or key specified above is bound to. This value can be the name of any Blueprint node that you see in the Input category, such as F1, nDisplay F1nDisplay Button 0, Gamepad Left Thumbstick X-Axis, Gamepad Face Button Top, and so on.
If the name contains a space, you must enclose it in double-quotes.

You can also set up these channel and key bindings in your Project's Blueprint code, using the nodes in the input module API. For details, see Binding Device Channels to UE4 Inputs.

General Configuration

The general configuration line contains parameters that control the overall operation of the nDisplay cluster.

Example configuration:

[general] swap_sync_policy=1

Parameters:

Parameter

Description

swap_sync_policy

Determines how output is synchronized over the network.

  • 0: no synchronization.

  • 1: Software swap synchronization

  • 2: NV swap lock (only for NVIDIA cards rendering with OpenGL)

Stereo Configuration

The stereo configuration line sets optional global parameters for stereoscopic rendering.

Example configuration:

[stereo] eye_dist=0.064

Parameters:

Parameter

Description

eye_dist

The inter-ocular distance to use for offsetting the images generated for the left and right eyes, in meters.

Network Configuration

The network configuration section provides settings that you can use to control timeouts and other settings related to network communication between nDisplay cluster nodes.

You can only have zero or one network section in your nDisplay configuration file.

Example configuration:

[network] cln_conn_tries_amount=10 cln_conn_retry_delay=1000 game_start_timeout=30000 barrier_wait_timeout=5000

Parameters:

Parameter

Description

cln_conn_tries_amount

When a non-master cluster node starts up, this setting determines the number of times the node will attempt to connect to the master.
Optional; the default value is 10.

cln_conn_retry_delay

When a non-master cluster node starts up, this setting determines the time interval between each successive attempt by the node to connect to its master, in milliseconds.
Optional; the default value is 1000.

game_start_timeout

Sets a time interval that each Unreal Engine application on each cluster node will wait before it starts the first frame of the game loop and begins rendering to the main window, in milliseconds. This gives all your cluster nodes a chance to connect to the master before rendering begins. During this time, the main window will be black. If, at the end of this time interval, any node has not yet successfully connected, all instances in the cluster will shut down.
Optional; the default value is 30000. You may need to raise this value if your cluster takes an unusually long time to initialize.

barrier_wait_timeout

Sets the barrier timeout for the game and render threads, in milliseconds. This is a barrier timeout to synchronize both game and render threads among cluster nodes. It’s used several times within each frame. In other words, this is used at runtime to detect situations where any node becomes unreachable. If this occurs, the state of the cluster state is determined to be invalid, and all nodes shut themselves down.
Optional; the default value is 5000.

The cln_conn_tries_amount and cln_conn_retry_delay settings work together to determine the maximum length of time your cluster nodes will try to connect to the master node at startup. For example, suppose you have cln_conn_tries_amount set to 10, and cln_conn_retry_delay set to 1000 milliseconds. On startup, each node tries to connect to the master. If that connection fails, it waits 1000 milliseconds to try again. If that attempt also fails, it waits another 1000 milliseconds. After ten successive failures, the cluster node quits automatically. As soon as a cluster node makes the connection to its master, the count stops.

Info Configuration

The info configuration line contains optional information about the latest version of nDisplay and Unreal Engine that this configuration file is known to be compatible with.

Example configuration:

[info] version=22

Parameters:

Parameter

Description

version

The latest version of nDIsplay and Unreal Engine that this configuration file is known to be compatible with.
The number should be understood as the point version that follows 4.. For example, a value of 22 means that the file is compatible with version 4.22 of nDisplay and Unreal Engine.

Do not set this value by hand. The nDisplay Launcher sets it automatically. If you use a configuration file without a version, or where the version in the file is lower than the version of nDisplay and Unreal Engine you are using, the nDisplay Launcher automatically attempts to update your configuration file to work with the latest version. If it succeeds, it saves the updated configuration to a new file and updates this value to the latest version.

Configuration File Scene Structure Example

To take a specific example, open the wall_flat_3x2.cfg sample file, which you'll find in your Unreal Engine installation folder under Templates/TP_nDisplayBP/Content/ExampleConfigs. This file defines six projection screens, each of which is to be rendered by a separate physical computer.

It also defines several scene_nodes, which taken together create the following hierarchy:

nDisplay example scene hierarchy

The relative positions and rotations of the nodes in this hierarchy lay out the arrangement of the camera and the six screens in VR space so that the six projection screens are side-by-side, at a distance of 1 meter from the camera. 

Note that the configuration implies a small space in between each adjacent pair of projection screens, to account for the edges of the monitors rendering the scene.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback