C++ API Reference
Associations Class Reference

Class handling associations between internal and external data. More...

#include <adskDataAssociations.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...
 
Associationsoperator= (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 ChannelfindChannel (const std::string &) const
 Get the Channel with the given name, return NULL if it doesn't exist. More...
 
ChannelfindChannel (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 Channeloperator[] (unsigned int channelIndex) const
 Get a pointer to one of the associated channels by index. More...
 

Static Public Member Functions

static Associationscreate ()
 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...
 

Detailed 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.

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]rhsAssociations 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]rhsAssociations data to be copied

Member Function Documentation

Associations & operator= ( const Associations rhs)

Assignment operator, shares implementation with the rhs.

Parameters
[in]rhsAssociations 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]channelNameName 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]newChannelNew 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]channelNameName 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]channelNameName 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]channelNameName 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]oldChannelNameName of the Channel to be renamed
[in]newChannelNameNew 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

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]channelIndexIndex 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]channelIndexIndex 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]mePointer to object to debug, NULL means class static
[out]requestPrint 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]mePointer to object to footprint, NULL means class static
[out]requestFootprint 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: