Using VRPN Inputs

Describes how to set up nDisplay to get input from VRPN devices.

Windows
MacOS
Linux

You can send input events to nDisplay from motion trackers, axis controllers, button controllers, and keyboards that you have configured to send their data to a VRPN network.

Setting up VRPN for nDisplay

To use a VRPN input device with nDisplay:

  1. Install a VRPN server on your network.
    This version of nDisplay requires VRPN version 7.33.

  2. In the server’s vrpn.cfg file, which you'll find located next to the server's executable file, enable your input device and give it a name.

  3. In your nDisplay configuration file, add an input entry to set up your VRPN input device.

Depending on the kind of input device you need to set up, and how you want to apply the input from that device to your Unreal Engine Project, you may need to use different settings for your input configuration and carry out some additional steps. See the following sections for details that apply to each different type of input device.

For complete details on all the settings and parameters you can set in the nDisplay configuration file, see nDisplay Configuration File Reference.

Mapping a VRPN Tracker to an nDisplay Camera or Scene Node

If you have a VRPN tracker device, you can map its current position directly to any nDisplay camera or scene node that you have set up in your nDisplay configuration file. As you move the tracker around in real space, the location of that camera or scene node will automatically update in virtual space to follow.

You can do this in your nDisplay configuration file, by setting up the input and camera sections.

The following example shows one way to set up the ART DTrack tracking system:

  • In Vrpn.cfg, located next to the VRPN server executable, add the following line:

    vrpn_Tracker_DTrack DTrack  5000

    This makes VRPN receive the DTrack inputs from port 5000, and maps them to the VRPN device named DTrack. (Make sure DTrack is configured to output its tracking data on port 5000.)

  • In the nDisplay config file, add the following lines:

    [input] id=CaveTracking type=tracker addr=DTrack@127.0.0.1 loc="X=1.32,Y=0,Z=0.93735" rot="P=0,Y=0,R=0" front=Z right=-X up=Y
    [camera] id=camera_dynamic loc="X=0,Y=0,Z=0" tracker_id=CaveTracking tracker_ch=0

    The first line creates an nDisplay input device named CaveTracking, which fetches data from VRPN address DTrack@127.0.01. You have to adapt the coordinate system here to fit with your tracking system and offset. The second line, the camera configuration, tells nDisplay to fetch camera positions from the CaveTracking input on channel 0.

Reflecting Keyboard Events

If you have a keyboard device set up for your VRPN server, you can control how the events from that keyboard (when keys are pressed and released) are reflected in your Unreal Engine Project. You can make the keyboard keys trigger the standard UE4 keyboard input system, you can direct the keys trigger new keyboard inputs provided by nDisplay, you can do both, or neither.

You can set this up in either of two equivalent ways:

  • You can do it in your nDisplay configuration file, by setting the reflect option for the input section that defines your keyboard device:

    [input] id=ControlKeyboard type=keyboard addr=Keyboard0@192.168.0.1 reflect=ue4
  • Or you can do it in your Project's Blueprint code, by calling the Set VRPN Keyboard Reflection (Interface Call) function:
    Keyboard reflection in Blueprint

The reflection setting accepts any one of the following values:

[input] setting

Blueprint option

Description

nDisplay

nDisplay buttons only

Keyboard events are routed to new keyboard input events created by nDisplay. You can respond to these events in your Blueprint scripts using the nodes in the Input > N Display Keyboard Events category.

ue4

Native UE4 keyboard events

Keyboard events are routed through the input system built in to Unreal Engine. You can respond to these events in the InputController class you use in your application, or you can respond to them in your Blueprint scripts using the nodes in the Input > Keyboard Events category.

both

Both nDisplay and UE4 native

Keyboard events are routed through both the nDisplay keyboard handling system and the input system built in to Unreal Engine. You can respond to their events using of the methods described in either of the rows above.

none

No reflection

Keyboard events are not routed through either the nDisplay keyboard handling system or the built-in input system.
If you use this option, you'll need to either:

  • Query for specific events using Blueprint nodes from the nDisplay Blueprint API, like Display Cluster > Input > Was VRPN Button Pressed or Display Cluster > Input > Was VRPN Button Released. See also Querying for Device Inputs.

  • Bind individual keys to other input events in UE4. For details, see Binding Device Channels to UE4 Inputs.

When you set up reflection for a keyboard device, your setting applies to all keys on that device. However, you can still re-bind individual keys to other input events in UE4. For details, see Binding Device Channels to UE4 Inputs.

Binding Device Channels to UE4 Inputs

You can make your Project respond to VRPN input devices by binding specific channels from your VRPN devices to Unreal Engine events and motion sources. You can create these bindings in either of two equivalent ways:

  • By setting up an input_setup section in your nDisplay configuration file for each channel you want to bind to a motion source or event.

  • By using the functions available in the nDisplay input module API:
    Bind VRPN device channel

Example: Binding a Tracking Device to a Motion Source

You can bind a VRPN motion tracking device to any existing Motion Source in Unreal Engine. You can then use that Motion Source to drive a MotionControllerComponent that you assign to an Actor in your Level.

To set this up:

  1. You'll need your nDisplay configuration file to have an input section that defines the tracker. For example:

    [input] id=TestTrack type=tracker addr=Tracker0@127.0.0.1 loc="X=0,Y=0,Z=0" rot="P=0,Y=0,R=0" front=X right=Y up=Z
  2. You'll also need to bind the device and channel that you want to track to the Motion Source that you want to receive its input.
    You can do this by adding an input_source section to your configuration file:

    [input_setup] id=TestTrack ch=0 bind="Special_1"

    Or you can do it in your Project's Blueprint code, by calling the Bind VRPN Tracker (Interface Call) function and setting the same values:
    Bind VRPN Tracker

Example: Binding an Analog Device

An analog VRPN device gives input values that range from 0 to 1, similar to a mouse or thumbstick input in Unreal Engine.

nDisplay includes a set of 20 generic analog inputs that you can bind your analog VRPN devices to. You'll find them under the Input > N Display Events and Input > N Display Values categories.

nDisplay generic analog events and values

You don't have to use these nDisplay analog inputs; you can also bind the VRPN device to other UE4 inputs. The following example shows both.

To set this up:

  1. You'll need your nDisplay configuration file to have an input section that defines the analog device. For example:

    [input] id=TestAxes type=analog addr=Mouse0@127.0.0.1
  2. You'll also need to bind the device and channel that you want to track to the analog input that you want to receive its input. Often analog devices have two channels — one for input on an X axis and one for the Y axis. In this case, you'll typically want to bind the two axes separately to different nDisplay analog inputs.
    You can do this by adding two input_source sections to your configuration file:

    [input_setup] id=TestAxes ch=0 bind="nDisplay Analog 0"
    [input_setup] id=TestAxes ch=1 bind="Gamepad Left Thumbstick Y-Axis".

    Or you can do it in your Project's Blueprint code, by calling the Bind VRPN Channel (Interface Call) function and setting the same values:
    Bind VRPN Channel for analog device

  3. When you need to detect that an input event occurred, or get the actual value of the input along its axis, use the input events that you've bound your VRPN axis channels to.
    For example, in this case you'd use:

    • for the first axis, Input > N Display Events > nDisplay Analog 0 to respond to an input event, and Input > N Display Values >  nDisplay Analog 0 to retrieve the current axis value.

    • for the second axis, Input > Gamepad Events > Gamepad Left Thumbstick Y-Axis to respond to an input event, and Input > Gamepad Values > Gamepad Left Thumbstick Y-Axis to retrieve the current axis value.

Example: Binding a Button Device

A button VRPN device fires an event on a given channel each time a button is pressed or released.

nDisplay includes a set of 20 generic button event inputs that you can bind your button devices to. You'll find them in the the Input > N Display Events category.

nDisplay generic button events

You don't have to use these nDisplay button inputs; you can also bind the VRPN device to other UE4 inputs. The following example shows both.

To set this up:

  1. You'll need your nDisplay configuration file to have an input section that defines the button device. For example:

    [input] id=TestBtn type=buttons addr=Mouse0@127.0.0.1
  2. You'll also need to bind the device and channel that you want to track to the button input that you want to receive its input.
    You can do this by adding an input_source section to your configuration file:

    [input_source] id=TestBtn ch=0 bind="nDisplay Button 0"
    [input_source] id=TestBtn ch=2 bind="Gamepad Face Button Top"

    Or you can do it in your Project's Blueprint code, by calling the Bind VRPN Channel (Interface Call) function and setting the same values:
    Bind VRPN Channel for button device

  3. When you need to detect that an input event occurred, use the input event that you've bound your VRPN button channel to.
    For example, in this case you would use the Events > N Display Events > nDisplay Button 0 and Events > Gamepad Events > Gamepad Face Button Top nodes.

Example: Binding a Keyboard Device

As described under Reflecting Keyboard Events above, you can make VRPN keyboards map their inputs to built-in Unreal Engine keyboard inputs, to new nDisplay keyboard inputs, both, or neither. Regardless of what type of reflection you set up, you can also bind individual keys from your keyboard to other Unreal Engine or nDisplay input events.

To set this up:

  1. You'll need your nDisplay configuration file to have an input section that defines the keyboard device. For example:

    [input] id=TestKb type=keyboard addr=Keyboard0@127.0.0.1
  2. You'll also need to bind the device and the key that you want to track to the Unreal Engine input event that you want that key to trigger.
    You can do this by adding an input_source section to your configuration file:

    [input_source] id=TestBtn key="Space Bar" bind="Gamepad Left Trigger"

    Or you can do it in your Project's Blueprint code, by calling the Bind VRPN Keyboard (Interface Call) function and setting the same values:
    Bind VRPN Keyboard

  3. When you need to detect that an input event occurred, use the input event that you've bound your VRPN button channel to.
    For example, in this case you would use the Event > Gamepad Events > Gamepad Left Trigger node.

Querying for Device Inputs

Instead of relying on bindings to input events, you can directly query your VRPN devices to find out their current state.

  • In C++, use the IDisplayClusterInputManager class.

  • In Blueprints, use the functions in the nDisplay API under DisplayCluster > Input. Make sure that the input values that you provide for the Device Id and Device Channel in these nodes must match the values that you have set for the device in the input section of your nDisplay configuration file.
    For example:

Keyboard Buttons and Device Channels

A VRPN keyboard input is essentially a specialized type of button device. If you need to query whether a given keyboard button was pressed, use the Was VRPN Button Pressed (Interface Call) function:

Detecting whether a VRPN button was pressed

For this to work, you need to set the Device Channel input to the numeric ID assigned by VRPN to the button that you want to test.

To determine the numeric ID of the Device Channel that corresponds to the button that you want to test on your keyboard, you can run the vrpn_print_devices.exe application that you'll find provided with the VRPN distribution. While this tool is running, it prints to the console the numeric ID of any button you press on your keyboard.

For example, the spacebar is key number 57:

Find the numeric ID of a keyboard button

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