Home | Download | Screen shots | Discussion | Documentation
--- | --- | --- | --- | ---

- Main Page
- Namespaces
- Classes
- Files
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions
openvrml::browser Class Reference

Encapsulates a VRML browser. More...

`#include <openvrml/browser.h>`

List of all members.

## Public Member Functions

| browser (resource_fetcher &fetcher, std::ostream &out, std::ostream &err) throw ( std::bad_alloc )
| Constructor.
virtual | ~browser () throw ()
| Destructor.
void | add_node_metatype (const node_metatype_id &id, const boost::shared_ptr< openvrml::node_metatype > &metatype) throw ( std::invalid_argument , std::bad_alloc )
| Add a `node_metatype`.
const boost::shared_ptr < openvrml::node_metatype > | node_metatype (const node_metatype_id &id) const throw ()
| Get the `node_metatype` corresponding to `id`.
scene * | root_scene () const throw ()
| Get the root `scene`.
const node_path | find_node (const node &n) const throw ( std::bad_alloc )
| Get the path to a `node` in the scene graph.
viewpoint_node & | active_viewpoint () const throw ()
| Get the active `viewpoint_node`.
void | active_viewpoint (viewpoint_node &viewpoint) throw ()
| Set the active `viewpoint_node`.
void | reset_default_viewpoint () throw ()
| Reset the active `viewpoint_node` to the default.
navigation_info_node & | active_navigation_info () const throw ()
| Get the active `navigation_info_node`.
void | active_navigation_info (navigation_info_node &nav_info) throw ()
| Set the active `navigation_info_node`.
void | reset_default_navigation_info () throw ()
| Reset the active `navigation_info_node` to the default.
void | add_viewpoint (viewpoint_node &viewpoint) throw ( std::bad_alloc )
| Add a `viewpoint_node` to the list of `viewpoint_nodes` for the `browser`.
void | remove_viewpoint (viewpoint_node &viewpoint) throw ()
| Remove a `viewpoint_node` from the list of `viewpoint_nodes` for the `browser`.
const std::list< viewpoint_node * > | viewpoints () const throw ()
| Get the list of `viewpoint_nodes` for the world.
void | viewer (openvrml::viewer *v) throw ( viewer_in_use )
| Set the current `viewer`.
openvrml::viewer * | viewer () const throw ()
| The current `viewer`.
virtual const char * | name () const throw ()
| Get the browser name.
virtual const char * | version () const throw ()
| Get the `browser` version.
float | current_speed ()
| Get the average navigation speed in meters per second.
const std::string | world_url () const throw ( std::bad_alloc )
| Get the URI for the world.
void | set_world (resource_istream &in)
| Set the world from a stream.
void | replace_world (const std::vector< boost::intrusive_ptr< node > > &nodes)
| Replace the root nodes of the world.
void | load_url (const std::vector< std::string > &url, const std::vector< std::string > &parameter) throw ( std::bad_alloc , boost::thread_resource_error )
| Asynchronously load a VRML world into the `browser`.
virtual void | description (const std::string &description)
| Send a string to the user interface.
const std::vector < boost::intrusive_ptr< node > > | create_vrml_from_stream (std::istream &in, const std::string &type=vrml_media_type)
| Generate nodes from a stream of VRML syntax.
void | create_vrml_from_url (const std::vector< std::string > &url, const boost::intrusive_ptr< node > &node, const std::string &event) throw ( unsupported_interface , std::bad_cast , boost::thread_resource_error )
| Create nodes from a URI.
bool | add_listener (browser_listener &listener) throw ( std::bad_alloc )
| Add a listener for `browser_events`.
bool | remove_listener (browser_listener &listener) throw ()
| Remove a listener for `browser_events`.
void | sensitive_event (node *object, double timestamp, bool is_over, bool is_active, const double(&point)[3])
double | frame_rate () const
| Get the current frame rate.
bool | update (double current_time=-1.0)
| Process events (update the `browser`).
void | render ()
| Draw this `browser` into the specified `viewer`.
void | modified (bool value)
| Indicate whether rendering is necessary.
bool | modified () const
| Check if the browser has been modified.
void | delta (double d)
| Set the time until the next update is needed.
double | delta () const
| Get the time interval between `browser` updates.
void | add_scoped_light (scoped_light_node &)
| Add a scoped light node to the `browser`.
void | remove_scoped_light (scoped_light_node &)
| Remove a scoped light node from the `browser`.
void | add_time_dependent (time_dependent_node &n)
| Add a time-dependent node to the browser.
void | remove_time_dependent (time_dependent_node &n)
| Remove a time-dependent node from the browser.
void | add_script (script_node &)
| Add a Script node to the browser.
void | remove_script (script_node &)
| Remove a Script node from the browser.
void | update_flags ()
| Propagate the bvolume dirty flag from children to ancestors.
void | out (const std::string &str) const
| Print a message to the output stream.
void | err (const std::string &str) const
| Print a message to the error stream.

## Static Public Member Functions

static double | current_time () throw ()
| Get the current time.

## Public Attributes

bool | flags_need_updating
| Set by `node::bounding_volume_dirty` on any node in this browser graph, cleared by `update_flags`.

## Protected Member Functions

bool | headlight_on ()
| Indicate whether the headlight is on.

## Detailed Description

Encapsulates a VRML browser.

`browser` is the foundation of the OpenVRML runtime. `browser` is instantiated with an implementation of `resource_fetcher`, which is provided by application code. The `resource_fetcher` instance must have a longer lifetime than the `browser` instance, since the `resource_fetcher` instance could be used during destruction of the `browser`. Note, however, that `browser`'s destructor will block until all threads that may use the `resource_fetcher` have completed. So it is sufficient to have the `browser` and the `resource_fetcher` destroyed sequentially in the same thread.

See also:
  openvrml::resource_fetcher

Examples:

  sdl_viewer.cpp.

## Constructor & Destructor Documentation

openvrml::browser::browser | ( | resource_fetcher & | fetcher,
|  | std::ostream & | out,
|  | std::ostream & | err
| ) |  | throw ( std::bad_alloc )

Constructor.

Parameters:

  [in] | fetcher | a `resource_fetcher` implementation.
  [in] | out | output stream for console output.
  [in] | err | output stream for error console output.

Exceptions:

  std::bad_alloc | if memory allocation fails.

openvrml::browser::~browser | ( |  | ) | throw ()`[virtual]`

Destructor.

## Member Function Documentation

double openvrml::browser::current_time | ( |  | ) | throw ()`[static]`

Get the current time.

void openvrml::browser::add_node_metatype | ( | const node_metatype_id & | id,
|  | const boost::shared_ptr< openvrml::node_metatype > & | metatype
| ) |  | throw ( std::invalid_argument , std::bad_alloc )

Add a `node_metatype`.

If a `node_metatype` identified by `id` has already been added to the browser, it will be replaced.

Warning:
  If `std::bad_alloc` is thrown here, the `browser`'s `node_metatype` map is left in an unknown state. In all likelihood any preexisting entry in the map with the same implementation identifier as `id` will have been removed.

Parameters:

  [in] | id | a `node_metatype` identifier.
  [in] | metatype | a `boost::shared_ptr` to a `node_metatype`

Exceptions:

  std::invalid_argument | if `nc` is null.
  std::bad_alloc | if memory allocation fails.

const boost::shared_ptr< openvrml::node_metatype > openvrml::browser::node_metatype | ( | const node_metatype_id & | id | ) | const throw ()

Get the `node_metatype` corresponding to `id`.

Parameters:

  [in] | id | a `node_metatype` identifier.

Returns:
  the `node_metatype` corresponding to `id`; or a null pointer if no such `node_metatype` exists.

openvrml::scene * openvrml::browser::root_scene | ( |  | ) | const throw ()

Get the root `scene`.

Returns:
  the root `scene`, or 0 if no `scene` is loaded.

const openvrml::node_path openvrml::browser::find_node | ( | const node & | n | ) | const throw ( std::bad_alloc )

Get the path to a `node` in the scene graph.

Parameters:

  [in] | n | the objective `node`.

Returns:
  the path to `node`, starting with a root `node`, and ending with `node`. If `node` is not in the scene graph, the returned `node_path` is empty.

Exceptions:

  std::bad_alloc | if memory allocation fails.

openvrml::viewpoint_node & openvrml::browser::active_viewpoint | ( |  | ) | const throw ()

Get the active `viewpoint_node`.

The active `viewpoint_node` is the one currently associated with the user view.

Returns:
  the active `viewpoint_node`.

void openvrml::browser::active_viewpoint | ( | viewpoint_node & | viewpoint | ) | throw ()

Set the active `viewpoint_node`.

Parameters:

  [in] | viewpoint | a `viewpoint_node`.

Precondition:
  `viewpoint.scene()` == `this->root_scene()`

void openvrml::browser::reset_default_viewpoint | ( |  | ) | throw ()

Reset the active `viewpoint_node` to the default.

openvrml::navigation_info_node & openvrml::browser::active_navigation_info | ( |  | ) | const throw ()

Get the active `navigation_info_node`.

The active `navigation_info_node` is the one currently associated with the user view.

Returns:
  the active `navigation_info_node`.

void openvrml::browser::active_navigation_info | ( | navigation_info_node & | nav_info | ) | throw ()

Set the active `navigation_info_node`.

Parameters:

  [in] | nav_info | a `navigation_info_node`.

Precondition:
  `viewpoint.scene()` == `this->root_scene()`

void openvrml::browser::reset_default_navigation_info | ( |  | ) | throw ()

Reset the active `navigation_info_node` to the default.

void openvrml::browser::add_viewpoint | ( | viewpoint_node & | viewpoint | ) | throw ( std::bad_alloc )

Add a `viewpoint_node` to the list of `viewpoint_nodes` for the `browser`.

Parameters:

  [in] | viewpoint | a `viewpoint_node`.

Exceptions:

  std::bad_alloc | if memory allocation fails.

Precondition:
  `viewpoint` is not in the list of `viewpoint_nodes` for the `browser`.

void openvrml::browser::remove_viewpoint | ( | viewpoint_node & | viewpoint | ) | throw ()

Remove a `viewpoint_node` from the list of `viewpoint_nodes` for the `browser`.

Parameters:

  [in] | viewpoint | a `viewpoint_node`.

Precondition:
  `viewpoint` is in the list of `viewpoint_nodes` for the `browser`.

const std::list< openvrml::viewpoint_node * > openvrml::browser::viewpoints | ( |  | ) | const throw ()

Get the list of `viewpoint_nodes` for the world.

Returns:
  the list of `viewpoint_nodes` for the world.

void openvrml::browser::viewer | ( | openvrml::viewer * | v | ) | throw ( viewer_in_use )

Set the current `viewer`.

Parameters:

  [in] | v | `viewer`.

Exceptions:

  viewer_in_use | if `v` is already associated with a `browser`.

openvrml::viewer * openvrml::browser::viewer | ( |  | ) | const throw ()

The current `viewer`.

Returns:
  the current `viewer`.

const char * openvrml::browser::name | ( |  | ) | const throw ()`[virtual]`

Get the browser name.

Returns:
  "OpenVRML"

Specific browsers may wish to override this method.

const char * openvrml::browser::version | ( |  | ) | const throw ()`[virtual]`

Get the `browser` version.

Returns:
  the version of OpenVRML.

Specific browsers may wish to override this method.

float openvrml::browser::current_speed | ( |  | ) |

Get the average navigation speed in meters per second.

Returns:
  the average navigation speed.

const std::string openvrml::browser::world_url | ( |  | ) | const throw ( std::bad_alloc )

Get the URI for the world.

Returns:
  the URI for the world.

void openvrml::browser::set_world | ( | resource_istream & | in | ) |

Set the world from a stream.

Parameters:

  [in,out] | in | an input stream.

Exceptions:

  bad_media_type | if `in.type()` is not `model/vrml`, `x-world/x-vrml`, or `model/x3d-vrml`.
  invalid_vrml | if `in` has invalid syntax.

void openvrml::browser::replace_world | ( | const std::vector< boost::intrusive_ptr< node > > & | nodes | ) |

Replace the root nodes of the world.

Parameters:

  [in] | nodes | new root nodes for the world.

void openvrml::browser::load_url | ( | const std::vector< std::string > & | url,
|  | const std::vector< std::string > & | parameter
| ) |  | throw ( std::bad_alloc , boost::thread_resource_error )

Asynchronously load a VRML world into the `browser`.

This function takes an alternative URI list consistent with such lists as they appear in VRML nodes. `openvrml::browser_event::initialized` will be emitted once the world has been loaded and initialized.

For synchronously loading a world, see `set_world`.

Parameters:

  [in] | url | a URI.
  [in] | parameter | parameters for `url`.

Exceptions:

  std::bad_alloc | if memory allocation fails.
  boost::thread_resource_error | if thread creation fails.

See also:
  set_world

void openvrml::browser::description | ( | const std::string & | description | ) | `[virtual]`

Send a string to the user interface.

The default implementation of this method simply prints `description` to out. Subclasses can override this method to direct messages to an application's UI; for instance, a status bar.

Parameters:

  [in] | description | a string.

const std::vector< boost::intrusive_ptr< openvrml::node > > openvrml::browser::create_vrml_from_stream | ( | std::istream & | in,
|  | const std::string & | type = `vrml_media_type`
| ) |  |

Generate nodes from a stream of VRML syntax.

In addition to the exceptions listed, this method may throw any exception that may result from reading the input stream.

Parameters:

  [in,out] | in | an input stream.
  [in] | type | MIME content type of `in`.

Returns:
  the root nodes generated from `in`.

Exceptions:

  invalid_vrml | if `in` has invalid VRML syntax.
  std::invalid_argument | if `type` refers to an unsupported content type.
  std::bad_alloc | if memory allocation fails.

void openvrml::browser::create_vrml_from_url | ( | const std::vector< std::string > & | url,
|  | const boost::intrusive_ptr< node > & | node,
|  | const std::string & | event
| ) |  | throw ( unsupported_interface , std::bad_cast , boost::thread_resource_error )

Create nodes from a URI.

This function executes asynchronously. When the nodes have been completely loaded, they are sent to the `event` MFNode eventIn of `node`.

Parameters:

  [in] | url | an alternative URI list.
  [in] | node | the node to which the nodes loaded from `url` should be sent as an event.
  [in] | event | the event of `node` to which the new nodes will be sent.

Exceptions:

  unsupported_interface | if `node` has no eventIn `event`.
  std::bad_cast | if the `event` eventIn of `node` is not an MFNode.
  boost::thread_resource_error | if thread creation fails.

bool openvrml::browser::add_listener | ( | browser_listener & | listener | ) | throw ( std::bad_alloc )

Add a listener for `browser_events`.

Parameters:

  [in] | listener | a `browser_listener`.

Returns:
  `true` if `listener` is added successfully; `false` otherwise (if `listener` is already listening for events from the `browser`).

Exceptions:

  std::bad_alloc | if memory allocation fails.

bool openvrml::browser::remove_listener | ( | browser_listener & | listener | ) | throw ()

Remove a listener for `browser_events`.

Parameters:

  [in] | listener | a `browser_listener`.

Returns:
  `true` if `listener` is removed successfully; `false` otherwise (if `listener` is not listening for events from the `browser`).

void openvrml::browser::sensitive_event | ( | node * | object,
|  | double | timestamp,
|  | bool | is_over,
|  | bool | is_active,
|  | const double(&) | point[3]
| ) |  |

