Channel Class Reference

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013, Meta Data.

---

Search for all occurrences

---

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

#include <adskDataChannel.h>

List of all members.

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.
	Channel (const Channel &)
	Copy constructor, shares implementation with the rhs.
Channel &	operator= (const Channel &)
	Assignment operator, shares implementation with the rhs.
bool	operator== (const Channel &) const
	Comparison operator, checks if this channel is the same as another.
Stream *	setDataStream (const Stream &newStream)
	Set a new named data stream.
const Stream *	findDataStream (const std::string &) const
	Get the Stream with the given name, return NULL if it doesn't exist.
Stream *	findDataStream (const std::string &)
	Get the Stream with the given name, return NULL if it doesn't exist.
bool	removeDataStream (const std::string &)
	Destroy the data stream with the given name.
bool	renameDataStream (const std::string &, const std::string &)
	Rename a Stream.
bool	makeUnique ()
	Make the channel data unique to this object.
const std::string &	name () const
	Get the name of this Channel, const-version.
Channel::iterator	begin () const
	Get an iterator pointed to the beginning of the Stream list.
Channel::iterator	end () const
	Get an iterator off the end of the Stream list.
Channel::const_iterator	cbegin () const
	Get a read-only iterator pointed to the beginning of the Stream list.
Channel::const_iterator	cend () const
	Get a read-only iterator off the end of the Stream list.
unsigned int	size () const
	Get the number of Streams on this Channel.
bool	empty () const
	Check to see if the Stream list is empty.
bool	removeElement (const Index &elementIndex)
	Remove a single element from this data channel.
bool	addElement (const Index &elementIndex)
	Add a new data element to the channel.
unsigned int	dataStreamCount () const
	Get the number of data streams in this channel.
Stream *	dataStream (unsigned int streamIndex)
	Get the named data stream, either const or non-const.
Stream *	dataStream (const std::string &streamName)
	Get the data stream of the given name.
Static Public Member Functions
static bool	Debug (const Channel *me, Debug::Print &request)
	Answer a Print request for a Channel object.
static bool	Debug (const Channel *me, Debug::Footprint &request)
	Answer a footprint request for a Channel object.

---

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

)

Search for all occurrences

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)

const Stream * findDataStream

(

const std::string &

streamName

)

const

Search for all occurrences

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

)

Search for all occurrences

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

)

Search for all occurrences

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
	)

Search for all occurrences

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

(

)

Search for all occurrences

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

Search for all occurrences

Get the name of this Channel, const-version.

Returns:

Const reference to the Channel's name

Channel::iterator begin

(

)

const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Get the number of Streams on this Channel.

Returns:

number of Streams on this Channel

bool empty

(

)

const

Search for all occurrences

Check to see if the Stream list is empty.

Returns:

true if there are no Streams on this Channel

bool removeElement

(

const Index &

elementIndex

)

Search for all occurrences

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

)

Search for all occurrences

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

Search for all occurrences

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

Stream * dataStream

(

unsigned int

streamIndex

)

Search for all occurrences

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

Stream * dataStream

(

const std::string &

streamName

)

Search for all occurrences

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]

Search for all occurrences

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]

Search for all occurrences

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.