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

- Main Page
- Namespaces
- Classes
- Files
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Private Member Functions | Friends | Related Functions
openvrml::node Class Reference

A `node` in the scene graph. More...

`#include <openvrml/node.h>`

Inheritance diagram for openvrml::node:
[legend]

List of all members.

## Public Member Functions

virtual | ~node ()=0 throw ()
| Destructor.
void | add_ref () const throw ()
| Increment the reference count.
void | remove_ref () const throw ()
| Decrement the reference count.
void | release () const throw ()
| Decrement the reference count; destroy the instance if the count drops to zero.
size_t | use_count () const throw ()
| The number of owning references to the instance.
const node_type & | type () const throw ()
| The type information object for the `node`.
const std::string & | id () const throw ()
| Retrieve the name of this `node`.
void | id (const std::string &node_id) throw ( std::bad_alloc )
| Set the name of the `node`.
const openvrml::scope & | scope () const throw ()
| Get the `scope` to which the `node` belongs.
openvrml::scene * | scene () const throw ()
| Get the `scene` with which the `node` is associated.
const std::vector < boost::intrusive_ptr< node > > & | impl_nodes () const throw ()
| Get the implementation nodes of a `PROTO` instance.
std::ostream & | print (std::ostream &out, size_t indent) const
| Pretty print.
void | initialize (openvrml::scene &scene, double timestamp) throw ( std::bad_alloc )
| Initialize the node.
std::auto_ptr< field_value > | field (const std::string &id) const throw ( unsupported_interface , std::bad_alloc )
| Generalized field accessor.
openvrml::event_listener & | event_listener (const std::string &id) throw ( unsupported_interface )
| Get an event listener.
openvrml::event_emitter & | event_emitter (const std::string &id) throw ( unsupported_interface )
| Get an event emitter.
void | shutdown (double timestamp) throw ()
| Shut down the node.
bool | modified () const throw ( boost::thread_resource_error )
| Determine whether the `node` has been modified.
void | modified (bool value) throw ( boost::thread_resource_error )
| Set the modified flag.

## Static Public Attributes

static const boost::intrusive_ptr< node > | self_tag
| Special value used when initializing a `script_node`.

## Protected Member Functions

| node (const node_type &type, const boost::shared_ptr< openvrml::scope > &scope) throw ()
| Construct.
boost::shared_mutex & | scene_mutex ()
| The `scene` mutex.

## Static Protected Member Functions

static void | emit_event (openvrml::event_emitter &emitter, double timestamp) throw ( std::bad_alloc )
| Emit an event.

## Private Member Functions

virtual const std::vector < boost::intrusive_ptr< node > > & | do_impl_nodes () const throw ()
| Get the implementation nodes of a `PROTO` instance.
virtual void | do_initialize (double timestamp) throw ( std::bad_alloc )
| `node` subclass-specific initialization.
virtual const field_value & | do_field (const std::string &id) const =0 throw ( unsupported_interface )
| Called by `node::field` to get a `field`.
virtual openvrml::event_listener & | do_event_listener (const std::string &id)=0 throw ( unsupported_interface )
| Get an event listener.
virtual openvrml::event_emitter & | do_event_emitter (const std::string &id)=0 throw ( unsupported_interface )
| Get an event emitter.
virtual void | do_shutdown (double timestamp) throw ()
| Called by node::shutdown.
virtual bool | do_modified () const throw ( boost::thread_resource_error )
| Determine whether the `node` has been modified.

## Friends

std::ostream & | operator<< (std::ostream &out, const node &n)
| Stream output.
script_node * | node_cast (node *n) throw ()
| Downcast a `node` to one of the abstract `node` types.

## Related Functions

(Note that these are not member functions.)
void | intrusive_ptr_add_ref (const node *n)
| Increment the reference count.
void | intrusive_ptr_release (const node *n)
| Decrement the reference count.
bool | is_proto_instance (const node &n)
| Check whether a `node` is a `PROTO` instance.

## Detailed Description

A `node` in the scene graph.

