XdkWrl: NavigationInfo Class Reference

Home | Hierarchy | Members | Alphabetical | Related Pages

# NavigationInfo Class Reference
[Standard Node Types]

`#include <navigationinfo.h>`

Inherits Node.

List of all members.

## Public Member Functions
| NavigationInfo (const char *name="")
virtual | ~NavigationInfo ()
virtual unsigned int | nbFields () const
virtual FieldHandle | field (const std::string &n)
virtual FieldHandle | field (unsigned int i)
virtual bool | isSetToDefaultValue (unsigned int i) const
virtual unsigned int | nbEventsIn () const
virtual EventInHandle | eventIn (const std::string &n)
virtual EventInHandle | eventIn (unsigned int i)
virtual unsigned int | nbEventsOut () const
virtual EventOutHandle | eventOut (const std::string &n)
virtual EventOutHandle | eventOut (unsigned int i)
const char * | typeName () const
virtual Node * | duplicate () const
virtual Node * | duplicate (std::map< const Node *, Node * > &) const
## Public Attributes
Exposed Fields
A field that is capable of receiving events via an eventIn to change its value(s), and generating events via an eventOut when its value(s) change.
MFFloat | avatarSize
SFBool | headlight
SFFloat | speed
MFString | type
SFFloat | visibilityLimit
Events In
EventIn< SFBool > | set_bind
EventIn< MFFloat > | set_avatarSize
EventIn< SFBool > | set_headlight
EventIn< SFFloat > | set_speed
EventIn< MFString > | set_type
EventIn< SFFloat > | set_visibilityLimit
Events Out
EventOut< SFBool > | isBound
EventOut< MFFloat > | avatarSize_changed
EventOut< SFBool > | headlight_changed
EventOut< SFFloat > | speed_changed
EventOut< MFString > | type_changed
EventOut< SFFloat > | visibilityLimit_changed

## Detailed Description

Here is the documentation for this node type, from the ISO standard.

## 6.41 NavigationInfo

The NavigationInfo node contains information describing the physical characteristics of the viewer's avatar and viewing model. NavigationInfo node is a bindable node (see 4.6.10, Bindable children nodes). Thus, there exists a NavigationInfo node stack in which the top-most NavigationInfo node on the stack is the currently bound NavigationInfo node. The current NavigationInfo node is considered to be a child of the current Viewpoint node regardless of where it is initially located in the VRML file. Whenever the current Viewpoint nodes changes, the current NavigationInfo node shall be re-parented to it by the browser. Whenever the current NavigationInfo node changes, the new NavigationInfo node shall be re-parented to the current Viewpoint node by the browser.

If a TRUE value is sent to the set_bind eventIn of a NavigationInfo node, the node is pushed onto the top of the NavigationInfo node stack. When a NavigationInfo node is bound, the browser uses the fields of the NavigationInfo node to set the navigation controls of its user interface and the NavigationInfo node is conceptually re-parented under the currently bound Viewpoint node. All subsequent scaling changes to the current Viewpoint node's coordinate system automatically change aspects (see below) of the NavigationInfo node values used in the browser (e.g., scale changes to any ancestors' transformations). A FALSE value sent to set_bind pops the NavigationInfo node from the stack, results in an isBound FALSE event, and pops to the next entry in the stack which shall be re-parented to the current Viewpoint node. 4.6.10, Bindable children nodes, has more details on binding stacks.

The type field specifies an ordered list of navigation paradigms that specify a combination of navigation types and the initial navigation type. The navigation type of the currently bound NavigationInfo node determines the user interface capabilities of the browser. For example, if the currently bound NavigationInfo node's type is "WALK", the browser shall present a WALK navigation user interface paradigm (see below for description of WALK). Browsers shall recognize and support at least the following navigation types: "ANY", "WALK", "EXAMINE", "FLY", and "NONE".

If "ANY" does not appear in the type field list of the currently bound NavigationInfo, the browser's navigation user interface shall be restricted to the recognized navigation types specified in the list. In this case, browsers shall not present a user interface that allows the navigation type to be changed to a type not specified in the list. However, if any one of the values in the type field are "ANY", the browser may provide any type of navigation interface, and allow the user to change the navigation type dynamically. Furthermore, the first recognized type in the list shall be the initial navigation type presented by the browser's user interface.

ANY navigation specifies that the browser may choose the navigation paradigm that best suits the content and provide a user interface to allow the user to change the navigation paradigm dynamically. The results are undefined if the currently bound NavigationInfo's type value is "ANY" and Viewpoint transitions (see 6.53, Viewpoint) are triggered by the Anchor node (see 6.2, Anchor) or the `loadURL()`scripting method (see 4.12.10, Browser script interface).

WALK navigation is used for exploring a virtual world on foot or in a vehicle that rests on or hovers above the ground. It is strongly recommended that WALK navigation define the up vector in the +Y direction and provide some form of terrain following and gravity in order to produce a walking or driving experience. If the bound NavigationInfo's type is "WALK", the browser shall strictly support collision detection (see 6.8, Collision).

