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
A B
C
D E
A.setValue(1)
Fields - Example
A B
C
D E
E.getValue()D.getValue()B.getValue()A.getValue()
1 1 1
1
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< SFVec3f, SFVec3f > > { virtual void update() { const Vec3f &v1 = static_cast< SFVec3f * >(routes_in[0])
->getValue(); const Vec3f &v2 = static_cast< SFVec3f * >(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.