#include <adskDataAssociations.h>

Class Description

Class handling associations between internal and external data.

You would use this data structure when creating something like per-component data; e.g. a piece of data you wish to attach to every vertex on a surface, every point in a cloud, every particle in a fluid simulation, etc.

It provides a generic interface to handle lists of data streams that can be associated with your own data.

Association types should be unique within the context of where this data is being stored. e.g. "mesh/vertex", "mesh/edge", and "mesh/face". There is no requirement of the naming convention. Associations are looked up by pointer first before string compares so using a const reference from the calling code is more efficient.

The classes are designed to each be simple to use at the expense of a little complexity in the hierarchy. Here's how the different levels break down using the namespace adsk::Data

Associations | | Associates type (e.g. per-vertex data) with channel | Channel | | Amalgamates all data streams (e.g. per-vertex data maintained | for an external simulation) into a single entity | Stream | | Keeps an efficient list of indexed data | (e.g. one set of simulation data per vertex) | Data The actual data with introspection capabilities so that you can find out what it is. At this level it's a single chunk of data, e.g. 3 floats for color, an int and a string as a version identifier, a collection of vectors and scalars for current simulation state, etc.

For example on a mesh with 8 vertices if a simulation engine wants to store the velocity and acceleration of every vertex the data would look like this:

adsk::Data::Associations { channelCount = 1 channel(0) = adsk::Data::Channel { name = "mesh/vertex" streamCount = 1 stream(0) = adsk::Data::Stream { indexCount = 8 streamData = adsk::Data::Handle[8] { "simulationData" : compoundType { "velocity" : compoundType { "velocityX" : float "velocityY" : float "velocityZ" : float } "acceleration" : compoundType { "accelerationX" : float "accelerationY" : float "accelerationZ" : float } } } } } }

Examples:: MetadataSample/createMetadataCmd.cpp, MetadataSample/exportMetadataCmd.cpp, MetadataSample/importMetadataCmd.cpp, MetadataSample/tweakMetadataNode.cpp, MetadataXML/associationsSerializerXML.cpp, MetadataXML/associationsSerializerXML.h, sceneAssembly/adskSceneMetadataCmd.cpp, and sceneAssembly/adskSceneMetadataCmd.h.

Public Member Functions
	~Associations ()
	Default destructor, release the implementation object.

	Associations ()
	Default constructor, initializes the implementation object.

	Associations (const Associations *)
	Copy constructor with pointer, shares a ref to internal data with the copy Used as a convenience function for passing in a metadata pointer without caring if it's null or not. More...

	Associations (const Associations &)
	Copy constructor, shares a ref to internal data with the copy. More...

Associations &	operator= (const Associations &)
	Assignment operator, shares implementation with the rhs. More...

Channel	channel (const std::string &)
	Get the data channel with the given name, create if needed. More...

void	setChannel (Channel)
	Set the data channel into the Association. More...

const Channel *	findChannel (const std::string &) const
	Get the Channel with the given name, return NULL if it doesn't exist. More...

Channel *	findChannel (const std::string &)
	Get the Channel with the given name, return NULL if it doesn't exist. More...

bool	removeChannel (const std::string &)
	Remove the Channel with the given name from this metadata. More...

bool	renameChannel (const std::string &, const std::string &)
	Rename a Channel. More...

bool	makeUnique ()
	Make the Association's data unique to this object. More...

Associations::iterator	begin () const
	Get an iterator pointed to the beginning of the Channel list. More...

Associations::iterator	end () const
	Get an iterator off the end of the Channel list. More...

Associations::const_iterator	cbegin () const
	Get a read-only iterator pointed to the beginning of the Channel list. More...

Associations::const_iterator	cend () const
	Get a read-only iterator off the end of the Channel list. More...

unsigned int	size () const
	Get the number of currently associated Channels. More...

bool	empty () const
	Check to see if the Channel list is empty. More...

unsigned int	channelCount () const
	Get the count of currently associated channels. More...

Channel	channelAt (unsigned int channelIndex) const
	Get one of the associated channels by index. More...

const Channel *	operator[] (unsigned int channelIndex) const
	Get a pointer to one of the associated channels by index. More...

Static Public Member Functions
static Associations *	create ()
	Associations creator. More...

static bool	Debug (const Associations *me, Debug::Print &request)
	Answer a Print request for an Associations object. More...

static bool	Debug (const Associations *me, Debug::Footprint &request)
	Answer a footprint request for an Associations object. More...

Constructor & Destructor Documentation

Associations ( const Associations * rhs )

Copy constructor with pointer, shares a ref to internal data with the copy Used as a convenience function for passing in a metadata pointer without caring if it's null or not.

Parameters

[in] rhs Associations data to be copied, NULL means just use the default construction.

Associations ( const Associations & rhs )

Copy constructor, shares a ref to internal data with the copy.

Parameters

[in] rhs Associations data to be copied

Member Function Documentation

Associations & operator= ( const Associations & rhs )

Assignment operator, shares implementation with the rhs.

Parameters

[in] rhs Associations data to be copied

Channel channel ( const std::string & channelName )

Get the data channel with the given name, create if needed.

If a Channel with the given name doesn't yet exist then a new Channel will be created for it and returned. Modifying the returned channel will modify the data in place. To modify a copy first use the method adsk::Data::Channel::makeUnique() to make it unique.

Parameters

[in] channelName Name of channel to retrieve

Returns: Channel with the given name. If there is no data the channel will have no data streams in it

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

void setChannel ( Channel newChannel )

Set the data channel into the Association.

If a Channel with the same name existed it will be overwritten; retrieve and modify the existing channel if you don't want to lose old data.

Parameters

[in] newChannel New Channel data to set

Examples:: MetadataXML/associationsSerializerXML.cpp.

const Channel * findChannel ( const std::string & channelName ) const

Get the Channel with the given name, return NULL if it doesn't exist.

If no Channel with that name exists NULL will be returned.

Parameters

[in] channelName Name of Channel to retrieve

Returns: Channel with the given name if it exists, NULL if it doesn't.

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

Channel * findChannel ( const std::string & channelName )

Get the Channel with the given name, return NULL if it doesn't exist.

If no Channel with that name exists NULL will be returned.

Parameters

[in] channelName Name of Channel to retrieve

Returns: Channel with the given name if it exists, NULL if it doesn't.

bool removeChannel ( const std::string & channelName )

Remove the Channel with the given name from this metadata.

Parameters

[in] channelName Name of the channel to remove

Returns: true if the channel was successfully removed, false if it failed or didn't exist

bool renameChannel	(	const std::string &	oldChannelName,
		const std::string &	newChannelName
	)

Rename a Channel.

Since sorting order comes from the Channel name this had to be controlled at this level.

Parameters

[in]	oldChannelName	Name of the Channel to be renamed
[in]	newChannelName	New name for the Channel to be renamed

Returns: True if the Channel was found and renamed

bool makeUnique ( )

Make the Association's data unique to this object.

Makes a copy of the data if it's currently being shared, otherwise leaves it as-is. Note that it can still be shared afterwards by some other object, i.e. this is not a persistent state, just an operation to perform before making changes you don't want any other copies of the Associations to share.

Returns: true if the data was duplicated in order to make it unique

Associations * create ( )

static

Associations creator.

Used to force allocation of the Associations data into the main heap so that it controls deletion (which it must since the class is reference-counted).

Returns: Pointer to the newly created Associations

Examples:: MetadataXML/associationsSerializerXML.cpp.

Associations::iterator begin ( ) const

Get an iterator pointed to the beginning of the Channel list.

Returns: An iterator pointing at the first element of the Channel list

Associations::iterator end ( ) const

Get an iterator off the end of the Channel list.

Returns: An iterator positioned off the end of the Channel list

Associations::const_iterator cbegin ( ) const

Get a read-only iterator pointed to the beginning of the Channel list.

Returns: A read-only iterator pointing at the first element of the Channel list

Associations::const_iterator cend ( ) const

Get a read-only iterator off the end of the Channel list.

Returns: A read-only iterator positioned off the end of the Channel list

unsigned int size ( ) const

Get the number of currently associated Channels.

Returns: number of currently associated Channels

bool empty ( ) const

Check to see if the Channel list is empty.

Returns: true if there are no Channels in the list

unsigned int channelCount ( ) const

Get the count of currently associated channels.

Same as the size() method, which has a more standard naming.

Returns: number of currently associated channels

Examples:: MetadataXML/associationsSerializerXML.cpp.

Channel channelAt ( unsigned int channelIndex ) const

Get one of the associated channels by index.

Don't use this method, position isn't guaranteed. Use the iterator.

Parameters

[in] channelIndex Index of the channel to retrieve

Returns: The associated channel at the given index. If there is no data the channel will be empty (have no data streams).

Examples:: MetadataXML/associationsSerializerXML.cpp.

const Channel * operator[] ( unsigned int channelIndex ) const

Get a pointer to one of the associated channels by index.

Obsolete, use the iterator instead. Positioning is not guaranteed.

Parameters

[in] channelIndex Index of the channel to retrieve

Returns: The associated channel at the given index. Returns a null pointer if no Channel exists at the given index.

bool Debug	(	const Associations *	me,
		Debug::Print &	request
	)

static

Answer a Print request for an Associations object.

Use the request object to dump all information on the "me" Associations, or all static Associations information if "me" is NULL.

Parameters

[in]	me	Pointer to object to debug, NULL means class static
[out]	request	Print request object

Returns: True if the request was successfully processed.

bool Debug	(	const Associations *	me,
		Debug::Footprint &	request
	)

static

Answer a footprint request for an Associations object.

Populate the Footprint request with the information on all data stored within this class if "me" is NULL, otherwise the information stored in the Associations object pointed at by "me".

Parameters

[in]	me	Pointer to object to footprint, NULL means class static
[out]	request	Footprint object to populate

Returns: True if the request was successfully processed. The Footprint object will have all information added to it.

The documentation for this class was generated from the following files:

adskDataAssociations.h
adskDataAssociations.cpp

Associations Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation