Extensible 3D (X3D)
Part 1: Architecture and base components

30 Event Utilities component

# 30.1 Introduction

## 30.1.1 Name

The name of this component is "EventUtilities". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

## 30.1.2 Overview

This clause describes the Event Utilities component of this document. This includes Trigger and Sequencer node types that gives authors the capability to gate, convert, or sequence numerous event-types for common interactive applications without the use of a Script node. Table 30.1 provides links to the major topics in this subclause.

Table 30.1 — Topics

30.1 Introduction 30.1.1 Name 30.1.2 Overview 30.2 Concepts 30.2.1 Overview of event utility nodes 30.2.2 Mutating events of Single Field (SF) event types 30.2.3 Triggering events between Single Field (SF) event types 30.2.4 Sequencing Single Field (SF) events 30.3 Abstract types 30.3.1 X3DSequencerNode 30.3.2 X3DTriggerNode 30.4 Node reference 30.4.1 BooleanFilter 30.4.2 BooleanSequencer 30.4.3 BooleanToggle 30.4.4 BooleanTrigger 30.4.5 IntegerSequencer 30.4.6 IntegerTrigger 30.4.7 TimeTrigger 30.5 Support levels Table 30.1 — Topics Table 30.2 — Event utilities component support levels

# 30.2 Concepts

## 30.2.1 Overview of event utility nodes

The Event Utilities component consists of 3 basic concepts:

1. mutating events of Single Field (SF) events of a given type,
2. triggering Single Field (SF) events of a given type from events of other types, and
3. sequencing Single Field (SF) events along a timeline (as a discrete value generator).

These nodes may be composed using ROUTEs to create powerful authoring scenarios without writing script code. This is especially useful in profiles where interactivity would be otherwise significantly limited due to lack of a Script node.

The location of event utility nodes in the transformation hierarchy has no effect on their operation. For example, if a parent of a BooleanSequencer is a Switch node with whichChoice set to −1 ( i.e., ignore its children), the BooleanSequencer continues to operate as specified ( i.e., receives and sends events).

## 30.2.2 Mutating events of Single Field (SF) event types

Mutator nodes allow content authors to alter values of a given type. In this part of ISO/IEC 19775, the BooleanFilter node accepts a single Boolean input event and generates either a TRUE or FALSE output event based on the value of its input; it also generates an event equal to the negation of its input. These events allow for the creation of conditional behaviors that would otherwise require a script.

## 30.2.3 Triggering events between Single Field (SF) event-types

Trigger nodes that generate an output event of a given type based on an input event of a different type are all derived from the X3DTriggerNode abstract node type. This document specifies the following types of X3DTriggerNode nodes:

1. BooleanTrigger
2. IntegerTrigger
3. TimeTrigger

The BooleanTrigger node generates an SFBool output event upon receiving an SFTime input event.

The IntegerTrigger node generates an SFInt32 output event upon receiving an SFBool input event. The value of the integer can be specified.

The TimeTrigger node generates an SFTime output event upon receiving The IntegerTrigger node generates an integer output event upon receiving an SFBool input event.

EXAMPLE Routing the isActive field of a TouchSensor to the TimeTrigger allows the content creator to start a corresponding TimeSensor when the isActive field generates a TRUE event.

## 30.2.4 Sequencing Single Field (SF) events

Sequencer nodes allow content authors to generate a specific sequence of discrete events over the course of a TimeSensor's output. They are derived from the abstract node type X3DSequencerNode and thus share the signature fields of set_fraction (SFFloat [in]) and key (MFFloat [in,out]).

The set_fraction inputOnly field receives an SFFloat event and causes the sequencing function to evaluate, resulting in a value_changed output event with the same timestamp as the set_fraction event. The sequencer node sends only one value_changed output event per key[i] interval. Such sequenced values are not interpolated. The usage of the keyValue and output fields are dependent on the type of the Sequencer.

BooleanSequencer and IntegerSequencer output a single-value field to value_changed. Each value in the keyValue field corresponds in order to the parameter value in the key field. Results are undefined if the number of values in the key field of a sequencer is not the same as the number of values in the keyValue field.

The specified X3D sequencer nodes are designed for discrete events along a timeline. Each of these nodes defines a piecewise-linear function, f(t), on the interval ( −infinity, +infinity). The piecewise-linear function is defined by n values of t, called key, and the n corresponding values of f(t), called keyValue. The keys shall be monotonically non-decreasing, otherwise the results are undefined. The keys are not restricted to any interval.

Each of these nodes evaluates f(t) given any value of t (via the fraction field) as follows: Let the n keys t0, t1, t2, ..., tn-1 partition the domain ( -infinity, +infinity) into the n+1 subintervals given by (− infinity, t0), [t0, t1), [t1, t2), ..., [tn-1, +infinity). Also, let the n values v0, v1, v2, ..., vn-1 be the values of f(t) at the associated key values. The discrete value sequencing function, f(t), is defined to be:

f(t) = vi , if ti ≤ t < tn-1 for 0 ≤ i < n-1;
= vi , if t = ti = ti+1;
= v0 , if t ≤ t0;
= vn−1 , if t ≥ tn−1

Note that if more than one key/keyValue pairs are provided for the same key, only the first defined value for keyValue is used.

# 30.3 Abstract types

## 30.3.1 X3DSequencerNode

    X3DSequencerNode : X3DChildNode {
      SFBool       [in]     next
      SFBool       [in]     previous
      SFFloat      [in]     set_fraction       (-∞,∞)
      MFFloat      [in,out] key           []   (-∞,∞)
      MF<type>     [in,out] keyValue      []
      SFNode       [in,out] metadata      NULL [X3DMetadataObject]
      [S|M]F<type> [out]    value_changed
    }

This abstract node type is the base node type from which all Sequencers are derived. 30.2.4 Sequencing Single Field (SF) events contains a detailed discussion of Sequencer nodes.

The value of the internal fraction field is initialized at the first value of the key field, or else has a value of 0 if no key array is defined.

Receipt of a next event with value TRUE triggers the next output value in keyValue array by issuing a value_changed event with that value. Receipt of a previous event with value TRUE triggers previous output value in keyValue array. The value of the internal fraction field is reset to match the corresponding sequential ( next or previous) value in the key array.

Sending a FALSE event to the next or previous fields has no effect.

The next or previous trigger events "wrap around" after reaching the boundary of keyValue array; i.e., next goes to initial element after last, and previous goes to last element after first.

## 30.3.2 X3DTriggerNode

    X3DTriggerNode : X3DChildNode  {
      SFNode [in,out] metadata NULL [X3DMetadataObject]
    }

This abstract node type is the base node type from which all trigger nodes are derived. 30.2.3 Triggering events between Single Field (SF) event-types contains a detailed discussion of Triggers.

# 30.4 Node Reference

## 30.4.1 BooleanFilter

    BooleanFilter : X3DChildNode {
      SFBool [in]     set_boolean
      SFNode [in,out] metadata    NULL [X3DMetadataObject]
      SFBool [out]    inputFalse
      SFBool [out]    inputNegate
      SFBool [out]    inputTrue
    }

BooleanFilter filters Boolean events, allowing for selective routing of TRUE or FALSE values and negation.

When the set_boolean event is received, the BooleanFilter node generates two events: either inputTrue or inputFalse, based on the Boolean value received; and inputNegate, which contains the negation of the value received.

## 30.4.2 BooleanSequencer

    BooleanSequencer : X3DSequencerNode {
      SFBool  [in]     next
      SFBool  [in]     previous
      SFFloat [in]     set_fraction
      MFFloat [in,out] key           []   (-∞,∞)
      MFBool  [in,out] keyValue 	 []
      SFNode  [in,out] metadata      NULL [X3DMetadataObject]
      SFBool  [out]    value_changed
    }

BooleanSequencer generates sequential value_changed events selected from the keyValue field when driven from a TimeSensor clock. Among other actions, it can enable/disable lights and sensors, or bind/unbind viewpoints and other X3DBindableNode nodes using set_bind events.

