openvrml::browser Class Reference

Encapsulates a VRML browser. More...

#include <openvrml/browser.h>


Classes
class	node_metatype_map
	The map of `node_metatypes`. More...
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.
Static Private Member Functions
static void	parse_vrml (std::istream &in, const std::string &uri, const std::string &type, const openvrml::scene &scene, std::vector< boost::intrusive_ptr< openvrml::node > > &nodes, std::map< std::string, std::string > &meta)
	Parse a VRML stream.
Private Attributes
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`).
read_write_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.
node_metatype_map	node_metatype_map_
	A map of URIs to node implementations.
script_node_metatype	script_node_metatype_
	`node_metatype` for Script `nodes` in the `browser`.
resource_fetcher &	fetcher_
	A reference to the `resource_fetcher` associated with the `browser`.
read_write_mutex	scene_mutex_
	Mutex protecting `scene_`.
boost::scoped_ptr< scene >	scene_
	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.
read_write_mutex	active_viewpoint_mutex_
	Mutex protecting `active_viewpoint_`.
viewpoint_node *	active_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.
read_write_mutex	active_navigation_info_mutex_
	Mutex protecting `active_navigation_info_`.
navigation_info_node *	active_navigation_info_
	The currently “active” `navigation_info_node`.
read_write_mutex	viewpoint_list_mutex_
	Mutex protecting `viewpoint_list_`.
std::list< viewpoint_node * >	viewpoint_list_
	A list of all the Viewpoint `nodes` in the `browser`.
read_write_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`.
read_write_mutex	scripts_mutex_
	Mutex protecting `scripts_`.
std::list< script_node * >	scripts_
	A list of all the Script `nodes` in the `browser`.
read_write_mutex	timers_mutex_
	Mutex protecting `timers_`.
std::list< time_dependent_node * >	timers_
	A list of all the TimeSensor `nodes` in the `browser`.
read_write_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.
read_write_mutex	delta_time_mutex_
	Mutex protecting `delta_time`.
double	delta_time
	Time elapsed since the last update.
read_write_mutex	viewer_mutex_
	Mutex protecting `viewer_`.
openvrml::viewer *	viewer_
	The current `viewer`.
bool	modified_
	Flag to indicate whether the `browser` has been modified.
read_write_mutex	modified_mutex_
	Mutex protecting `modified_`.
read_write_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	externproto_node
bool	operator== (const node_type &, const node_type &) throw ()
	Compare for equality.

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

void openvrml::browser::parse_vrml	(	std::istream &	in,
		const std::string &	uri,
		const std::string &	type,
		const openvrml::scene &	scene,
		std::vector< boost::intrusive_ptr< openvrml::node > > &	nodes,
		std::map< std::string, std::string > &	meta
	)			`[static, private]`

Parse a VRML stream.

For internal use only.

Parameters:

`[in,out]`	in	input stream.
`[in]`	uri	URI associated with `in`.
`[in]`	type	MIME media type of the data to be read from `in`.
`[in]`	scene	a `scene`.
`[out]`	nodes	the root `nodes`.
`[out]`	meta	the `scene` metadata.

Exceptions:

	openvrml::bad_media_type
	openvrml::invalid_vrml

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 > &	nc
	)			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.

bool operator==	(	const node_type &	lhs,
		const node_type &	rhs
	)			throw () `[friend]`

Compare for equality.

Two node_types t and u are considered equal if all of the following are true:

t.id() == u.id()
t.interfaces() == u.interfaces()
t.metatype().id() is in the set of identifiers associated with u in the browser's node_metatype map.

Note that the latter requirement makes this comparison a rather expensive operation.

Parameters: