Registerable Class Reference

the abstract base class for SPARK objects More...

Inheritance diagram for Registerable:

Public Member Functions
	Registerable ()
	Default constructor of Registerable.
	Registerable (const Registerable &registerable)
	Copy constructor of Registerable.
virtual	~Registerable ()
	Destructor of Registerable.
void	setShared (bool shared)
	Makes this Registerable shared or not.
void	setDestroyable (bool destroyable)
	Makes this Registerable destroyable or not.
void	setName (const std::string &name)
	Sets the name of this Registerable.
SPK_ID	getSPKID () const
	Gets the ID of this Registerable.
SPK_ID	getID () const
	Gets the ID of this Registerable.
unsigned int	getNbReferences () const
	Gets the number of references of this Registerable.
bool	isRegistered () const
	Tells whether this Registerable is registered or not.
bool	isShared () const
	Tells whether this Registerable is shared or not.
bool	isDestroyable () const
	Tells whether this Registerable is destroyable or not.
const std::string &	getName () const
	Gets the name of this registerable.
virtual std::string	getClassName () const =0
	Gets the name of the class of the object.
virtual Registerable *	findByName (const std::string &name)
	Finds a registerable with its name recursively from this registerable.
Protected Member Functions
void	registerChild (Registerable *child, bool registerAll)
	Registers a child of this Registerable.
Registerable *	copyChild (Registerable *child, bool createBase)
	Copies a child of this Registerable.
bool	destroyChild (Registerable *child, bool keepChildren)
	Destroys a child of this Registerable.
void	incrementChildReference (Registerable *child)
	Increments the number of references of the child by one.
void	decrementChildReference (Registerable *child)
	Decrements the number of references of the child by one.
virtual void	registerChildren (bool registerAll)
	Registers the children of this Registerable.
virtual void	copyChildren (const Registerable &object, bool createBase)
	Copies the children of object in this Registerable.
virtual void	destroyChildren (bool keepChildren)
	Destroys the children of this Registerable.
Static Protected Member Functions
static void	registerObject (Registerable *obj, bool registerAll=false)
	Registers a Registerable in the factory.

Detailed Description

the abstract base class for SPARK objects

A Registerable defines a SPARK object that can be managed by the SPKFactory.

In SPARK, a particle System is defined as a tree of objects. For instance, a System will contain some Renderer, Emitter and Modifier. Every Emitter and Modifier will contain a Zone...
All those Registerable are linked by association. A Registerable can be shared to several Registerable or belong to a single Registerable and die with it (composition).

The SPKFactory offers a flexible system to define, create and destroy complex association of Registerable.

Basically a Registerable has 3 parameters that will define its behavior :

Registered : a registered Registerable is managed by the SPKFactory to deal with copy and destruction.
Shared : a shared Registerable will not be copied when copying its parent. Only its reference will. This allows for instance to change a parameter for many system with only a call. Note that this is valid only for registered Registerable copied with the SPKFactory.
Destroyable : a destroyable Registerable is a Registerable that is allowed to be destroyed by the SPKFactory when destroying its parent (if it has no more references on it see below). If not destroyable, the destruction of the Registerable is the user's responsability. Note that a non destroyable Registerable can still be destroyed by the SPKFactory by a direct call.

Moreover, every registered Registerable holds a counter of references that indicates how many registered Registerable hold a reference to it. A registered Registerable will only be destroyed by the SPKFactory if its number of references is 0 (except for a direct call to its destruction).

Since:: 1.03.00

Definition at line 86 of file SPK_Registerable.h.

Constructor & Destructor Documentation

Registerable ( )

Default constructor of Registerable.

Registerable ( const Registerable & registerable )

Copy constructor of Registerable.

Parameters:

registerable

: the Registerable to construct the new Registerable from

virtual ~Registerable ( ) [virtual]

Destructor of Registerable.

Member Function Documentation

Registerable* copyChild	(	Registerable *	child,
		bool	createBase
	)			`[protected]`