The keyValue field is made up of a list of FALSE and TRUE values.

A BooleanSequencer shall be instanced for every node enabled or bound.

## 30.4.3 BooleanToggle

    BooleanToggle : X3DChildNode {
      SFBool [in]     set_boolean
      SFNode [in,out] metadata    NULL  [X3DMetadataObject]
      SFBool [in,out] toggle      FALSE
    }

BooleanToggle stores a Boolean value for toggling on/off. When a set_boolean TRUE event is received, the BooleanToggle negates the value of the toggle field and generates the corresponding toggle_changed output event. All received set_boolean FALSE events are ignored.

The BooleanToggle can be reset to a specific state by directly setting the value of the inputOutput toggle field. A toggle_changed event is then sent with the same value.

## 30.4.4 BooleanTrigger

    BooleanTrigger : X3DTriggerNode {
      SFTime [in]     set_triggerTime
      SFNode [in,out] metadata        NULL [X3DMetadataObject]
      SFBool [out]    triggerTrue
    }

BooleanTrigger is a trigger node that generates Boolean events upon receiving time events.

The triggerTrue event is generated when the BooleanTrigger receives a set_triggerTime event. The value of triggerTrue shall always be TRUE.

## 30.4.5 IntegerSequencer

    IntegerSequencer : X3DSequencerNode {
      SFBool  [in]     next
      SFBool  [in]     previous
      SFFloat [in]     set_fraction
      MFFloat [in,out] key           []   (-∞,∞)
      MFInt32 [in,out] keyValue      []   (-∞,∞)
      SFNode  [in,out] metadata      NULL [X3DMetadataObject]
      SFInt32 [out]    value_changed
    }

The IntegerSequencer node generates sequential discrete value_changed events selected from the keyValue field in response to each set_fraction, next, or previous event.

## 30.4.6 IntegerTrigger

    IntegerTrigger : X3DTriggerNode {
      SFBool  [in]     set_boolean
      SFInt32 [in,out] integerKey   -1   (-∞,∞)
      SFNode  [in,out] metadata     NULL [X3DMetadataObject]
      SFInt32 [out]    triggerValue
    }

IntegerTrigger handles single set_boolean input events to provide an integer value for the output event. This is useful for connecting environmental events such as the Switch node's whichChoice field.

The integerKey field is the value that is sent if the IntegerTrigger node receives a set_boolean TRUE event. Resetting the value of the integerKey field itself generates corresponding integerKey_changed and triggerValue_changed events that is sent with that same value.

Upon receiving a set_boolean TRUE event, the IntegerTrigger node generates a triggerValue event with the current value of integerKey. The set_boolean event shall only be honored if a TRUE value is received.

## 30.4.7 TimeTrigger

    TimeTrigger : X3DTriggerNode {
      SFBool [in]     set_boolean
      SFNode [in,out] metadata    NULL [X3DMetadataObject]
      SFTime [out]    triggerTime
    }

TimeTrigger is a trigger node that generates time events upon receiving Boolean events.

The triggerTime event is generated when the TimeTrigger receives a set_boolean event. The value of triggerTime shall be the time at which set_boolean is received. The value of set_boolean shall be ignored.

# 30.5 Support levels

The Event Utilities component provides one level of support as specified in Table 30.2. Level 1 provides the full support for all nodes defined above.

Table 30.2 — Event utilities component support levels

Level | Prerequisites | Nodes/Features | Support
--- | --- | --- | ---
1 | Core 1 Grouping 1 |  |
|  | X3DSequencerNode (abstract) | All fields fully supported.
|  | X3DTriggerNode (abstract) | All fields fully supported.
|  | BooleanFilter | All fields fully supported.
|  | BooleanSequencer | All fields fully supported.
|  | BooleanToggle | All fields fully supported.
|  | BooleanTrigger | All fields fully supported.
|  | IntegerSequencer | All fields fully supported.
|  | IntegerTrigger | All fields fully supported.
|  | TimeTrigger | All fields fully supported.