## Constructor & Destructor Documentation

openvrml::node::~node | ( |  | ) | throw ()`[pure virtual]`

Destructor.

Remove `node` name (if any) from the `scope`.

openvrml::node::node | ( | const node_type & | type,
|  | const boost::shared_ptr< openvrml::scope > & | scope
| ) |  | throw ()`[protected]`

Construct.

Parameters:

  [in] | type | the `node_type` associated with the instance.
  [in] | scope | the `scope` associated with the instance.

## Member Function Documentation

void openvrml::node::add_ref | ( |  | ) | const throw ()

Increment the reference count.

Add an owning reference.

void openvrml::node::remove_ref | ( |  | ) | const throw ()`[inline]`

Decrement the reference count.

Remove an owning reference; but do not destroy the instance if the reference count drops to zero. This function should be used with caution. It is really only appropriate when the caller is aware that the reference count may drop to zero but destroying the instance in that case would be inappropriate. In most cases it is appropriate to use `release`.

void openvrml::node::release | ( |  | ) | const throw ()

Decrement the reference count; destroy the instance if the count drops to zero.

size_t openvrml::node::use_count | ( |  | ) | const throw ()

The number of owning references to the instance.

Returns:
  the number of owning references to the instance.

const openvrml::node_type & openvrml::node::type | ( |  | ) | const throw ()

The type information object for the `node`.

Returns:
  the type information object for the `node`.

Reimplemented in openvrml::navigation_info_node.

const std::string & openvrml::node::id | ( |  | ) | const throw ()

Retrieve the name of this `node`.

Returns:
  the `node` name.

void openvrml::node::id | ( | const std::string & | node_id | ) | throw ( std::bad_alloc )

Set the name of the `node`.

Parameters:

  [in] | node_id | the name for the `node`.

Exceptions:

  std::bad_alloc | if memory allocation fails.

const scope & openvrml::node::scope | ( |  | ) | const throw ()`[inline]`

Get the `scope` to which the `node` belongs.

Returns:
  the `scope` to which the `node` belongs.

See also:
  http://boost.org/libs/smart_ptr/shared_ptr.htm

openvrml::scene * openvrml::node::scene | ( |  | ) | const throw ()

Get the `scene` with which the `node` is associated.

Returns:
  the `scene` with which the `node` is associated.

const std::vector< boost::intrusive_ptr< openvrml::node > > & openvrml::node::impl_nodes | ( |  | ) | const throw ()

Get the implementation nodes of a `PROTO` instance.

If the `node` is not a `PROTO` instance, the returned `vector` is empty.

This function delegates to `do_impl_nodes`.

Returns:
  the implementation nodes.

std::ostream & openvrml::node::print | ( | std::ostream & | out,
|  | size_t | indent
| ) |  | const

Pretty print.

Parameters:

  [in,out] | out | output stream.
  [in] | indent | number of spaces per indentation level.

Returns:
  `out`.

void openvrml::node::initialize | ( | openvrml::scene & | scene,
|  | double | timestamp
| ) |  | throw ( std::bad_alloc )

Initialize the node.

This method works recursively, initializing any child nodes to the same `scene` and `timestamp`. If the node has already been initialized, this method has no effect.

Parameters:

  [in,out] | scene | the `scene` to which the `node` will belong.
  [in] | timestamp | the current time.

Exceptions:

  std::bad_alloc | if memory allocation fails.

Postcondition:
  #scene_ points to `scene`.

const FieldValue openvrml::node::field | ( | const std::string & | id | ) | const throw ( unsupported_interface , std::bad_alloc )

Generalized field accessor.

Parameters:

  [in] | id | the name of the field.

Returns:
  the field value.

Exceptions:

  unsupported_interface | if the node has no field named `id`.
  std::bad_alloc | if memory allocation fails.

Template Parameters:

  FieldValue | a Field Value.

Parameters:

  [in] | id | the name of the `field`.

Returns:
  the field value.

Exceptions:

  unsupported_interface | if the node has no field named `id`.
  std::bad_cast | if the node's `id` field is not a `FieldValue`.

field_value_listener< FieldValue > & openvrml::node::event_listener | ( | const std::string & | id | ) | throw ( unsupported_interface )

Get an event listener.

Parameters:

  [in] | id | an `eventIn` identifier.

Exceptions:

  unsupported_interface | if the `node` has no `eventIn` `id`.

Template Parameters:

  FieldValue | a Field Value.

Parameters:

  [in] | id | an `eventIn` identifier.

Exceptions:

  unsupported_interface | if the `node` has no `eventIn` `id`.
  std::bad_cast | if the `node`'s `id` `eventIn` is not a `FieldValue`.

field_value_emitter< FieldValue > & openvrml::node::event_emitter | ( | const std::string & | id | ) | throw ( unsupported_interface )

Get an event emitter.

Parameters:

  [in] | id | an `eventOut` identifier.

Exceptions:

  unsupported_interface | if the node has no eventOut `id`.

Template Parameters:

  FieldValue | a Field Value.

Parameters:

  [in] | id | an `eventOut` identifier.

Exceptions:

  unsupported_interface | if the `node` has no `eventOut` `id`.
  std::bad_cast | if the `node`'s `id` `eventOut` is not a `FieldValue`.

void openvrml::node::shutdown | ( | double | timestamp | ) | throw ()

Shut down the node.

This method works recursively, shutting down any child `nodes`. If the `node` has already been shut down, this method has no effect.

Parameters:

  [in] | timestamp | the current time.

Postcondition:
  scene is 0.

bool openvrml::node::modified | ( |  | ) | const throw ( boost::thread_resource_error )

Determine whether the `node` has been modified.

The default implementation returns whether this `node` has been modified. Subclasses that can have child `nodes` should override this method and return `true` if any of their children have been modified.

Returns:
  `true` if the `node` has been modified; `false` otherwise.

Exceptions:

  boost::thread_resource_error | if `#modified_mutex_` cannot be locked.

void openvrml::node::modified | ( | bool | value | ) | throw ( boost::thread_resource_error )

Set the modified flag.

Indicates the node needs to be revisited for rendering.

Parameters:

  [in] | value |

Exceptions:

  boost::thread_resource_error | if `#modified_mutex_` cannot be locked.

void openvrml::node::emit_event | ( | openvrml::event_emitter & | emitter,
|  | double | timestamp
| ) |  | throw ( std::bad_alloc )`[static, protected]`

Emit an event.

Parameters:

  [in,out] | emitter | an `event_emitter`.
  [in] | timestamp | the current time.

Exceptions:

  std::bad_alloc | if memory allocation fails.

boost::shared_mutex & openvrml::node::scene_mutex | ( |  | ) | `[protected]`

The `scene` mutex.

Returns:
  the `scene` mutex.

const std::vector< boost::intrusive_ptr< openvrml::node > > & openvrml::node::do_impl_nodes | ( |  | ) | const throw ()`[private, virtual]`

Get the implementation nodes of a `PROTO` instance.

This default implementation returns an empty `vector`.

Returns:
  an empty `vector`.

void openvrml::node::do_initialize | ( | double | timestamp | ) | throw ( std::bad_alloc )`[private, virtual]`

`node` subclass-specific initialization.

This method is called by `initialize`. Subclasses of node should override this method for any subclass-specific initialization.

The default implementation of this method does nothing.

Parameters:

  [in] | timestamp | the current time.

Exceptions:

  std::bad_alloc | if memory allocation fails.

Reimplemented in openvrml::script_node.

const openvrml::field_value & openvrml::node::do_field | ( | const std::string & | id | ) | const throw ( unsupported_interface )`[private, pure virtual]`

Called by `node::field` to get a `field`.

Parameters:

  [in] | id | field identifier.

Returns:
  the field value.

Exceptions:

  unsupported_interface | if the `node` has no `field` `id`.

Implemented in openvrml::node_impl_util::abstract_node< Derived >, and openvrml::script_node.

openvrml::event_listener & openvrml::node::do_event_listener | ( | const std::string & | id | ) | throw ( unsupported_interface )`[private, pure virtual]`

Get an event listener.

This method is called by `event_listener`. Subclasses must implement this method.

Parameters:

  [in] | id | `eventIn` identifier.

Returns:
  the event listener.

Exceptions:

  unsupported_interface | if the node has no `eventIn` `id`.

Implemented in openvrml::node_impl_util::abstract_node< Derived >, and openvrml::script_node.

openvrml::event_emitter & openvrml::node::do_event_emitter | ( | const std::string & | id | ) | throw ( unsupported_interface )`[private, pure virtual]`

Get an event emitter.

This method is called by `event_emitter`. Subclasses must implement this method.

Parameters:

  [in] | id | `eventOut` identifier.

Returns:
  the event emitter.

Exceptions:

  unsupported_interface | if the node has no `eventOut` `id`.

Implemented in openvrml::node_impl_util::abstract_node< Derived >, and openvrml::script_node.

void openvrml::node::do_shutdown | ( | double | timestamp | ) | throw ()`[private, virtual]`

Called by node::shutdown.

`node` subclass-specific shut down.

Parameters:

  [in] | timestamp | the current time.

This method is called by `shutdown`. Subclasses of node should override this method for any subclass-specific shut down. Note that this method cannot throw.

The default implementation of this method does nothing.

Parameters:

  [in] | timestamp | the current time.

Reimplemented in openvrml::script_node.

bool openvrml::node::do_modified | ( |  | ) | const throw ( boost::thread_resource_error )`[private, virtual]`

Determine whether the `node` has been modified.

The default implementation returns `false`. Subclasses that can have child `nodes` should override this method and return `true` if any of their children has been modified.

Returns:
  `false`.

Exceptions:

  boost::thread_resource_error | if a mutex cannot be locked.

## Friends And Related Function Documentation

std::ostream & openvrml::node::operator<< | ( | std::ostream & | out,
|  | const node & | n
| ) |  | `[friend]`

Stream output.

openvrml::viewpoint_node * openvrml::node::node_cast< viewpoint_node * > | ( | node * | n | ) | throw ()`[friend]`

Downcast a `node` to one of the abstract `node` types.

Cast to a `viewpoint_node`.

Cast to a `transform_node`.

Cast to a `texture_transform_node`.

Cast to a `texture_coordinate_node`.

Cast to a `texture_node`.

Cast to a `sound_source_node`.

Cast to a `normal_node`.

Cast to a `navigation_info_node`.

Cast to a `material_node`.

Cast to a `grouping_node`.

Cast to a `geometry_node`.

Cast to a `font_style_node`.

Cast to a `coordinate_node`.

Cast to a `color_rgba_node`.

Cast to a `color_node`.

Cast to a `child_node`.

Cast to a `appearance_node`.

Cast to a `script_node`.

Template Parameters:

  To | an abstract `node` type.

Parameters:

  [in] | n | a `node`.

Returns:
  a pointer to the downcast `node`, or 0 if the cast fails.

void intrusive_ptr_add_ref | ( | const node * | n | ) | `[related]`

Increment the reference count.

This function is used by `boost::intrusive_ptr<node>`.

See also:
  http://boost.org/libs/smart_ptr/intrusive_ptr.html

void intrusive_ptr_release | ( | const node * | n | ) | `[related]`

Decrement the reference count.

This function is used by `boost::intrusive_ptr<node>`.

See also:
  http://boost.org/libs/smart_ptr/intrusive_ptr.html

bool is_proto_instance | ( | const node & | n | ) | `[related]`

Check whether a `node` is a `PROTO` instance.

Parameters:

  [in] | n | a `node`.

Returns:
  `true` if `n` is a `PROTO` instance; `false` otherwise.

## Member Data Documentation

const boost::intrusive_ptr< openvrml::node > openvrml::node::self_tag `[static]`

Special value used when initializing a `script_node`.

One should never attempt to dereference this value. It is useful only for comparison.