nDisplay Configuration File Reference

As of Unreal Engine 4.27, you can continue to import both .cfg and .ndisplay configuration files into your project's Content Browser and they will be converted to the new .uasset format.

You can export and use .ndisplay configuration files to launch a cluster. The .ndisplay files won't have tracking and other features that can only be configured in the nDisplay Config Asset.

We recommend using the nDisplay 3D Config Editor for configuring your nDisplay cluster.

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 primary 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

Copy full snippet

[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-primary cluster node:

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

Copy full snippet

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

Parameters:

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

Copy full snippet

[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"

Copy full snippet

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

Parameters:

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.

nDisplay supports multi-GPU (mGPU) for viewport rendering, so you can specify one GPU device to render a specific viewport and copy the frame to another GPU to display. For example in virtual production and in-camera VFX scenarios, the inner frustum can be entirely rendered on a second GPU thereby improving performance and hardware usage. On NVIDIA GPUs with NVLink, you can bypass the CPU and transfer memory directly from GPU to GPU. Without NVLink, any memory transfer will still be peer-to-peer (P2P) but might be slower as it has to go through the CPU over PCIe.

Add MaxGPUCount=2 to the custom command line arguments when you launch nDisplay either through the nDisplay Launcher or Switchboard to utilize mGPU.

Example configuration:

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

Copy full snippet

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

Parameters:

Typically, the first GPU installed and enabled in your computer is referenced as 0, while the others are incrementally assigned 1, 2, ... , n. You can find the GPU device number provided by your OS in your computer's settings. For example on Windows, you can find your GPU device numbers in Task Manager:

1. Open Task Manager.
2. Switch to the Performance tab.

3. The left side of the window shows every GPU you have in your machine and their device number.

   

   A computer with one GPU has its GPU labelled GPU 0 in Task Manager.

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 mpcdi, easyblend, vioso, and domeprojection, 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

Copy full snippet

[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

Copy full snippet

[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

Copy full snippet

[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

Copy full snippet

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

The following example shows how to use the vioso projection type to render to a surface defined in a native VIOSO file.

	[projection] id=proj_vioso_1 type="vioso" file="D:\left.vwf" origin=vioso_origin base="[1000 0 0 0] [0 1000 0 0] [0 0 1000 0] [0 0 1000 1]"

Copy full snippet

[projection] id=proj_vioso_1 type="vioso" file="D:\left.vwf" origin=vioso_origin base="[1000 0 0 0] [0 1000 0 0] [0 0 1000 0] [0 0 1000 1]"

The following example shows how to use the domeprojection type to render to a surface defined by DomeProjection in a .xml calibration file.

	[projection] id=proj_domeprojection_1 type=domeprojection file="D:\config.xml" origin=domeprojection_origin channel=0

Copy full snippet

[projection] id=proj_domeprojection_1 type=domeprojection file="D:\config.xml" origin=domeprojection_origin channel=0

Parameters:

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

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

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

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

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

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

Projections where type=manual also accept the following additional parameters to define the view rotation and frustum that nDisplay should render. You can configure the frustum using either matrices or angles.

Projections where type=camera do not accept any other additional parameters. You set up the camera for the projection policy at runtime using either the Blueprint or C++ API.

Projections where type=mesh and type=picp_mesh do not accept any other additional parameters. You set up the Static Mesh Component for the projection policy at runtime using either the Blueprint or C++ API.

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

Copy full snippet

[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

Copy full snippet

[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:

PostProcess Configurations

A postprocess configuration defines how the image generated for a window by an instance of the Unreal Engine should be post-processed before being rendered. nDisplay currently supports two types of post-process operations: OutputRemap and TextureShare.

With OutputRemap, you can control the way the 2D image, generated by nDisplay, maps to the 2D area of the application window. For example, you can translate, rotate, and scale parts of the output image so that they appear in different regions of the application window. To do this, you need to provide an .obj file that contains a planar geometry with a UV mapping set up. nDisplay will use the UV mapping that was set for your plane to determine how the output image is mapped to each part of the application window.

With TextureShare, you can receive a texture from another application and display it in the specified viewport. To do this, you need to define a postprocess with the name of the Texture Share item and the viewport that will display the texture.

Example configuration:

The following example shows how to use the OutputRemap postprocess type with two .obj files:

	[window] id=somewindow ... postprocess="pp_1, pp_2"
	[postprocess] id=pp_1 type="OutputRemap" file="remap_1.obj"
	[postprocess] id=pp_2 type="OutputRemap" file="remap_2.obj"

Copy full snippet

[window] id=somewindow ... postprocess="pp_1, pp_2" [postprocess] id=pp_1 type="OutputRemap" file="remap_1.obj" [postprocess] id=pp_2 type="OutputRemap" file="remap_2.obj"

The following example shows how to use TextureShare to share the rendered frame for the vp_1 viewport to an external application, receive a texture from a third party source, and display it in the vp_ext viewport.

	[window] id=somewindow viewports="vp_1" fullscreen="false" … postprocess="pp_sharenode_ext"
	[viewport] id=vp_1 ... projection="proj_screen_1" share=true
	[viewport] id=vp_ext ... projection=""
		[postprocess] id=pp_sharednode_ext type="TextureShare" destination="vp_ext" source="thirdpartyapp_viewport_rendering"
Copy full snippet

[window] id=somewindow viewports="vp_1" fullscreen="false" … postprocess="pp_sharenode_ext" [viewport] id=vp_1 ... projection="proj_screen_1" share=true [viewport] id=vp_ext ... projection="" [postprocess] id=pp_sharednode_ext type="TextureShare" destination="vp_ext" source="thirdpartyapp_viewport_rendering"

Parameters:

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

Copy full snippet

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

Parameters:

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

Copy full snippet

[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

Copy full snippet

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

Parameters:

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 Live Link VRPN.

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 [email protected] loc="X=-1.5,Y=0,Z=3.4" rot="P-0,Y=0,R=0" front=X right=Y up=-Z

Copy full snippet

[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

Parameters:

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

Devices where type=analog and type=button do not accept any additional parameters.

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"

Copy full snippet

[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"

Copy full snippet

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

Parameters:

General Configuration

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

Example configuration:

	[general] swap_sync_policy=1

Copy full snippet

[general] swap_sync_policy=1

Parameters:

NVIDIA Configuration

If you use a swap_sync_policy value of 2 in your general configuration section, you can use the parameters in the NVIDIA section to tweak some specific hardware settings relating to frame lock.

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

Copy full snippet

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

Parameters:

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 primary 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 primary PC. 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 primary PC, the count stops.

Info Configuration

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

Example configuration:

	[info] version=22

Copy full snippet

[info] version=22

Parameters:

Custom Configuration Parameters

You can include a custom configuration section to provide your own custom key-value pairs to your nDisplay cluster nodes. You can include as many parameters and values as you need on a [cluster] line. You can then retrieve these configuration values at runtime from the nDisplay Blueprint or C++ APIs.

Example configuration:

	[custom] stringParameter=myValue numberParameter=2

Copy full snippet

[custom] stringParameter=myValue numberParameter=2

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:

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.