openvrml::browser Class Reference

List of all members.


Detailed Description

Encapsulates a VRML browser.

Public Types

enum  cb_reason {
  destroy_world_id,
  replace_world_id
}
 Valid reasons for browser callback. More...
typedef void(* scene_cb )(cb_reason reason)
 A pointer to a browser callback function.

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_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.
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 () 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_ptrcreate_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_nodebindable_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

enum  { max_events = 400 }
typedef std::list< scene_cbscene_cb_list_t
 List of functions to call when the world is changed.

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_ptrbind_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.
scenescene_
 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_nodeactive_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::viewerviewer_
 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

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.

Maps URIs to node_classes.

A list of bound nodes.

List of functions to call when the world is changed.


Member Enumeration Documentation

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

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:
in 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:
cb 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:
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_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:
n 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:
n 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:
n 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).

A map of URIs to node implementations.

node_class for Script nodes in the browser.

Pointer to the root scene.

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

The currently "active" viewpoint_node.

A list of all the Viewpoint nodes in the browser.

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.

Flag to indicate whether the browser has been modified.

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

Time elapsed since the last update.

The current viewer.

List of functions to call when the world is changed.

double openvrml::browser::frame_rate_ [protected]

Frame rate.

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.

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.