Home | Download | Screen shots | Discussion | Documentation
--- | --- | --- | --- | ---

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

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.

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

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.