H3D API Training Part 3.2: Fields; Event Handling

H3D API  Fields: ◦ Field concept ◦ SF / MF Fields ◦ Mutator/Function fields  Event Handling: ◦ Field Routes (Behaviour Graph)

Fields  Fundamental building blocks of X3D and H3D API  Data storage  Data dependency  Data modification (functional)  Event handling  Ability to express behaviour in the system / applications

Routing  Dependencies between fields  Event propagation  Default behaviour: copy value

Fields - Example button my_func colour my_func() has type SFBool -> SFRGB my_func() returns red if button pressed is true, otherwise green

Fields - Functionality  Base Field ◦ route to field (express a dependency) ◦ unroute from field ◦ upToDate() (ensure field is up-to-date) ◦ event passing ◦ lazy evaluation  Data Field ◦ Single (SF) or Multiple (MF) data value ◦ Strongly typed ◦ Functional modification of data values (via update() function) ◦ getValue() and setValue()

Access types  initializeOnly  outputOnly  inputOnly  inputOutput

Event Handling  H3D API (and X3D) uses Fields for event handling  Fields trigger events immediately when modifying a field’s value (e.g. setValue())  Events propagate immediately when triggered  Events are not evaluated / acted upon until the field’s value is requested (e.g. getValue()) ◦ Lazy evaluation, by default ◦ Immediate evaluation when using the “AutoUpdate” template in C++

Fields - Example AB C DE A.setValue(1)

Fields - Example AB C DE E.getValue()D.getValue()B.getValue()A.getValue()

Fields - SF Fields  Contain a single data value of a specified type ◦ SFFloat, SFInt32, SFBool, SFString ◦ SFVec2f, SFVec3f ◦ SFNode  Can create own SF types in C++  Need to define the setValueFromString() function in C++ in order to be recognisable by the X3D parser

Fields - MF Fields  Contain an array of values of a specified type ◦ MFFloat, MFInt32, MFBool, MFString ◦ MFVec2f, MFVec3f ◦ MFNode  Can create own MF types in C++ as with SF  Can set/get entire array, or individual elements  Iterate (from C++)  MFNode (and SFNode) performs reference counting to automatically reference and unreference the nodes in the array.

Fields – Function fields  X3D concept - a field that executes code during its update check ◦ Can act as a function (in the mathematical sense), mapping an input value to an output value ◦ Can perform any action, e.g. file I/O, graphics rendering, etc ◦ Strongly typed: has an output type, and an input type ◦ Input type can be composite, e.g.  “greater_than” field:  output type: SFBool  input type: ( SFFloat, SFFloat )

TypedField  Adds type checking to field routes.  Allows specification of input route types and resulting type. class DotProduct: public TypedField< SFFloat, Types > { virtual void update() { const Vec3f &v1 = static_cast (routes_in[0]) ->getValue(); const Vec3f &v2 = static_cast (routes_in[1]) ->getValue(); value = v1 * v2; }

AutoUpdate  Updates its value when event received  Eager evaluation

PeriodicUpdate  Allows the field value to be polled at certain intervals( by default each scene-graph loop ).  Period can be specified in time or scene-graph loops.

Dependent fields  SF/MFNode types where the status of the field is dependent on a field in the node it contains.  Changes to the dependent field causes an event on the SF/MFNode. typedef DependentSFNode< X3DCoordinateNode FieldRef< X3DGeometricPropertyNode, Field, &X3DCoordinateNode::propertyChanged > > SFCoordinateNode;