Called by the `viewer` when the cursor passes over, clicks, drags, or releases a sensitive object (an Anchor or another grouping node with an enabled TouchSensor child).

double openvrml::browser::frame_rate | ( |  | ) | const

Get the current frame rate.

Returns:
  the current frame rate.

bool openvrml::browser::update | ( | double | current_time = `-1.0` | ) |

Process events (update the `browser`).

This method should be called after each frame is rendered.

Returns:
  `true` if the `browser` needs to be rerendered, `false` otherwise.

void openvrml::browser::render | ( |  | ) |

Draw this `browser` into the specified `viewer`.

void openvrml::browser::modified | ( | bool | value | ) |

Indicate whether rendering is necessary.

Parameters:

  [in] | value | `true` to indicate that the browser state has changed and rerendering is necessary; `false` once rendering has occurred.

bool openvrml::browser::modified | ( |  | ) | const

Check if the browser has been modified.

Returns:
  `true` if the browser has been modified, `false` otherwise.

void openvrml::browser::delta | ( | double | d | ) |

Set the time until the next update is needed.

Parameters:

  [in] | d | a time interval.

double openvrml::browser::delta | ( |  | ) | const

Get the time interval between `browser` updates.

Returns:
  the time interval between `browser` updates.

void openvrml::browser::add_scoped_light | ( | scoped_light_node & | light | ) |

Add a scoped light node to the `browser`.

Parameters:

  [in] | light | a light node.

Precondition:
  `light` is not in the list of light nodes for the `browser`.

void openvrml::browser::remove_scoped_light | ( | scoped_light_node & | light | ) |

Remove a scoped light node from the `browser`.

Parameters:

  [in] | light | the light node to remove.

Precondition:
  `light` is in the list of light nodes for the `browser`.

void openvrml::browser::add_time_dependent | ( | time_dependent_node & | n | ) |

Add a time-dependent node to the browser.

Parameters:

  [in] | n | a `time_dependent_node`.

Precondition:
  `n` is not in the list of `time_dependent_nodes` for the `browser`.

void openvrml::browser::remove_time_dependent | ( | time_dependent_node & | n | ) |

Remove a time-dependent node from the browser.

Parameters:

  [in] | n | the `time_dependent_node` to remove.

Precondition:
  `n` is in the list of `time_dependent_nodes` for the `browser`.

void openvrml::browser::add_script | ( | script_node & | script | ) |

Add a Script node to the browser.

Parameters:

  [in] | script | a Script node.

Precondition:
  `script` is not in the list of Script nodes for the `browser`.

void openvrml::browser::remove_script | ( | script_node & | script | ) |

Remove a Script node from the browser.

Parameters:

  [in] | script | the Script node to remove.

Precondition:
  `script` is in the list of Script nodes for the `browser`.

void openvrml::browser::update_flags | ( |  | ) |

Propagate the bvolume dirty flag from children to ancestors.

The invariant is that if a `node`'s bounding volume is out of date, then the bounding volumes of all that `node`'s ancestors must be out of date. However, `node` does not maintain a parent pointer. So we must do a traversal of the entire browser graph to do the propagation.

See also:
  node::setBVolumeDirty
  node::isBVolumeDirty

void openvrml::browser::out | ( | const std::string & | str | ) | const

Print a message to the output stream.

Parameters:

  [in] | str | a string.

void openvrml::browser::err | ( | const std::string & | str | ) | const

Print a message to the error stream.

Parameters:

  [in] | str | a string.

bool openvrml::browser::headlight_on | ( |  | ) | `[protected]`

Indicate whether the headlight is on.

Returns:
  `true` if the headlight is on; `false` otherwise.

## Member Data Documentation

bool openvrml::browser::flags_need_updating

Set by `node::bounding_volume_dirty` on any node in this browser graph, cleared by `update_flags`.

`true` if the bvolume dirty flag has been set on a `node` in the `browser` graph, but has not yet been propagated to that `node`'s ancestors.