openvrml::scene Class Reference

A scene in the VRML world. More...

#include <openvrml/scene.h>

List of all members.


Public Member Functions

 scene (openvrml::browser &browser, scene *parent=0) throw ()
 Construct.
virtual ~scene () throw ()
 Destroy.
openvrml::browserbrowser () const throw ()
 Get the associated browser.
sceneparent () const throw ()
 Get the parent scene.
void load (resource_istream &in)
 Load the scene from a stream.
void initialize (double timestamp) throw ( std::bad_alloc )
 Initialize the scene.
const std::string meta (const std::string &key) const throw ( std::invalid_argument , std::bad_alloc )
 Get metadata.
void meta (const std::string &key, const std::string &value) throw ( std::bad_alloc )
 Set metadata.
const std::vector< std::string > meta_keys () const throw ( std::bad_alloc )
 Get the metadata keys.
const std::vector
< boost::intrusive_ptr< node > > 
nodes () const throw ( std::bad_alloc )
 Root nodes for the scene.
void nodes (const std::vector< boost::intrusive_ptr< node > > &n) throw ( std::invalid_argument , std::bad_alloc )
 Set the root nodes for the scene.
const scoperoot_scope () const throw ()
 Get the root scope.
const std::string url () const throw ( std::bad_alloc )
 Get the absolute URI for the scene.
void render (openvrml::viewer &viewer, rendering_context context)
 Render the scene.
void load_url (const std::vector< std::string > &url, const std::vector< std::string > &parameter) throw ( std::bad_alloc )
 Load a resource into browser.
std::auto_ptr< resource_istreamget_resource (const std::vector< std::string > &url) const throw ( no_alternative_url , std::bad_alloc )
 Get a resource using a list of alternative URIs.
void read_stream (std::auto_ptr< resource_istream > in, std::auto_ptr< stream_listener > listener)
 Read a stream in a new thread.
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.
void shutdown (double timestamp) throw ()
 Shut down the nodes in the scene.

Private Member Functions

virtual void scene_loaded ()
 Function called once the scene has been loaded.

Private Attributes

openvrml::browser *const browser_
 A reference to the browser associated with the scene.
scene *const parent_
 A pointer to the parent scene.
boost::shared_mutex nodes_mutex_
 Mutex protecting nodes_.
std::vector
< boost::intrusive_ptr< node > > 
nodes_
 The nodes for the scene.
boost::shared_mutex url_mutex_
 Mutex protecting url_.
std::string url_
 The URI for the scene.
boost::shared_mutex meta_mutex_
 Mutex protecting meta_.
std::map< std::string,
std::string > 
meta_
 Scene metadata map.
boost::thread_group stream_reader_threads_
 Stream reader thread group.

Detailed Description

A scene in the VRML world.

Constructor & Destructor Documentation

openvrml::scene::scene ( openvrml::browser browser,
scene parent = 0 
) throw () [explicit]

Construct.

Parameters:
[in] browser the browser associated with the scene.
[in] parent the parent scene.

openvrml::scene::~scene (  )  throw () [virtual]

Destroy.


Member Function Documentation

openvrml::browser & openvrml::scene::browser (  )  const throw ()

Get the associated browser.

Returns:
the associated browser.

openvrml::scene * openvrml::scene::parent (  )  const throw ()

Get the parent scene.

Returns:
the parent scene, or 0 if this is the root scene.

void openvrml::scene::load ( resource_istream in  ) 

Load the scene 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::scene::initialize ( double  timestamp  )  throw ( std::bad_alloc )

Initialize the scene.

Parameters:
[in] timestamp the current time.
Exceptions:
std::bad_alloc if memory allocation fails.

const std::string openvrml::scene::meta ( const std::string &  key  )  const throw ( std::invalid_argument , std::bad_alloc )

Get metadata.

Parameters:
[in] key metadata key.
Returns:
the metadata value associated with key.
Exceptions:
std::invalid_argument if there is no value associated with key.
std::bad_alloc if memory allocation fails.

void openvrml::scene::meta ( const std::string &  key,
const std::string &  value 
) throw ( std::bad_alloc )

Set metadata.

Parameters:
[in] key metadata key.
[in] value metadata value.
Exceptions:
std::bad_alloc if memory allocation fails.

const std::vector< std::string > openvrml::scene::meta_keys (  )  const throw ( std::bad_alloc )

Get the metadata keys.

Returns:
the metadata keys.

const std::vector< boost::intrusive_ptr< openvrml::node > > openvrml::scene::nodes (  )  const throw ( std::bad_alloc )

Root nodes for the scene.

Returns:
the root nodes for the scene.
Exceptions:
std::bad_alloc if memory allocation fails.

void openvrml::scene::nodes ( const std::vector< boost::intrusive_ptr< node > > &  n  )  throw ( std::invalid_argument , std::bad_alloc )

Set the root nodes for the scene.

This function calls shutdown to shut down the scene's existing nodes.

Parameters:
[in] n the new root nodes for the scene.
Exceptions:
std::invalid_argument if any of the nodes in n has already been initialized.
std::bad_alloc if memory allocation fails.

const openvrml::scope * openvrml::scene::root_scope (  )  const throw ()

Get the root scope.

Returns:
the root scope.

const std::string openvrml::scene::url (  )  const throw ( std::bad_alloc )

Get the absolute URI for the scene.

Returns:
the absolute URI for the scene.
Exceptions:
std::bad_alloc if memory allocation fails.

void openvrml::scene::render ( openvrml::viewer viewer,
rendering_context  context 
)

Render the scene.

Parameters:
[in,out] viewer a viewer to render to.
[in] context a rendering_context.

void openvrml::scene::load_url ( const std::vector< std::string > &  url,
const std::vector< std::string > &  parameter 
) throw ( std::bad_alloc )

Load a resource into browser.

This method simply resolves any relative references in uri and calls browser::load_url.

Note:
There are a couple of edge cases here where we are probably doing the wrong thing:
  • If there is a URI in the list of the form “#NodeId” and it is not the first URI in the list, this URI will be loaded as if it were a new world rather than as a Viewpoint that should simply be bound.
  • If the first URI in the list is of the form “#NodeId” and no Viewpoint named “NodeId” exists in the scene, this method will not try any subsequent URIs in the list.
Parameters:
[in] url an array of URIs. Per VRML97 convention, the first resource in the sequence that can be reached will be loaded into the browser.
[in] parameter an array of parameters to be associated with the URIs in uri.
Exceptions:
std::bad_alloc if memory allocation fails.
Todo:
This method currently fails silently if any of the URIs in url is invalid. Should this throw invalid_url?

std::auto_ptr< openvrml::resource_istream > openvrml::scene::get_resource ( const std::vector< std::string > &  url  )  const throw ( no_alternative_url , std::bad_alloc )

Get a resource using a list of alternative URIs.

Relative URIs in url are resolved against the absolute URI of the scene.

Parameters:
[in] url a list of alternative URIs.
Returns:
the resource.
Exceptions:
no_alternative_url if none of the elements of url can be resolved.
std::bad_alloc if memory allocation fails.

void openvrml::scene::read_stream ( std::auto_ptr< resource_istream in,
std::auto_ptr< stream_listener listener 
)

Read a stream in a new thread.

read_stream takes ownership of its arguments; the resources are released when reading the stream completes and the thread terminates.

Parameters:
[in] in an input stream.
[in] listener a stream listener.

void openvrml::scene::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.

void openvrml::scene::shutdown ( double  timestamp  )  throw ()

Shut down the nodes in the scene.

This function must be called before the scene is destroyed.

Parameters:
[in] timestamp the current time.

void openvrml::scene::scene_loaded (  )  [private, virtual]

Function called once the scene has been loaded.

load calls this function once the scene has finished loading. The default implementation does nothing.


Member Data Documentation

A reference to the browser associated with the scene.

For internal use only.

A pointer to the parent scene.

For internal use only.

If the scene is the root scene, parent will be 0.

boost::shared_mutex openvrml::scene::nodes_mutex_ [mutable, private]

Mutex protecting nodes_.

For internal use only.

The nodes for the scene.

For internal use only.

boost::shared_mutex openvrml::scene::url_mutex_ [mutable, private]

Mutex protecting url_.

For internal use only.

const std::string openvrml::scene::url_ [private]

The URI for the scene.

For internal use only.

This may be a relative or an absolute reference.

boost::shared_mutex openvrml::scene::meta_mutex_ [mutable, private]

Mutex protecting meta_.

For internal use only.

std::map< std::string, std::string > openvrml::scene::meta_ [private]

Scene metadata map.

For internal use only.

boost::thread_group openvrml::scene::stream_reader_threads_ [private]

Stream reader thread group.

For internal use only.