FLY navigation is similar to WALK except that terrain following and gravity may be disabled or ignored. There shall still be some notion of "up" however. If the bound NavigationInfo's type is "FLY", the browser shall strictly support collision detection (see 6.8, Collision).

EXAMINE navigation is used for viewing individual objects and often includes (but does not require) the ability to spin around the object and move the viewer closer or further away.

NONE navigation disables and removes all browser-specific navigation user interface forcing the user to navigate using only mechanisms provided in the scene, such as Anchor nodes or scripts that include `loadURL()`.

If the NavigationInfo type is "WALK", "FLY", "EXAMINE", or "NONE" or a combination of these types (i.e., "ANY" is not in the list), Viewpoint transitions (see 6.53, Viewpoint) triggered by the Anchor node (see 6.2, Anchor) or the `loadURL()`scripting method (see 4.12.10, Browser script interface) shall be implemented as a jump cut from the old Viewpoint to the new Viewpoint with transition effects that shall not trigger events besides the exit and enter events caused by the jump.

Browsers may create browser-specific navigation type extensions. It is recommended that extended type names include a unique suffix (e.g., HELICOPTER_mydomain.com) to prevent conflicts. Viewpoint transitions (see 6.53, Viewpoint) triggered by the Anchor node (see 6.2, Anchor) or the `loadURL()`scripting method (see 4.12.10, Browser script interface) are undefined for extended navigation types. If none of the types are recognized by the browser, the default "ANY" is used. These strings values are case sensitive ("any" is not equal to "ANY").

The speed field specifies the rate at which the viewer travels through a scene in metres per second. Since browsers may provide mechanisms to travel faster or slower, this field specifies the default, average speed of the viewer when the NavigationInfo node is bound. If the NavigationInfo type is EXAMINE, speed shall not affect the viewer's rotational speed. Scaling in the transformation hierarchy of the currently bound Viewpoint node (see above) scales the speed; parent translation and rotation transformations have no effect on speed. Speed shall be non-negative. Zero speed indicates that the avatar's position is stationary, but its orientation and field of view may still change. If the navigation type is "NONE", the speed field has no effect.

The avatarSize field specifies the user's physical dimensions in the world for the purpose of collision detection and terrain following. It is a multi-value field allowing several dimensions to be specified. The first value shall be the allowable distance between the user's position and any collision geometry (as specified by a Collision node ) before a collision is detected. The second shall be the height above the terrain at which the browser shall maintain the viewer. The third shall be the height of the tallest object over which the viewer can move. This allows staircases to be built with dimensions that can be ascended by viewers in all browsers. The transformation hierarchy of the currently bound Viewpoint node scales the avatarSize. Translations and rotations have no effect on avatarSize.

For purposes of terrain following, the browser maintains a notion of the down direction (down vector), since gravity is applied in the direction of the down vector. This down vector shall be along the negative Y-axis in the local coordinate system of the currently bound Viewpoint node (i.e., the accumulation of the Viewpoint node's ancestors' transformations, not including the Viewpoint node's orientation field).

Geometry beyond the visibilityLimit may not be rendered. A value of 0.0 indicates an infinite visibility limit. The visibilityLimit field is restricted to be greater than or equal to zero.

The speed, avatarSize and visibilityLimit values are all scaled by the transformation being applied to the currently bound Viewpoint node. If there is no currently bound Viewpoint node, the values are interpreted in the world coordinate system. This allows these values to be automatically adjusted when binding to a Viewpoint node that has a scaling transformation applied to it without requiring a new NavigationInfo node to be bound as well. The results are undefined if the scale applied to the Viewpoint node is non-uniform.

The headlight field specifies whether a browser shall turn on a headlight. A headlight is a directional light that always points in the direction the user is looking. Setting this field to TRUE allows the browser to provide a headlight, possibly with user interface controls to turn it on and off. Scenes that enlist precomputed lighting (e.g., radiosity solutions) can turn the headlight off. The headlight shall have intensity = 1, color = (1 1 1), ambientIntensity = 0.0, and direction = (0 0 -1).

It is recommended that the near clipping plane be set to one-half of the collision radius as specified in the avatarSize field (setting the near plane to this value prevents excessive clipping of objects just above the collision volume, and also provides a region inside the collision volume for content authors to include geometry intended to remain fixed relative to the viewer). Such geometry shall not be occluded by geometry outside of the collision volume.

## Constructor & Destructor Documentation

NavigationInfo | ( | const char * | name = `""` | ) |

Construct a node with all its fields set to default value, which is equivalent to the code below:

          avatarSize.push_back(SFFloat(0.25f));
        avatarSize.push_back(SFFloat(1.6f));
        avatarSize.push_back(SFFloat(0.75f));
      headlight = true;
      speed = 1.0f;

      visibilityLimit = 0.0f;

~NavigationInfo | ( |  | ) | `[virtual]`

Virtual destructor, does nothing

## Member Function Documentation

unsigned int nbFields | ( |  | ) | const`[inline, virtual]`

Returns the number of fields (exposed or not) for this node type.

Implements Node.

wrl::Node::FieldHandle field | ( | const std::string & | n | ) | `[virtual]`

Return a handle on the field named `n` of the node or a "unknown" typed handle if there is no such field. Valid names are:

- avatarSize
- headlight
- speed
- type
- visibilityLimit

Implements Node.

wrl::Node::FieldHandle field | ( | unsigned int | n | ) | `[virtual]`

Return a handle on the `i` th field of the node or a "unknown" typed handle if there is no such node. Here is how `i` is related to fields:

- 0 : avatarSize
- 1 : headlight
- 2 : speed
- 3 : type
- 4 : visibilityLimit This function is useful, with nbFields() if you want to traverse all fields of a Node.

Implements Node.

bool isSetToDefaultValue | ( | unsigned int | i | ) | const`[virtual]`

Implements Node.

unsigned int nbEventsIn | ( |  | ) | const`[inline, virtual]`

Returns the number of events in for this node type.

Implements Node.

wrl::Node::EventInHandle eventIn | ( | const std::string & | n | ) | `[virtual]`

Return a handle on the event in named `n` of the node or a "unknown" typed handle if there is no such event. Valid names are:

- set_bind
- set_avatarSize
- set_headlight
- set_speed
- set_type
- set_visibilityLimit

Implements Node.

wrl::Node::EventInHandle eventIn | ( | unsigned int | n | ) | `[virtual]`

Return a handle on the `i` th event in of the node or a "unknown" typed handle if there is no such node. Here is how `i` is related to fields:

- 0 : set_bind
- 1 : set_avatarSize
- 2 : set_headlight
- 3 : set_speed
- 4 : set_type
- 5 : set_visibilityLimit

This function is useful, with nbEventsIn() if you want to traverse all events in of a Node.

Implements Node.

unsigned int nbEventsOut | ( |  | ) | const`[inline, virtual]`

Returns the number of events out for this node type.

Implements Node.

wrl::Node::EventOutHandle eventOut | ( | const std::string & | n | ) | `[virtual]`

Return a handle on the event out named `n` of the node or a "unknown" typed handle if there is no such event. Valid names are:

- isBound
- avatarSize_changed
- headlight_changed
- speed_changed
- type_changed
- visibilityLimit_changed

Implements Node.

wrl::Node::EventOutHandle eventOut | ( | unsigned int | n | ) | `[virtual]`

Return a handle on the `i` th event out of the node or a "unknown" typed handle if there is no such node. Here is how `i` is related to fields:

- 0 : isBound
- 1 : avatarSize_changed
- 2 : headlight_changed
- 3 : speed_changed
- 4 : type_changed
- 5 : visibilityLimit_changed This function is useful, with nbEventsOut() if you want to traverse all events in of a Node.

Implements Node.

const char * typeName | ( |  | ) | const`[inline, virtual]`

Returns `"NavigationInfo"`. Useful for printing.

Implements Node.

wrl::Node * duplicate | ( |  | ) | const`[virtual]`

Returns a deep copy of this node, that is a fully independant node with all children (if any) also copied. This is mainly useful for instanciating protos.

Implements Node.

virtual Node* duplicate | ( | std::map< const Node *, Node * > & |  | ) | const`[virtual]`

Implements Node.

## Member Data Documentation

MFFloat avatarSize

See Detailed Description for meaning of this field. Default value is set to

               avatarSize.push_back(SFFloat(0.25f));
        avatarSize.push_back(SFFloat(1.6f));
        avatarSize.push_back(SFFloat(0.75f));

SFBool headlight

See Detailed Description for meaning of this field. Default value is set to

           headlight = true;

SFFloat speed

See Detailed Description for meaning of this field. Default value is set to

           speed = 1.0f;

MFString type

See Detailed Description for meaning of this field. Default value is set to

SFFloat visibilityLimit

See Detailed Description for meaning of this field. Default value is set to

           visibilityLimit = 0.0f;

EventIn<SFBool> set_bind

See Detailed Description for meaning of this event.

EventIn<MFFloat> set_avatarSize

Set event associated to exposedField avatarSize

EventIn<SFBool> set_headlight

Set event associated to exposedField headlight

EventIn<SFFloat> set_speed

Set event associated to exposedField speed

EventIn<MFString> set_type

Set event associated to exposedField type

EventIn<SFFloat> set_visibilityLimit

Set event associated to exposedField visibilityLimit

EventOut<SFBool> isBound

See Detailed Description for meaning of this event.

EventOut<MFFloat> avatarSize_changed

Changed event associated to exposedField avatarSize

EventOut<SFBool> headlight_changed

Changed event associated to exposedField headlight

EventOut<SFFloat> speed_changed

Changed event associated to exposedField speed

EventOut<MFString> type_changed

Changed event associated to exposedField type

EventOut<SFFloat> visibilityLimit_changed

Changed event associated to exposedField visibilityLimit

Generated on 5 Jan 2007 with version 1.5.1. |