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.