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.
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.

Private Attributes

boost::scoped_ptr
< node_metatype_registry
node_metatype_registry_
const boost::scoped_ptr
< null_node_metatype
null_node_metatype_
 “Null” class object for default nodes (e.g., default_viewpoint).
const boost::scoped_ptr
< null_node_type
null_node_type_
 “Null” type object for default nodes (e.g., default_viewpoint).
boost::shared_mutex load_root_scene_thread_mutex_
 Mutex protecting load_root_scene_thread_.
boost::scoped_ptr< boost::thread > load_root_scene_thread_
 The thread that loads the root scene.
boost::thread_group load_proto_thread_group_
 The threads that load EXTERNPROTO implementations.
script_node_metatype script_node_metatype_
 node_metatype for Script nodes in the browser.
resource_fetcherfetcher_
 A reference to the resource_fetcher associated with the browser.
boost::shared_mutex scene_mutex_
 Mutex protecting scene_.
boost::scoped_ptr< scenescene_
 Pointer to the root scene.
const boost::intrusive_ptr
< viewpoint_node
default_viewpoint_
 The “default” viewpoint_node used when no viewpoint_node in the scene is bound.
boost::shared_mutex active_viewpoint_mutex_
 Mutex protecting active_viewpoint_.
viewpoint_nodeactive_viewpoint_
 The currently “active” viewpoint_node.
const boost::intrusive_ptr
< navigation_info_node
default_navigation_info_
 The “default” navigation_info_node used when no navigation_info_node in the scene is bound.
boost::shared_mutex active_navigation_info_mutex_
 Mutex protecting active_navigation_info_.
navigation_info_nodeactive_navigation_info_
 The currently “active” navigation_info_node.
boost::shared_mutex viewpoint_list_mutex_
 Mutex protecting viewpoint_list_.
std::list< viewpoint_node * > viewpoint_list_
 A list of all the Viewpoint nodes in the browser.
boost::shared_mutex scoped_lights_mutex_
 Mutex protecting scoped_lights_.
std::list< scoped_light_node * > scoped_lights_
 A list of all the scoped light nodes in the browser.
boost::shared_mutex scripts_mutex_
 Mutex protecting scripts_.
std::list< script_node * > scripts_
 A list of all the Script nodes in the browser.
boost::shared_mutex timers_mutex_
 Mutex protecting timers_.
std::list< time_dependent_node * > timers_
 A list of all the TimeSensor nodes in the browser.
boost::shared_mutex listeners_mutex_
 Mutex to guard listeners_.
std::set< browser_listener * > listeners_
 The set of browser_listeners that will receive browser_events.
bool new_view
 Flag to indicate if the user has changed to a new view.
boost::shared_mutex delta_time_mutex_
 Mutex protecting delta_time.
double delta_time
 Time elapsed since the last update.
boost::shared_mutex viewer_mutex_
 Mutex protecting viewer_.
openvrml::viewerviewer_
 The current viewer.
bool modified_
 Flag to indicate whether the browser has been modified.
boost::shared_mutex modified_mutex_
 Mutex protecting modified_.
boost::shared_mutex frame_rate_mutex_
 Mutex protecting frame_rate_.
double frame_rate_
 Frame rate.
boost::mutex out_mutex_
 Mutex guarding out_.
std::ostream *const out_
 Output stream, generally for console output.
boost::mutex err_mutex_
 Mutex guarding err_.
std::ostream *const err_
 Error output stream.

Friends

class scene
 The scene.
class script_node
class local::externproto_node
class local::externproto_node_type
class local::externproto_node_metatype
struct local::vrml97_parse_actions
struct local::x3d_vrml_parse_actions
bool operator== (const node_type &, const node_type &) throw ()
void local::parse_vrml (std::istream &in, const std::string &uri, const std::string &type, const openvrml::scene &scene, std::vector< boost::intrusive_ptr< node > > &nodes, std::map< std::string, std::string > &meta)

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] nc 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.


Friends And Related Function Documentation