Copies a child of this Registerable.

This method has to be called in the copyChildren(const Registerable&,bool) implementation of a derived class of Registerable.
It is called to allow correct copy (of the object or of the reference only) of the children Registerable when copying the Registerable.

Parameters:

	child	: the child of this Registerable to copy
	createBase	: true if a base is created, false otherwise

Returns:: the children of the copy of this Registerable

virtual void copyChildren	(	const Registerable &	object,
		bool	createBase
	)			`[protected, virtual]`

Copies the children of object in this Registerable.

This method has to be implemented in derived classes of Registerable which hold pointers or references of Registerable children.
The copyChild(Registerable*,bool) has to be called within it for each child to copy from object.
The createBase parameter of copyChild is simply the createBase parameter of copyChildren.

Parameters:

	object	: the object to copy the children from
	createBase	: true if a base is created, false otherwise

Definition at line 339 of file SPK_Registerable.h.

void decrementChildReference ( Registerable * child ) [protected]

Decrements the number of references of the child by one.

This method has to be called when removing a child in the implementation of a derived class of Registerable.
It allows to keep the number of references of the child correct.

Parameters:

child

: the child of this Registerable to decrement references of

Definition at line 461 of file SPK_Registerable.h.

bool destroyChild	(	Registerable *	child,
		bool	keepChildren
	)			`[protected]`

Destroys a child of this Registerable.

This method has to be called in the destroyChildren(bool) implementation of a derived class of Registerable.
It is called to allows the correct destruction (if not destroyable or references exist) of the children Registerable when destroying the Registerable.

Parameters:

	child	: the child of this Registerable to destroy
	keepChildren	: true to keep the children (used when destroying all registered Registerable)

Returns:: true if the child was destroyed, false if not

virtual void destroyChildren ( bool keepChildren ) [protected, virtual]

Destroys the children of this Registerable.

This method has to be implemented in derived classes of Registerable which hold pointers or references of Registerable children.
The destroyChild(Registerable*,bool) has to be called within it for each child to destroy.
The keepChildren parameter of destroyChild is simply the keepChildren parameter of destroyChildren.

Parameters:

keepChildren

: true to keep the children (used when destroying all registered Registerable)

Reimplemented in Emitter, Group, Modifier, System, NormalEmitter, and ModifierGroup.

Definition at line 350 of file SPK_Registerable.h.

Registerable * findByName ( const std::string & name ) [virtual]

Finds a registerable with its name recursively from this registerable.

If the name is not found, NULL is returned.
If the several objects with the same name exists, only the first one is returned.

Note that the name of the registerable itself is already tested.

Parameters:

name

: the name of the registerable to find

Returns:: : the first registerable with that name within this registerable or NULL if none is found

Since:: 1.05.00

Reimplemented in Emitter, Group, Modifier, System, NormalEmitter, and ModifierGroup.

Definition at line 438 of file SPK_Registerable.h.

virtual std::string getClassName ( ) const [pure virtual]

Gets the name of the class of the object.

This method is implemented in non abstract derived class of Registerable with the macro SPK_IMPLEMENT_REGISTERABLE(ClassName).

Returns:: the name of the class of the object as a std::string

SPK_ID getID ( ) const

Gets the ID of this Registerable.

Returns:: the ID of this Registerable or NO_ID if it is not registered

Deprecated:: 1.05.04 Use getSPKID instead

Definition at line 408 of file SPK_Registerable.h.

const std::string & getName ( ) const

Gets the name of this registerable.

The name is an easy to find registerable in a tree.
See setName(const std::string&) and findByName(const std::string&)

Returns:: the name of this registerable

Since:: 1.05.00

Definition at line 433 of file SPK_Registerable.h.

unsigned int getNbReferences ( ) const

Gets the number of references of this Registerable.

The number of references defines the number of times a registered Registerable is references within all the registered Registerable.

0 is always returned for an unregistered Registerable.

