openvrml::node Class Reference

A node in the scene graph. More...

#include <openvrml/node.h>

Inheritance diagram for openvrml::node:

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_typetype () 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::scopescope () const throw ()
 Get the scope to which the node belongs.
openvrml::scenescene () 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_valuefield (const std::string &id) const throw ( unsupported_interface , std::bad_alloc )
 Generalized field accessor.
openvrml::event_listenerevent_listener (const std::string &id) throw ( unsupported_interface )
 Get an event listener.
openvrml::event_emitterevent_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_valuedo_field (const std::string &id) const =0 throw ( unsupported_interface )
 Called by node::field to get a field.
virtual openvrml::event_listenerdo_event_listener (const std::string &id)=0 throw ( unsupported_interface )
 Get an event listener.
virtual openvrml::event_emitterdo_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_nodenode_cast (node *n) throw ()
 Cast to a script_node.

Related Functions

(Note that these are not member functions.)

To * node_cast (node *n)
 Downcast a node to one of the abstract node types.
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]typethe node_type associated with the instance.
[in]scopethe 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_idthe name for the node.
Exceptions
std::bad_allocif 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]outoutput stream.
[in]indentnumber 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]scenethe scene to which the node will belong.
[in]timestampthe current time.
Exceptions
std::bad_allocif 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]idthe name of the field.
Returns
the field value.
Exceptions
unsupported_interfaceif the node has no field named id.
std::bad_allocif memory allocation fails.
Template Parameters
FieldValuea Field Value.
Parameters
[in]idthe name of the field.
Returns
the field value.
Exceptions
unsupported_interfaceif the node has no field named id.
std::bad_castif 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]idan eventIn identifier.
Exceptions
unsupported_interfaceif the node has no eventIn id.
Template Parameters
FieldValuea Field Value.
Parameters
[in]idan eventIn identifier.
Exceptions
unsupported_interfaceif the node has no eventIn id.
std::bad_castif 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]idan eventOut identifier.
Exceptions
unsupported_interfaceif the node has no eventOut id.
Template Parameters
FieldValuea Field Value.
Parameters
[in]idan eventOut identifier.
Exceptions
unsupported_interfaceif the node has no eventOut id.
std::bad_castif 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]timestampthe 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_errorif #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_errorif #modified_mutex_ cannot be locked.
void openvrml::node::emit_event ( openvrml::event_emitter emitter,
double  timestamp 
) throw ( std::bad_alloc )
staticprotected

Emit an event.

Parameters
[in,out]emitteran event_emitter.
[in]timestampthe current time.
Exceptions
std::bad_allocif 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 ()
privatevirtual

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 )
privatevirtual

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]timestampthe current time.
Exceptions
std::bad_allocif memory allocation fails.
const openvrml::field_value & openvrml::node::do_field ( const std::string &  id) const throw ( unsupported_interface )
privatepure virtual

Called by node::field to get a field.

Parameters
[in]idfield identifier.
Returns
the field value.
Exceptions
unsupported_interfaceif the node has no field id.
openvrml::event_listener & openvrml::node::do_event_listener ( const std::string &  id) throw ( unsupported_interface )
privatepure virtual

Get an event listener.

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

Parameters
[in]ideventIn identifier.
Returns
the event listener.
Exceptions
unsupported_interfaceif the node has no eventIn id.
openvrml::event_emitter & openvrml::node::do_event_emitter ( const std::string &  id) throw ( unsupported_interface )
privatepure virtual

Get an event emitter.

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

Parameters
[in]ideventOut identifier.
Returns
the event emitter.
Exceptions
unsupported_interfaceif the node has no eventOut id.
void openvrml::node::do_shutdown ( double  timestamp) throw ()
privatevirtual

Called by node::shutdown.

node subclass-specific shut down.

Parameters
[in]timestampthe 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]timestampthe current time.
bool openvrml::node::do_modified ( ) const throw ( boost::thread_resource_error )
privatevirtual

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_errorif 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

Cast to a script_node.

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.

To * node_cast ( node n)
related

Downcast a node to one of the abstract node types.

Template Parameters
Toan abstract node type.
Parameters
[in]na 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]na 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.