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.3.4 Component statement).

30.1.2 Overview

This clause describes the Event Utilities component of this part of ISO/IEC 19775. This includes Trigger and Sequencer node types which 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.

30.2 Concepts

30.2.1 Overview of event utility nodes

The Event Utilities component consists of 3 basic concepts:  Mutating values of Single Field (SF) events of a given type, Triggering Single Field (SF) events of a given type from events of other types, and 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 (6.17.3.2).

The location of event utility nodes in the transformation hierarchy has no effect on their operation. For example, if a parent of an 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. For example, 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 generate an output event of a given type based on an input event of a different type. For example, the TimeTrigger node generates a time output event upon receiving a boolean input event, allowing the content creator to start a TimeSensor based on a boolean event such as the isActive field of a TouchSensor.

All Trigger nodes inherit from the base type X3DTriggerNode.

30.2.4 Sequencing Single Fielded (SF) events

Sequencer nodes are designed to allow content authors to generate a specific sequence of discrete events over the course of the 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 eventIn receives an SFFloat event and causes the sequencing function to evaluate, resulting in a value_changed eventOut with the same timestamp as the set_fraction event. 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 t₀, t₁, t₂, ..., t_n-1 partition the domain (-infinity, +infinity) into the n+1 subintervals given by (-infinity, t₀), [t₀, t₁), [t₁, t₂), ... , [t_n-1, +infinity). Also, let the n values v₀, v₁, v₂, ..., v_n-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) = vn, if tn ≤ t < tn-1

         = v0, if t ≤ t0,
         = vn-1, if t ≥ tn-1

30.3 Abstract types

30.3.1 X3DSequencerNode

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

This abstract node type is the base node type from which all Sequencers are derived. 30.2, Concepts, contains a detailed discussion of Sequencers.

30.3.2 X3DTriggerNode

X3DTriggerNode : X3DChildNode  {
}

This abstract node type is the base node type from which all Triggers are derived. 30.2, Concepts, contains a detailed discussion of Triggers.

30.4 Node Reference

30.4.1 BooleanFilter

BooleanFilter : X3DChildNode {
  SFBool [in]  set_boolean
  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 {
  SFFloat [in]     set_fraction
  MFFloat [in,out] key           [] (-∞,∞) 
  MFBool  [in,out] keyValue 	 [] 
  SFBool  [out]    value_changed
}

BooleanSequencer generates sequential SFBool events when driven from a TimeSensor clock. Among other actions, it can enable/disable lights and sensors,
or bind/unbind Viewpoints and other X3DBindableNodes via 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
  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 field output event. 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.

30.4.4 BooleanTrigger

BooleanTrigger : X3DChildNode {
  SFTime [in]  set_triggerTime
  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 {
  SFFloat [in]     set_fraction
  MFFloat [in,out] key           [] (-∞,∞) 
  MFInt32 [in,out] keyValue      [] -1|[1, ∞)
  SFInt32 [out]    value_changed
}

IntegerSequencer generates sequential SFInt32 events for a single TimeSensor clock (drive a Switch via set_whichChoice). A discrete-value generator.

30.4.6 IntegerTrigger

IntegerTrigger : X3DChildNode {
  SFBool  [in]     set_boolean
  SFInt32 [in,out] integerKey   -1|(-∞,∞)
  SFInt32 [out]    triggerValue
}

IntegerTrigger handles single field Boolean events to set an integer value for the output event. This is useful for connecting environmental events to the Switch node's whichChoice.

Upon receiving a set_boolean event, the IntegerTrigger node will generate a triggerValue event with the current value of integerKey.

30.4.7 TimeTrigger

TimeTrigger : X3DTriggerNode {
  SFBool [in]  set_boolean
  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 four levels of support as specified in Table 30.2.
Level 1 provides the full support for all nodes defined above.