Returns:: the number of references of this Registerable

Definition at line 413 of file SPK_Registerable.h.

SPK_ID getSPKID ( ) const

Gets the ID of this Registerable.

If this Registerable is unregistered, NO_ID is returned.
Else an SPK_ID is returned. This ID uniquely identifies the Registerable.

Returns:: the ID of this Registerable or NO_ID if it is not registered

Since:: 1.05.04

Definition at line 403 of file SPK_Registerable.h.

void incrementChildReference ( Registerable * child ) [protected]

Increments the number of references of the child by one.

This method has to be called when adding a child in the implementation of a derived class of Registerable.
It allows to keep the number of references of the child correct.

Parameters:

child

: the child of this Registerable to increment references of

Definition at line 455 of file SPK_Registerable.h.

bool isDestroyable ( ) const

Tells whether this Registerable is destroyable or not.

Returns:: true if this Registerable is destroyable, false if not

Definition at line 428 of file SPK_Registerable.h.

bool isRegistered ( ) const

Tells whether this Registerable is registered or not.

Returns:: true if this Registerable is registered, false if not

Definition at line 418 of file SPK_Registerable.h.

bool isShared ( ) const

Tells whether this Registerable is shared or not.

Returns:: true if this Registerable is shared, false if not

Definition at line 423 of file SPK_Registerable.h.

void registerChild	(	Registerable *	child,
		bool	registerAll
	)			`[protected]`

Registers a child of this Registerable.

This method has to be called in the registerChildren(bool) implementation of a derived class of Registerable.
It is called to allow correct registering and correct reference counting of the children Registerable when registering the Registerable.

Parameters:

	child	: the child of this Registerable to register
	registerAll	: true to register an unregistered child, false to only increment ref counts of an already registered child

Since:: 1.04.00

virtual void registerChildren ( bool registerAll ) [protected, virtual]

Registers the children of this Registerable.

This method has to be implemented in derived classes of Registerable which hold pointers or references of Registerable children.
The registerChild(Registerable*,bool) has to be called within it for each child to copy from object.
The registerAll parameter of registerChild is simply the registerAll parameter of registerChildren.

Parameters:

registerAll

: true to register unregistered children, false to only increment ref counts of already registered children

Since:: 1.04.00

Reimplemented in Emitter, Group, Modifier, System, NormalEmitter, and ModifierGroup.

Definition at line 327 of file SPK_Registerable.h.

static void registerObject	(	Registerable *	obj,
		bool	registerAll = `false`
	)			`[static, protected]`

Registers a Registerable in the factory.

This method allows to register an unregistered given object.
If the registerable is already registered nothing happen.

If registerAll is set to true, all the unregistered children of this Registerable will be registered as well.
Apart from that, all registered children see their reference count increments by one, no matter the value of registerAll.

Use this method with care as it is very important to never register a object that is allocated on the stack, as the factory may delete its registered object with a call to delete.

Parameters:

	obj	: the registerable object to register
	registerAll	: true to register all its unregistered children and chidren of children and so on, false not to

Since:: 1.04.00

void setDestroyable ( bool destroyable )

Makes this Registerable destroyable or not.

A non destroyable Registerable cannot be destroyed internally.

Parameters:

destroyable

: true to make this Registerable destroyable, false to make it undestroyable

Definition at line 393 of file SPK_Registerable.h.

void setName ( const std::string & name )

Sets the name of this Registerable.

The name is an easy to find registerable in a tree.
See getName() and findByName(const std::string&)

A constant NO_NAME exists to give no name to the registerable (an empty string)

Parameters:

name

: the name of this registerable

Since:: 1.05.00

Definition at line 398 of file SPK_Registerable.h.

void setShared ( bool shared )

Makes this Registerable shared or not.

By default, a Registerable is not shared

Parameters:

shared

: true to make this Registerable shared, false to make it unshared

Definition at line 388 of file SPK_Registerable.h.

Registerable Class Reference

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation