openvrml::browser Class Reference

Encapsulates a VRML browser. More...

#include <openvrml/browser.h>

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.
sceneroot_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_nodeactive_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_nodeactive_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::viewerviewer () 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]fetchera resource_fetcher implementation.
[in]outoutput stream for console output.
[in]erroutput stream for error console output.
Exceptions
std::bad_allocif 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]ida node_metatype identifier.
[in]metatypea boost::shared_ptr to a node_metatype
Exceptions
std::invalid_argumentif nc is null.
std::bad_allocif 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]ida 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]nthe 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_allocif 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]viewpointa 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_infoa 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]viewpointa viewpoint_node.
Exceptions
std::bad_allocif 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]viewpointa 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]vviewer.
Exceptions
viewer_in_useif 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]inan input stream.
Exceptions
bad_media_typeif in.type() is not model/vrml, x-world/x-vrml, or model/x3d-vrml.
invalid_vrmlif 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]nodesnew 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]urla URI.
[in]parameterparameters for url.
Exceptions
std::bad_allocif memory allocation fails.
boost::thread_resource_errorif 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]descriptiona 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]inan input stream.
[in]typeMIME content type of in.
Returns
the root nodes generated from in.
Exceptions
invalid_vrmlif in has invalid VRML syntax.
std::invalid_argumentif type refers to an unsupported content type.
std::bad_allocif 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]urlan alternative URI list.
[in]nodethe node to which the nodes loaded from url should be sent as an event.
[in]eventthe event of node to which the new nodes will be sent.
Exceptions
unsupported_interfaceif node has no eventIn event.
std::bad_castif the event eventIn of node is not an MFNode.
boost::thread_resource_errorif thread creation fails.
bool openvrml::browser::add_listener ( browser_listener listener) throw ( std::bad_alloc )

Add a listener for browser_events.

Parameters
[in]listenera browser_listener.
Returns
true if listener is added successfully; false otherwise (if listener is already listening for events from the browser).
Exceptions
std::bad_allocif memory allocation fails.
bool openvrml::browser::remove_listener ( browser_listener listener) throw ()

Remove a listener for browser_events.

Parameters
[in]listenera 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]valuetrue 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]da 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]lighta 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]lightthe 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]na 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]nthe 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]scripta 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]scriptthe 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]stra string.
void openvrml::browser::err ( const std::string &  str) const

Print a message to the error stream.

Parameters
[in]stra 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.