A class that specifies the configuration and usage of a set of channels of audio. More...

#include <omSoundChannelLayout.h>

Public Types
enum	Type { MONO, STEREO, BINAURAL, QUAD, SURROUND_4 = QUAD, SURROUND_5_1, SURROUND_7_1, CUSTOM, UNDEFINED }
	An enum that is used to specify various pre-defined types of channel layouts. More...

Public Member Functions
	ChannelLayout ()
	Create a default channel layout with no channels. More...

	ChannelLayout (Size newNumChannels)
	Create a new channel layout with the specified number of channels. More...

	ChannelLayout (Type newType)
	Create a ChannelLayout object that has the specified predefined layout type. More...

	ChannelLayout (const ChannelLayout &other)
	Create a copy of the specified ChannelLayout object. More...

	~ChannelLayout ()
	Destroy all state used by a ChannelLayout object. More...

ChannelLayout &	operator= (const ChannelLayout &other)
	Assign the contents of one ChannelLayout to this object. More...

Bool	operator== (const ChannelLayout &other) const
	Return whether or not this channel layout is equal to another. More...

Bool	operator!= (const ChannelLayout &other) const
	Return whether or not this channel layout is not equal to another. More...

Type	getType () const
	Return the semantic kind of channel layout this layout corresponds to. More...

void	setType (Type newType)
	Set the semantic kind of channel layout this layout corresponds to. More...

Size	getChannelCount () const
	Return the total number of channels that are part of this channel layout. More...

void	setChannelCount (Size newNumChannels)
	Set the total number of channels that are part of this channel layout. More...

const ChannelInfo &	getChannelInfo (Index channelIndex) const
	Return a reference to the channel information object describing the channel at the given index. More...

void	setChannelInfo (Index channelIndex, const ChannelInfo &newInfo)
	Set the information about the channel at the specified index in this layout. More...

ChannelType	getChannelType (Index channelIndex) const
	Return an object representing the semantic type of the channel at the specified index. More...

void	setChannelType (Index channelIndex, ChannelType newType)
	Set the semantic type of the channel at the specified index. More...

Vector3f	getChannelPosition (Index channelIndex) const
	Return a the channel position at the specified index. More...

void	setChannelPosition (Index channelIndex, const Vector2f &newPosition)
	Set the position of the channel's speaker at the specified index. More...

void	setChannelPosition (Index channelIndex, const Vector3f &newPosition)
	Set the position of the channel's speaker at the specified index. More...

Bool	panDirection (const Vector3f &direction, Array< Gain > &channelGains) const
	Get the channel gain coefficients for a sound source in the specified direction. More...

Bool	mapLayout (const ChannelLayout &layout, ChannelMixMatrix &mixMatrix) const
	Get a channel mix matrix which maps the specified speaker layout to this one. More...

Bool	panLayout (const ChannelLayout &layout, const PanDirection &pan, ChannelMixMatrix &mixMatrix) const
	Get a channel mix matrix which maps the specified speaker layout to this one using the specified panning. More...

Detailed Description

A class that specifies the configuration and usage of a set of channels of audio.

A ChannelLayout object contains an enum value indicating the type of the layout. This value either indicates a predefined layout type for standard channel layout formats, or a custom or undefined layout. A custom layout indicates that a custom SpeakerLayout has been defined and is stored by the ChannelLayout object.

Member Enumeration Documentation

enum om::sound::base::ChannelLayout::Type

An enum that is used to specify various pre-defined types of channel layouts.

Enumerator
MONO	An enum value describing a ChannelLayout with only one speaker.
STEREO	An enum value describing a ChannelLayout for a basic stereo speaker system. The left and right speakers are placed 90 degrees left and right of front center. This doesn't correspond to the actual placement of stereo speakers but it is used to provide proper panning - stereo speakers at the normal placement of 30 degrees off center axis wouldn't produce as wide of a stereo image. Another benefit is that this corresponds to headphone positioning, where it will produce realistic panning.
BINAURAL	An enum value indicating a 2-channel binaural HRTF-based output format.
QUAD	An enum value describing a ChannelLayout for a 4-channel quadraphonic speaker system. Front left and right speakers are placed 30 degrees off of front center. Back left and right speakers are placed 95 degrees off of front center.
SURROUND_4	An alias for the QUAD speaker configuration.
SURROUND_5_1	An enum value describing a ChannelLayout for a 5.1 surround speaker system. Front left and right speakers are placed 30 degrees off of front center. Back left and right speakers are placed 110 degrees off of front center. The low frequency channel's positioning is undefined.
SURROUND_7_1	An enum value describing a ChannelLayout for a 7.1 surround speaker system. Front left and right speakers are placed 30 degrees off of front center. Back left and right speakers are placed 135 degrees off of front center. Side left and right speakers are placed 90 degrees off of front center. The low frequency channel's positioning is undefined.
CUSTOM	An enum value indicating a custom channel layout.
UNDEFINED	An enum value indicating an undefined type of channel layout.

Constructor & Destructor Documentation

om::sound::base::ChannelLayout::ChannelLayout ( )

Create a default channel layout with no channels.

om::sound::base::ChannelLayout::ChannelLayout ( Size newNumChannels )

Create a new channel layout with the specified number of channels.

All channels in the layout are initialized to have the ChannelType::UNDEFINED type and are non-positional.

om::sound::base::ChannelLayout::ChannelLayout ( Type newType )

Create a ChannelLayout object that has the specified predefined layout type.

The predefined layout type is used to determine the type and number of channels that should be in the layout.

om::sound::base::ChannelLayout::ChannelLayout ( const ChannelLayout & other )

Create a copy of the specified ChannelLayout object.

om::sound::base::ChannelLayout::~ChannelLayout ( )

Destroy all state used by a ChannelLayout object.

Member Function Documentation

ChannelLayout& om::sound::base::ChannelLayout::operator= ( const ChannelLayout & other )

Assign the contents of one ChannelLayout to this object.

Bool om::sound::base::ChannelLayout::operator== ( const ChannelLayout & other ) const

Return whether or not this channel layout is equal to another.

Bool om::sound::base::ChannelLayout::operator!= ( const ChannelLayout & other ) const

inline

Return whether or not this channel layout is not equal to another.

Type om::sound::base::ChannelLayout::getType ( ) const

inline

Return the semantic kind of channel layout this layout corresponds to.

void om::sound::base::ChannelLayout::setType ( Type newType )

Set the semantic kind of channel layout this layout corresponds to.

If the number of channels for the specified layout type is different than the current number of channels, the channel layout is enlarged for the new number of channels.

If the specified type is CUSTOM or UNDEFINED, the number and type of channels is unchanged.

Size om::sound::base::ChannelLayout::getChannelCount ( ) const

inline

Return the total number of channels that are part of this channel layout.

void om::sound::base::ChannelLayout::setChannelCount ( Size newNumChannels )

Set the total number of channels that are part of this channel layout.

If increasing the size of the layout, the new channels are initialized to have the ChannelType::UNDEFINED type and to be non-positional. If decreasing the size, the extra channels are just removed.

const ChannelInfo& om::sound::base::ChannelLayout::getChannelInfo ( Index channelIndex ) const

inline

Return a reference to the channel information object describing the channel at the given index.

If the given channel index is invalid, a reference to a placeholder undefined channel is returned.

void om::sound::base::ChannelLayout::setChannelInfo	(	Index	channelIndex,
		const ChannelInfo &	newInfo
	)

Set the information about the channel at the specified index in this layout.

This method completely replaces the previous state of the channel at the given index. If the channel index is invalid, the method has no effect.

ChannelType om::sound::base::ChannelLayout::getChannelType ( Index channelIndex ) const

inline

Return an object representing the semantic type of the channel at the specified index.

If the given channel index is invalid, the ChannelType::UNDEFINED type is returned.

void om::sound::base::ChannelLayout::setChannelType	(	Index	channelIndex,
		ChannelType	newType
	)

inline

Set the semantic type of the channel at the specified index.

If the given channel index is invalid, the method has no effect.

Vector3f om::sound::base::ChannelLayout::getChannelPosition ( Index channelIndex ) const

Return a the channel position at the specified index.

If the channel index is invalid or if the speaker is not positional, the vector (0,0,0) is returned.

void om::sound::base::ChannelLayout::setChannelPosition	(	Index	channelIndex,
		const Vector2f &	newPosition
	)

Set the position of the channel's speaker at the specified index.

void om::sound::base::ChannelLayout::setChannelPosition	(	Index	channelIndex,
		const Vector3f &	newPosition
	)

Set the position of the channel's speaker at the specified index.

Bool om::sound::base::ChannelLayout::panDirection	(	const Vector3f &	direction,
		Array< Gain > &	channelGains
	)		const

Get the channel gain coefficients for a sound source in the specified direction.

This method uses a vector-based amplitude panning implementation to determine the speakers that are located nearest to the specified 3D direction. It then computes the gain coefficients for each of those speakers that will localize a sound source in the given direction. Those linear gain coefficients are placed in the output array of channel gains. The output array may be enlarged if necessary to hold all of this speaker layout's channels.

The method returns TRUE if it succeeds and FALSE if there was an error. This can happen if the layout has no speakers.

Bool om::sound::base::ChannelLayout::mapLayout	(	const ChannelLayout &	layout,
		ChannelMixMatrix &	mixMatrix
	)		const

Get a channel mix matrix which maps the specified speaker layout to this one.

This method determines the best mapping from the specified arbitrary speaker layout to this speaker layout. The method returns TRUE if a mapping was found and FALSE if no mapping was found between the layouts. This can happen if either layout has no speakers.

Bool om::sound::base::ChannelLayout::panLayout	(	const ChannelLayout &	layout,
		const PanDirection &	pan,
		ChannelMixMatrix &	mixMatrix
	)		const

Get a channel mix matrix which maps the specified speaker layout to this one using the specified panning.

This method determines the best mapping from the specified arbitrary speaker layout to this speaker layout when the original layout is panned in the specified direction. The method returns TRUE if a mapping was found and FALSE if no mapping was found between the layouts. This can happen if either layout has no speakers.

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

omSoundChannelLayout.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation