#include <adskDataChannel.h>

Class Description

Class handling a named association of a data array with other data.

This class is used in conjunction with adsk::Data::Associations. See the documentation for adsk::Data::Associations for the bigger picture in how the classes work together.

adsk::Data::Channel is responsible for maintaining a list of named data streams, where a "stream" can be thought of as equivalent to a named array of data.

The main reason for this class to exist is to allow attachment of multiple unrelated data streams. For instance a simulator can attach an arbitrary data structure to every vertex of a mesh (that's one stream) and a shader can attach a different color-based data structure to every vertex of a mesh (that's a different stream).

Having separate streams makes it easier to find and handle the stream of data in which a particular user is interested. Having this channel class manage the streams as a unit makes it easier for changes in the indexing to do the proper thing to the data in the streams all in one place (e.g. deleting one of the associated indexes will cause the matching indexed data in each of the streams to be deleted)

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

Public Member Functions
	~Channel ()
	Default destructor, disowns the implementation object.

	Channel ()
	Default constructor, creates an implementation object.

	Channel (const std::string &)
	Named constructor, creates an implementation object with a specific name. More...

	Channel (const Channel &)
	Copy constructor, shares implementation with the rhs. More...

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

bool	operator== (const Channel &) const
	Comparison operator, checks if this channel is the same as another. More...

Stream *	setDataStream (const Stream &newStream)
	Set a new named data stream. More...

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

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

bool	removeDataStream (const std::string &)
	Destroy the data stream with the given name. More...

bool	renameDataStream (const std::string &, const std::string &)
	Rename a Stream. More...

bool	makeUnique ()
	Make the channel data unique to this object. More...

const std::string &	name () const
	Get the name of this Channel, const-version. More...

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

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

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

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

unsigned int	size () const
	Get the number of Streams on this Channel. More...

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

bool	removeElement (const Index &elementIndex)
	Remove a single element from this data channel. More...

bool	addElement (const Index &elementIndex)
	Add a new data element to the channel. More...

unsigned int	dataStreamCount () const
	Get the number of data streams in this channel. More...

Stream *	dataStream (unsigned int streamIndex)
	Get the named data stream, either const or non-const. More...

Stream *	dataStream (const std::string &streamName)
	Get the data stream of the given name. More...

Static Public Member Functions
static bool	Debug (const Channel *me, Debug::Print &request)
	Answer a Print request for a Channel object. More...

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

Constructor & Destructor Documentation

Channel ( const std::string & name )

explicit

Named constructor, creates an implementation object with a specific name.

Parameters

[in] name Name of the Channel to construct

Channel ( const Channel & rhs )

Copy constructor, shares implementation with the rhs.

Parameters

[in] rhs Channel data to be copied

Member Function Documentation

Channel & operator= ( const Channel & rhs )

Assignment operator, shares implementation with the rhs.

Parameters

[in] rhs Channel data to be copied

bool operator== ( const Channel & rhs ) const

Comparison operator, checks if this channel is the same as another.

Parameters

[in] rhs Channel data to be compared

Returns: true if the two channels reference the same data

Stream * setDataStream ( const Stream & newStream )

Set a new named data stream.

Does not insist that the stream name is unique; asking for it by name when there are duplicates will return the first one found. If you are creating duplicates you have to iterate to find all streams with the same name.

This method creates a copy of the stream to be owned by the channel. This will not duplicate the data in the stream, just the stream information.

Parameters

[in] newStream New stream to be added to the channel

Returns: Newly added data stream (copy of the one passed in)

Examples:: MetadataXML/channelSerializerXML.cpp.

const Stream * findDataStream ( const std::string & streamName ) const

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

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

Parameters

[in] streamName Name of Stream to retrieve

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

Stream * findDataStream ( const std::string & streamName )

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

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

Parameters

[in] streamName Name of Stream to retrieve

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

bool removeDataStream ( const std::string & streamName )

Destroy the data stream with the given name.

Parameters

[in] streamName Name of the Stream to remove

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

bool renameDataStream	(	const std::string &	oldStreamName,
		const std::string &	newStreamName
	)

Rename a Stream.

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

Parameters

[in]	oldStreamName	Name of the Stream to be renamed
[in]	newStreamName	New name for the Stream to be renamed

Returns: True if the Stream was found and renamed

bool makeUnique ( )

Make the channel 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

const std::string & name ( ) const

Get the name of this Channel, const-version.

Returns: Const reference to the Channel's name

Examples:: MetadataSample/importMetadataCmd.cpp, and MetadataXML/channelSerializerXML.cpp.

Channel::iterator begin ( ) const

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

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

Channel::iterator end ( ) const

Get an iterator off the end of the Stream list.

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

Channel::iterator cbegin ( ) const

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

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

Channel::iterator cend ( ) const

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

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

unsigned int size ( ) const

Get the number of Streams on this Channel.

Returns: number of Streams on this Channel

bool empty ( ) const

Check to see if the Stream list is empty.

Returns: true if there are no Streams on this Channel

bool removeElement ( const Index & elementIndex )

Remove a single element from this data channel.

Parameters

[in] elementIndex Index of the data to be removed

Returns: false if any of the streams failed to remove an element at the given index

bool addElement ( const Index & elementIndex )

Add a new data element to the channel.

The data element at the new index will be filled in based on the rules/callbacks on the data stream data.

Parameters

[in] elementIndex Index of the data to be added

Returns: true if the element was added to at least one stream

unsigned int dataStreamCount ( ) const

Get the number of data streams in this channel.

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

Returns: the number of data streams currently in this channel

Examples:: MetadataSample/importMetadataCmd.cpp, and MetadataXML/channelSerializerXML.cpp.

Stream * dataStream ( unsigned int streamIndex )

Get the named data stream, either const or non-const.

Obsolete, use the iterator. Positioning is not guaranteed.

Parameters

[in] streamIndex Index of the stream to retrieve

Returns: The associated stream at the given index, NULL if no stream

Examples:: MetadataSample/importMetadataCmd.cpp, and MetadataXML/channelSerializerXML.cpp.

Stream * dataStream ( const std::string & streamName )

Get the data stream of the given name.

Note that the Stream is a reference to the original so any changes. you make to it will be reflected in the channel.

Parameters

[in] streamName Name of the stream to retrieve

Returns: Stream attached to the channel by the given name, NULL if no stream by that name

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

static

Answer a Print request for a Channel object.

Use the request object to dump all information on the "me" Channel, or all static Channel 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 Channel *	me,
		Debug::Footprint &	request
	)

static

Answer a footprint request for a Channel 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 Channel 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:

adskDataChannel.h
adskDataChannel.cpp

Channel Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation