Introduction

1.1 Name

The name of this component is "xj3d_IODevice". This name shall be used when referring to this component in the COMPONENT statement (see ISO FDIS 19775-1:200x 7.2.5.4 Component statement).

1.2 Overview

This clause describes the Input/Output device component as a custom extension to Xj3D. This includes how to map external hardare devices and their interactions with the X3D scene and event model.Table 1 provides links to the major topics in this clause.

2 Concepts

2.1 Overview

This component provides an abstraction of hardware that is used to provide input and output to the browser. Typical browser implementations hide these devices and automatically provide mapping to the software controls. For example, a joystick will directly move the user's avatar without any control by the user over how the avatar could move.

Some classes of applications prefer to do their own handling of the devices. For example, a joystick will want to be mapped so that the end user can see the control surfaces on an aircraft move in response to the joystick movement. This component is designed to expose these input devices to the end user in a manner that is consistent with the X3D specification.

Devices can be broken up into a set of classes of capabilities. There are those which represent some sort of controller, such as joysticks and gamepads. A second class of device is to provide position and orientation data in raw form and expressed. These are known as 6 degree of freedom (6DOF) devices, and are illustrated by devices such as motion capture suits, Head Mounted Displays (HMD) etc. Finally, MIDI is an important standard for providing programmatic control into and out of a scene. Most end users are familiar with MIDI as a format for music files (indeed, the Sound Component requires support of MIDI files for music playback). However, MIDI has found far greater uses in applications such as controlling large lighting systems at displays.

2.2 Classes of devices

2.2.1 MIDI

MIDI can be used as input from various hardware devices, as well as output control mechanisms, beyond the normal associations with music keyboards. This specification defines both input and output capabilities as being available to the content developer

2.2.2 Trackers

At level two, any 6-Degree Of Freedom (6DOF) device can be represented as a node in the X3D scene. This allows the content creator to take a generic input device, such as a joystick and expose it's input at the X3D level and use it to control other geometry. An example of this is to use the joystick to manipulate the ailerons and elevator of an aircraft model.

2.2.3 HID Devices

These devices implement the HID specification

TBD

2.3 Mapping devices

A user may have more than one of each device plugged into the system. In addition, for transportable content, each viewer will have different hardware available. In addition, a Joystick is not always just known as a "Joystick" as part of the device representation at the lower-level operating system. To deal with this, each node provides an output of the list of registered names on that system that have been found. A user may then set up the node with the explicit name. This will require a small amount of scripting to do. In addition, an extension to the SAI will allow the the user to extract this device information and then use the SAI createNode() call to do this work.

3 Abstract Types

3.1 X3DDeviceSensorNode

X3DDeviceSensorNode : X3DSensorNode  :  {
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""
  SFBool   [out]    isActive
  SFString [out]       manufacturerName
}

The base interface for all I/O devices supported in X3D.

3.2 X3DHIDDeviceSensorNode

X3DHIDDeviceSensorNode : X3DDeviceSensorNode  {
  MFFloat  [in]     outputValue
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""
  SFBool   [out]    isActive
  MFFloat  [out]    axisValue
  MFFloat  [out]    axisMinValue
  MFFloat  [out]    axisMaxValue
  MFString [out]    axisName
  MFFloat  [out]    axisResolution
  MFBool   [out]    axisWrap
  SFString [out]    manufacturerName
  SFInt32  [out]    numAxes
  SFInt32  [out]    numOutputs
  MFString [out]    outputName
  MFFloat  [out]    outputMinValue
  MFFloat  [out]    outputMaxValue
  MFFloat  [out]    outputResolution
  MFBool   [out]    outputWrap
}

The X3DHIDDeviceSensorNode exposes devices which conform to the Human Interface Device(need ref) specification or are mapped to it.

The outputValue inputOnly field updates an output feature on the device. This is typically a rumbler or LED light. Boolean outputs shall be represented using 1 for TRUE, all other values will be FALSE.

The fields axisMinValue, axisMaxValue, axisName, axisResolution and axisWrap are used to describe an axis. There shall be numAxes entries in each one.

