openvrml::scene Class Reference

A scene in the VRML world. More...

#include <openvrml/browser.h>


Public Member Functions
	scene (openvrml::browser &browser, scene *parent=0) throw ()
	Construct.
virtual	~scene () throw ()
	Destroy.
openvrml::browser &	browser () const throw ()
	Get the associated `browser`.
scene *	parent () 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 scope *	root_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_istream >	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.
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`.
read_write_mutex	nodes_mutex_
	Mutex protecting nodes_.
std::vector < boost::intrusive_ptr< node > >	nodes_
	The nodes for the scene.
read_write_mutex	url_mutex_
	Mutex protecting url_.
std::string	url_
	The URI for the scene.
read_write_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

openvrml::browser *const openvrml::scene::browser_ [private]

A reference to the browser associated with the scene.

For internal use only.

openvrml::scene *const openvrml::scene::parent_ [private]

A pointer to the parent scene.

For internal use only.

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

openvrml::read_write_mutex openvrml::scene::nodes_mutex_ [mutable, private]

Mutex protecting nodes_.

For internal use only.

openvrml::mfnode openvrml::scene::nodes_ [private]

The nodes for the scene.

For internal use only.

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

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

openvrml::scene Class Reference

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation