openvrml::browser Class Reference

Detailed Description

Encapsulates a VRML browser.


Public Types
typedef void(*)	scene_cb (cb_reason reason)
	A pointer to a browser callback function.
	destroy_world_id
	Destroy the world.
	replace_world_id
	Replace the world.
enum	cb_reason { destroy_world_id, replace_world_id }
	Valid reasons for browser callback. More...
Public Member Functions
	browser (std::ostream &out, std::ostream &err) throw (std::bad_alloc)
	Constructor.
virtual	~browser () throw ()
	Destructor.
const std::vector< node_ptr > &	root_nodes () const throw ()
	Get the root nodes for the browser.
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.
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 () 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	replace_world (const std::vector< node_ptr > &nodes)
virtual void	load_url (const std::vector< std::string > &url, const std::vector< std::string > &parameter) throw (std::bad_alloc)
	Load a resource into the browser.
virtual void	description (const std::string &description)
	Send a string to the user interface.
const std::vector< node_ptr >	create_vrml_from_stream (std::istream &in)
	Generate nodes from a stream of VRML syntax.
void	create_vrml_from_url (const std::vector< std::string > &url, const node_ptr &node, const std::string &event)
void	add_world_changed_callback (scene_cb)
	Add a callback function to be called when the world changes.
void	sensitive_event (node object, double timestamp, bool is_over, bool is_active, double point)
void	queue_event (double timestamp, field_value *value, const node_ptr &toNode, const std::string &to_eventin)
	Queue an event for a node.
bool	events_pending ()
	Check if any events are waiting to be distributed.
void	flush_events ()
	Discard all pending events.
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_navigation_info (vrml97_node::navigation_info_node &)
	Add a NavigationInfo node to the list of NavigationInfo nodes for the browser.
void	remove_navigation_info (vrml97_node::navigation_info_node &)
	Remove a NavigationInfo node from the list of NavigationInfo nodes for the browser.
vrml97_node::navigation_info_node *	bindable_navigation_info_top ()
	Get the active node on the bound NavigationInfo stack.
void	bindable_push (vrml97_node::navigation_info_node *)
	Push a NavigationInfo node onto the bound NavigationInfo node stack.
void	bindable_remove (vrml97_node::navigation_info_node *)
	Remove a NavigationInfo node from the bound NavigationInfo node stack.
void	add_scoped_light (vrml97_node::abstract_light_node &)
	Add a scoped light node to the browser.
void	remove_scoped_light (vrml97_node::abstract_light_node &)
	Remove a scoped light node from the browser.
void	add_time_sensor (vrml97_node::time_sensor_node &)
	Add a TimeSensor node to the browser.
void	remove_time_sensor (vrml97_node::time_sensor_node &)
	Remove a time_sensor node from the browser.
void	add_audio_clip (vrml97_node::audio_clip_node &)
	Add an AudioClip node to the browser.
void	remove_audio_clip (vrml97_node::audio_clip_node &)
	Remove an audio_clip node from the browser.
void	add_movie (vrml97_node::movie_texture_node &)
	Add a MovieTexture node to the browser.
void	remove_movie (vrml97_node::movie_texture_node &)
	Remove a movie_texture 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.
Static Public Member Functions
static double	current_time () throw ()
	Get the current time.
Public Attributes
std::ostream &	out
	Output stream, generally for console output.
std::ostream &	err
	Error output stream.
bool	flags_need_updating
	Set by node::setBVolumeDirty on any node in this browser graph, cleared by update_flags.
Protected Types
typedef std::list< scene_cb >	scene_cb_list_t
	List of functions to call when the world is changed.
	max_events = 400
	The maximum number of events which may be queued.
enum	{ max_events = 400 }
Protected Member Functions
bool	headlight_on ()
	Indicate whether the headlight is on.
void	do_callbacks (cb_reason reason)
	Execute browser callback functions.
const node_ptr	bindable_top (const bind_stack_t &stack)
	Get the top node of a bind_stack_t.
void	bindable_push (bind_stack_t &stack, const node_ptr &node)
	Push a node onto a bind_stack_t.
void	bindable_remove (bind_stack_t &stack, const node_ptr &node)
	Remove a node from a bind_stack_t.