The axisValue field is updated whenever an axis changes value. All values are absolute values. Normalized values can be attained by using the current value in combination with the min and maximum values for the axis. Axes representing buttons shall use 1 for ON, all other values will be OFF.

An X3D Browser shall try to map a device to one of the more specific device nodes provided in this spec. A conforming device must map all required features. If a specific device class cannot be found then the device shall be exposed through the GenericHIDDevice device node.

Specific classes of HID devices will follow these conventions:

TBD

Convenience fields will be added for accessing the common features of a device. All convenience fields shall be normalized to the following rules:

• When refering to directions like X, Y, Z in features the X direction goes from left to right in value. The Y direction goes from top to bottom in value. The Z direction shall go from the front of the device to the rear or left to right for twists. They shall range from -1 to 1 with 0 being center.
• Hats shall be mapped like directionals. Split them into X and Y directions. 0 values on both will mean the hat is not in use. Otherwise they will range from -1 to 1. A hat in the up/north position will be X=0, Y=-1. Left/west would be X=-1, Y=0;
• Sliders shall put out values from left to right, top to bottom, -1 to 1.

These values shall be the same as if the axesValue[i] was normalized (value - (maxValue[i] - minValue[i])) / (maxValue[i] - minValue[i])

3.3 X3DTrackerDeviceSensorNode

X3DTrackerDeviceSensorNode : X3DDeviceSensorNode  {
  MFFloat  [in]     outputValue
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""

Abstract representation of a device that is a 6DOF input device, such as HMDs

3.4 X3DMidiDeviceSensorNode

X3DMidiDeviceSensorNode : X3DDeviceSensorNode  {
  MFFloat  [in]     outputValue
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""

Abstract representation of a device that allows MIDI input and/or output

4 Node reference

4.1 DeviceManager

DeviceManager : X3DChildNode   {
   MFNode [out] currentDevice
   MFNode [out] newDevice
   MFNode [out] removedDevice

This is a singleton node. All instances of this node in any execution spaces issues the same events at the same time.

When a new device is added to the system it will generate a newDevice event. This event will list all devices added this frame. The node generated will be a device descending from the X3DDeviceSensorNode interface.

When a device is removed from the system it will generate a removedDevice event. The event shall contain a reference to the node that was removed.

4.2 GamepadSensor

GamepadSensor : X3DHIDDeviceSensorNode  {
  MFFloat  [in]     outputValue
  SFFloat  [in]     rumblerX
  SFFloat  [in]     rumblerY
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""
  SFBool   [out]    isActive
  MFFloat  [out]    axisValue
  SFBool   [out]    l1Button
  SFFloat  [out]    leftHatX
  SFFloat  [out]    leftHatY
  SFFloat  [out]    leftStickX
  SFFloat  [out]    leftStickY
  SFBool   [out]    r1Button
  SFFloat  [out]    rightStickX
  SFFloat  [out]    rightStickY
  SFBool   [out]    startButton
  SFFloat  [out]    throttleSlider
  MFFloat  [out]    axisMinValue
  MFFloat  [out]    axisMaxValue
  MFString [out]    axisName
  MFFloat  [out]    axisResolution
  MFBool   [out]    axisWrap
  MFString [out]    featuresAvailable
  SFInt32  [out]    numAxes
  SFInt32  [out]    numOutputs
  MFString [out]    outputName
  MFFloat  [out]    outputMinValue
  MFFloat  [out]    outputMaxValue
  MFFloat  [out]    outputResolution
  MFBool   [out]    outputWrap
}

The featuresAvailable field shows which features of the gamepad have been mapped to the standard set. If a feature is not listed here then the linked outputOnly field will not generate events.

Table 2 illustrates the mapping of the HID specification feature name to the field name of this node.

4.3 GenericHIDSensor

GenericHIDSensor : X3DHIDDeviceSensorNode {
  MFFloat  [in]     outputValue
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFBool   [out]    isActive
  MFFloat  [out]    axisValue []
  MFFloat  [out]    axisMinValue []
  MFFloat  [out]    axisMaxValue []
  MFString [out]    axisName []
  MFFloat  [out]    axisResolution []
  MFBool   [out]    axisWrap []
  SFString [out]    manufacturerName
  SFString [out]    name ""
  SFInt32  [out]    numAxes 0
  SFInt32  [out]    numOutputs 0
  MFString [out]    outputName []
  MFFloat  [out]    outputMinValue []
  MFFloat  [out]    outputMaxValue []
  MFFloat  [out]    outputResolution []
  MFBool   [out]    outputWrap []
}

No specific class of device could be mapped so a generic interface has been provided.

4.4 JoystickSensor

JoystickSensor : X3DHIDDeviceSensorNode  {
  MFFloat  [in]     outputValue
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""
  SFBool   [out]    isActive
  MFFloat  [out]    axisValue
  SFFloat  [out]    hatX
  SFFloat  [out]    hatY
  SFFloat  [out]    stickX
  SFFloat  [out]    stickY
  SFFloat  [out]    stickZ
  SFBool   [out]    triggerButton
  SFFloat  [out]    throttleSlider
  MFFloat  [out]    axisMinValue
  MFFloat  [out]    axisMaxValue
  MFString [out]    axisName
  MFFloat  [out]    axisResolution
  MFBool   [out]    axisWrap
  MFString [out]    featuresAvailable
  SFInt32  [out]    numAxes
  SFInt32  [out]    numOutputs
  MFString [out]    outputName
  MFFloat  [out]    outputMinValue
  MFFloat  [out]    outputMaxValue
  MFFloat  [out]    outputResolution
  MFBool   [out]    outputWrap
}

The featuresAvailable field shows which features of the gamepad have been mapped to the standard set. If a feature is not listed here then the linked outputOnly field will not generate events.

Table 2 illustrates the mapping of the HID specification feature name to the field name of this node.

4.5 MidiSensor

MidiSensor : X3DMidiDeviceSensorNode {
  MFInt32  [in]    outputChannel
  MFInt32  [in]    outputCommand
  MFInt32  [in]    outputData1
  MFInt32  [in]    outputData2
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""
  SFBool   [out]    isActive
  MFString [out]    available
  MFInt32  [out]    inputChannel
  MFInt32  [out]    inputCommand
  MFInt32  [out]    inputData1
  MFInt32  [out]    inputData2

Defines a source for MIDI input to the scene. Events are generated as the selected source detects them.

4.6 MouseSensor

TBD

4.7 TrackerSensor

TrackerSensor : X3DTrackerDeviceSensorNode {
  SFNode     [in,out] metadata NULL [X3DMetadataObject]
  SFString   [in,out] name ""
  SFBool     [out]    isActive
  SFInt32    [out]    numTrackers
  MFVec3f    [out]    positions
  MFRotation [out]    rotations

4.8 WheelSensor

WheelSensor : X3DHIDDeviceSensorNode  {
  MFFloat  [in]     outputValue
  SFFloat  [in]     equalibriumPoint
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFString [in,out] name ""
  SFBool   [out]    isActive
  MFFloat  [out]    axisValue
  SFBool   [out]    button1
  SFBool   [out]    button2
  SFBool   [out]    button3
  SFBool   [out]    button4
  SFFloat  [out]    wheelX
  SFFloat  [out]    throttleSlider
  MFFloat  [out]    axisMinValue
  MFFloat  [out]    axisMaxValue
  MFString [out]    axisName
  MFFloat  [out]    axisResolution
  MFBool   [out]    axisWrap
  MFString [out]    featuresAvailable
  SFInt32  [out]    numAxes
  SFInt32  [out]    numOutputs
  MFString [out]    outputName
  MFFloat  [out]    outputMinValue
  MFFloat  [out]    outputMaxValue
  MFFloat  [out]    outputResolution
  MFBool   [out]    outputWrap
}

The featuresAvailable field shows which features of the gamepad have been mapped to the standard set. If a feature is not listed here then the linked outputOnly field will not generate events.

Table 3 illustrates the mapping of the HID specification feature name to the field name of this node.

5 Support Levels

The Input/Output device component defines two levels of support as specified in Table 3.