class openvrml::browser::scene [friend]

The scene.


Member Data Documentation

“Null” class object for default nodes (e.g., default_viewpoint).

For internal use only.

“Null” type object for default nodes (e.g., default_viewpoint).

For internal use only.

boost::shared_mutex openvrml::browser::load_root_scene_thread_mutex_ [private]

Mutex protecting load_root_scene_thread_.

For internal use only.

boost::scoped_ptr< boost::thread > openvrml::browser::load_root_scene_thread_ [private]

The thread that loads the root scene.

For internal use only.

This thread is spawned by load_url. It is joined there (in a subsequent call to load_url) or when the browser is destroyed.

boost::thread_group openvrml::browser::load_proto_thread_group_ [private]

The threads that load EXTERNPROTO implementations.

For internal use only.

These threads must be joined by the browser before it is destroyed.

A reference to the resource_fetcher associated with the browser.

For internal use only.

boost::shared_mutex openvrml::browser::scene_mutex_ [mutable, private]

Mutex protecting scene_.

For internal use only.

Pointer to the root scene.

For internal use only.

boost::intrusive_ptr< openvrml::node > openvrml::browser::default_viewpoint_ [private]

The “default” viewpoint_node used when no viewpoint_node in the scene is bound.

For internal use only.

boost::shared_mutex openvrml::browser::active_viewpoint_mutex_ [mutable, private]

Mutex protecting active_viewpoint_.

For internal use only.

The currently “active” viewpoint_node.

For internal use only.

The “default” navigation_info_node used when no navigation_info_node in the scene is bound.

For internal use only.

boost::shared_mutex openvrml::browser::active_navigation_info_mutex_ [mutable, private]

Mutex protecting active_navigation_info_.

For internal use only.

The currently “active” navigation_info_node.

For internal use only.

boost::shared_mutex openvrml::browser::viewpoint_list_mutex_ [mutable, private]

Mutex protecting viewpoint_list_.

For internal use only.

A list of all the Viewpoint nodes in the browser.

For internal use only.

boost::shared_mutex openvrml::browser::scoped_lights_mutex_ [private]

Mutex protecting scoped_lights_.

For internal use only.

A list of all the scoped light nodes in the browser.

For internal use only.

boost::shared_mutex openvrml::browser::scripts_mutex_ [private]

Mutex protecting scripts_.

For internal use only.

A list of all the Script nodes in the browser.

For internal use only.

boost::shared_mutex openvrml::browser::timers_mutex_ [private]

Mutex protecting timers_.

For internal use only.

A list of all the TimeSensor nodes in the browser.

For internal use only.

boost::mutex openvrml::browser::listeners_mutex_ [private]

Mutex to guard listeners_.

For internal use only.

The set of browser_listeners that will receive browser_events.

For internal use only.

See also:
add_listener

remove_listener

Flag to indicate if the user has changed to a new view.

For internal use only.

boost::shared_mutex openvrml::browser::delta_time_mutex_ [mutable, private]

Mutex protecting delta_time.

For internal use only.

Time elapsed since the last update.

For internal use only.

boost::shared_mutex openvrml::browser::viewer_mutex_ [mutable, private]

Mutex protecting viewer_.

For internal use only.

openvrml::openvrml::viewer * openvrml::browser::viewer_ [private]

The current viewer.

For internal use only.

Flag to indicate whether the browser has been modified.

boost::shared_mutex openvrml::browser::modified_mutex_ [mutable, private]

Mutex protecting modified_.

boost::shared_mutex openvrml::browser::frame_rate_mutex_ [mutable, private]

Mutex protecting frame_rate_.

For internal use only.

Frame rate.

For internal use only.

boost::mutex openvrml::browser::out_mutex_ [mutable, private]

Mutex guarding out_.

std::ostream & openvrml::browser::out_ [private]

Output stream, generally for console output.

boost::mutex openvrml::browser::err_mutex_ [mutable, private]

Mutex guarding err_.

std::ostream & openvrml::browser::err_ [private]

Error output stream.

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.