Protected Attributes
scene_cb_list_t	scene_callbacks
	List of functions to call when the world is changed.
double	frame_rate_
	Frame rate.
event	event_mem [max_events]
	The event queue.
size_t	first_event
	Index of the first pending event.
size_t	last_event
	Index of the last pending event.
Private Types
typedef std::map< std::string, node_class_ptr >	node_class_map_t
	Maps URIs to node_classes.
typedef std::list< node_ptr >	bind_stack_t
	A list of bound nodes.
Private Member Functions
void	init_node_class_map ()
	Initialize the node_class map with the available node implementations.
Private Attributes
std::auto_ptr< null_node_class >	null_node_class_
	"Null" class object for default nodes (e.g., default_viewpoint).
std::auto_ptr< null_node_type >	null_node_type_
	"Null" type object for default nodes (e.g., default_viewpoint).
node_class_map_t	node_class_map
	A map of URIs to node implementations.
script_node_class	script_node_class_
	node_class for Script nodes in the browser.
scene *	scene_
	Pointer to the root scene.
const node_ptr	default_viewpoint_
	The "default" viewpoint_node used when no viewpoint_node in the scene is bound.
viewpoint_node *	active_viewpoint_
	The currently "active" viewpoint_node.
std::list< viewpoint_node * >	viewpoint_list
	A list of all the Viewpoint nodes in the browser.
bind_stack_t	navigation_info_stack
	The stack of bound NavigationInfo nodes.
std::list< node * >	navigation_infos
	A list of all the NavigationInfo nodes in the browser.
std::list< node * >	scoped_lights
	A list of all the scoped light nodes in the browser.
std::list< script_node * >	scripts
	A list of all the Script nodes in the browser.
std::list< node * >	timers
	A list of all the TimeSensor nodes in the browser.
std::list< node * >	audio_clips
	A list of all the AudioClip nodes in the browser.
std::list< node * >	movies
	A list of all the MovieTexture nodes in the browser.
bool	modified_
	Flag to indicate whether the browser has been modified.
bool	new_view
	Flag to indicate if the user has changed to a new view.
double	delta_time
	Time elapsed since the last update.
openvrml::viewer *	viewer_
	The current `viewer`.
Friends
class	Vrml97Parser
	VRML97 parser generated by ANTLR.
class	Vrml97RootScope
	Root scope that is initialized with the VRML97 node types.
Classes
struct	event
	An event. More...

Member Typedef Documentation

openvrml::browser::scene_cb

A pointer to a browser callback function.

The callback function provoides a way to let the app know when a world is loaded, changed, etc.

openvrml::browser::node_class_map_t [private]

Maps URIs to node_classes.

openvrml::browser::bind_stack_t [private]

A list of bound nodes.

openvrml::browser::scene_cb_list_t [protected]

List of functions to call when the world is changed.

Member Enumeration Documentation

enum openvrml::browser::cb_reason

Valid reasons for browser callback.

Enumerator:

destroy_world_id	Destroy the world.
replace_world_id	Replace the world.

anonymous enum [protected]

Enumerator:

max_events

The maximum number of events which may be queued.

Each browser can have a limited number of pending events. Repeatedly allocating/freeing events is slow (it would be nice to get rid of the field cloning, too), and if there are so many events pending, we are probably running too slow to handle them effectively anyway.

Constructor & Destructor Documentation

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

Constructor.

Parameters:

	out	output stream for console output.
	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.

const std::vector< node_ptr > & openvrml::browser::root_nodes ( ) const throw ()

Get the root nodes for the browser.

Returns:: the root nodes for the browser.

const 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:

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.

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:

viewpoint

a viewpoint_node.

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

Reset the active viewpoint_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:

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:

viewpoint

a viewpoint_node.

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

const std::list< 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:

v viewer.

Exceptions:

viewer_in_use if v is already associated with a browser.

viewer * openvrml::browser::viewer ( ) 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::replace_world ( const std::vector< node_ptr > & nodes )

Todo:: Implement me!

void openvrml::browser::load_url	(	const std::vector< std::string > &	url,
		const std::vector< std::string > &	parameter
	)			throw (std::bad_alloc) `[virtual]`

Load a resource into the browser.

The default implementation of this method simply loads a VRML world into the browser. If the resource at url is not a VRML world, this method as no effect.

Implementations should override this method to handle non-VRML resources, handing them off to a Web browser or other appropriate handler.

Parameters:

	url	a URI.
	parameter	parameters for `url`.

Todo:: Make this asynchronous.

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:

description

a string.

const std::vector< node_ptr > openvrml::browser::create_vrml_from_stream ( std::istream & in )

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:

an input stream.

Returns:: the root nodes generated from in.

Exceptions:

	invalid_vrml	if `in` has invalid VRML syntax.
	std::bad_alloc	if memory allocation fails.

void openvrml::browser::create_vrml_from_url	(	const std::vector< std::string > &	url,
		const node_ptr &	node,
		const std::string &	event
	)

Todo:: Implement me!

void openvrml::browser::add_world_changed_callback ( scene_cb cb )

Add a callback function to be called when the world changes.

Parameters:

a browser callback function.

void openvrml::browser::sensitive_event	(	node *	object,
		double	timestamp,
		bool	is_over,
		bool	is_active,
		double *	point
	)

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

void openvrml::browser::queue_event	(	double	timestamp,
		field_value *	value,
		const node_ptr &	to_node,
		const std::string &	to_eventin
	)

Queue an event for a node.

Current events are in the array event_mem[first_event, last_event). If first_event == last_event, the queue is empty. There is a fixed maximum number of events. If we are so far behind that the queue is filled, the oldest events get overwritten.

bool openvrml::browser::events_pending ( )

Check if any events are waiting to be distributed.

Returns:: true if there are pending events, false otherwise.

void openvrml::browser::flush_events ( )

Discard all pending events.

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:

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:

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_navigation_info ( vrml97_node::navigation_info_node & node )

Add a NavigationInfo node to the list of NavigationInfo nodes for the browser.

Parameters:

node

a NavigationInfo node.

Precondition:: node is not in the list of NavigationInfo nodes for the browser.

void openvrml::browser::remove_navigation_info ( vrml97_node::navigation_info_node & n )

Remove a NavigationInfo node from the list of NavigationInfo nodes for the browser.

Parameters:

a NavigationInfo node.

Precondition:: n is in the list of NavigationInfo nodes for the browser.

vrml97_node::navigation_info_node * openvrml::browser::bindable_navigation_info_top ( )

Get the active node on the bound NavigationInfo stack.

Returns:: the active node on the bound NavigationInfo stack.

void openvrml::browser::bindable_push ( vrml97_node::navigation_info_node * n )

Push a NavigationInfo node onto the bound NavigationInfo node stack.

Parameters:

a NavigationInfo node.

void openvrml::browser::bindable_remove ( vrml97_node::navigation_info_node * n )

Remove a NavigationInfo node from the bound NavigationInfo node stack.

Parameters:

a NavigationInfo node.

void openvrml::browser::add_scoped_light ( vrml97_node::abstract_light_node & light )

Add a scoped light node to the browser.

Parameters:

light

a light node.

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

void openvrml::browser::remove_scoped_light ( vrml97_node::abstract_light_node & light )

Remove a scoped light node from the browser.

Parameters:

light

the light node to remove.

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

void openvrml::browser::add_time_sensor ( vrml97_node::time_sensor_node & timer )

Add a TimeSensor node to the browser.

Parameters:

timer

a TimeSensor node.

Precondition:: timer is not in the list of TimeSensor nodes for the browser.

void openvrml::browser::remove_time_sensor ( vrml97_node::time_sensor_node & timer )

Remove a time_sensor node from the browser.

Parameters:

timer

the time_sensor node to remove.

Precondition:: timer is in the list of time_sensor nodes for the browser.

void openvrml::browser::add_audio_clip ( vrml97_node::audio_clip_node & audio_clip )

Add an AudioClip node to the browser.

Parameters:

audio_clip

an audio_clip node.

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

void openvrml::browser::remove_audio_clip ( vrml97_node::audio_clip_node & audio_clip )

Remove an audio_clip node from the browser.

Parameters:

audio_clip

the audio_clip node to remove.

Precondition:: audio_clip is in the list of audio_clip nodes for the browser.

void openvrml::browser::add_movie ( vrml97_node::movie_texture_node & movie )

Add a MovieTexture node to the browser.

Parameters:

movie

a MovieTexture node.

Precondition:: movie is not in the list of MovieTexture nodes for the browser.

void openvrml::browser::remove_movie ( vrml97_node::movie_texture_node & movie )

Remove a movie_texture node from the browser.

Parameters:

movie

the movie_texture node to remove.

Precondition:: movie is in the list of movie_texture nodes for the browser.

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

Add a Script node to the browser.

Parameters:

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:

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 nodes'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

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

Indicate whether the headlight is on.

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

void openvrml::browser::do_callbacks ( cb_reason reason ) [protected]

Execute browser callback functions.

Parameters:

reason

the cb_reason to pass to the callback functions.

const node_ptr openvrml::browser::bindable_top ( const bind_stack_t & stack ) [protected]

Get the top node of a bind_stack_t.

Returns:: the top node of stack.

void openvrml::browser::bindable_push	(	bind_stack_t &	stack,
		const node_ptr &	node
	)			`[protected]`

Push a node onto a bind_stack_t.

Parameters:

	stack	the bind_stack_t onto which to push `node`.
	node	the node to push onto `stack`.

void openvrml::browser::bindable_remove	(	bind_stack_t &	stack,
		const node_ptr &	node
	)			`[protected]`

Remove a node from a bind_stack_t.

Parameters:

	stack	the bind_stack_t from which to remove `node`.
	node	the node to remove from `stack`.

void openvrml::browser::init_node_class_map ( ) [private]

Initialize the node_class map with the available node implementations.

Friends And Related Function Documentation

openvrml::browser::Vrml97Parser [friend]

VRML97 parser generated by ANTLR.

openvrml::browser::Vrml97RootScope [friend]

Root scope that is initialized with the VRML97 node types.

Member Data Documentation

std::auto_ptr< null_node_class > openvrml::browser::null_node_class_ [private]

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

std::auto_ptr< null_node_type > openvrml::browser::null_node_type_ [private]

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

browser::node_class_map_t openvrml::browser::node_class_map [private]

A map of URIs to node implementations.

script_node_class openvrml::browser::script_node_class_ [private]

node_class for Script nodes in the browser.

scene * openvrml::browser::scene_ [private]

Pointer to the root scene.

node_ptr openvrml::browser::default_viewpoint_ [private]

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

viewpoint_node * openvrml::browser::active_viewpoint_ [private]

The currently "active" viewpoint_node.

std::list< viewpoint_node * > openvrml::browser::viewpoint_list [private]

A list of all the Viewpoint nodes in the browser.

browser::bind_stack_t openvrml::browser::navigation_info_stack [private]

The stack of bound NavigationInfo nodes.

std::list< node * > openvrml::browser::navigation_infos [private]

A list of all the NavigationInfo nodes in the browser.

std::list< node * > openvrml::browser::scoped_lights [private]

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

std::list< script_node * > openvrml::browser::scripts [private]

A list of all the Script nodes in the browser.

std::list< node * > openvrml::browser::timers [private]

A list of all the TimeSensor nodes in the browser.

std::list< node * > openvrml::browser::audio_clips [private]

A list of all the AudioClip nodes in the browser.

std::list< node * > openvrml::browser::movies [private]

A list of all the MovieTexture nodes in the browser.

bool openvrml::browser::modified_ [private]

Flag to indicate whether the browser has been modified.

bool openvrml::browser::new_view [private]

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

double openvrml::browser::delta_time [private]

Time elapsed since the last update.

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

The current viewer.

browser::scene_cb_list_t openvrml::browser::scene_callbacks [protected]

List of functions to call when the world is changed.

double openvrml::browser::frame_rate_ [protected]

Frame rate.

browser::event openvrml::browser::event_mem [protected]

The event queue.

Todo:: The event queue ought to be sorted by timestamp.

size_t openvrml::browser::first_event [protected]

Index of the first pending event.

size_t openvrml::browser::last_event [protected]

Index of the last pending event.

std::ostream & openvrml::browser::out

Output stream, generally for console output.

std::ostream & openvrml::browser::err

Error output stream.

bool openvrml::browser::flags_need_updating

Set by node::setBVolumeDirty 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 propegated to that node's ancestors.

openvrml::browser Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Private Types

Private Member Functions

Private Attributes

Friends

Classes

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation