A class that stores a directional transfer function for a linear acoustic system. More...

#include <omSoundDirectionalIR.h>

Public Types
enum	Representation { SAMPLED = 0, SPHERICAL_HARMONIC = 1 }
	An enum type that specifies the various representations that a directional IR can have. More...

enum	Domain { TIME_DOMAIN = 0, FREQUENCY_DOMAIN = 1, FREQUENCY_DOMAIN_MAGNITUDE = 2, FREQUENCY_DOMAIN_MAGNITUDE_PHASE = 3 }
	An enum type that specifies the domain that a directional IR is stored in. More...

enum	Phase { ORIGINAL_PHASE = 0, LINEAR_PHASE = 1, MIN_PHASE = 2 }
	An enum type that specifies the phase type of a filter reconstructed from magnitude-only data. More...

Public Member Functions
	DirectionalIR ()
	Create a new default sampled time-domain directional IR of length 256 with no channels. More...

	DirectionalIR (Size numChannels, Size length, SampleRate sampleRate=SampleRate(44100), Domain domain=TIME_DOMAIN)
	Create a new sampled directional IR with the specified number of channels. More...

	DirectionalIR (const DirectionalIR &other)
	Create a copy of the specified directional IR. More...

	~DirectionalIR ()
	Destroy a directional IR and release its internal data. More...

DirectionalIR &	operator= (const DirectionalIR &other)
	Assign the state of another directional IR to this one. More...

Representation	getRepresentation () const
	Return the representation type for this directional IR. More...

Domain	getDomain () const
	Return the domain type for this directional IR. More...

Bool	setDomain (Domain newDomain)
	Change the domain type for this directional IR. More...

Size	getLength () const
	Return the length in samples of this directional IR's time-domain impulse response. More...

void	setLength (Size newLength)
	Set the length in samples of this directional IR's time-domain impulse response. More...

Size	getChannelCount () const
	Return the number of channels there are in this directional IR. More...

ChannelInfo &	getChannelInfo (Index channelIndex)
	Return an object containing information about the channel at the specified index in this directional IR. More...

const ChannelInfo &	getChannelInfo (Index channelIndex) const
	Return an object containing information about the channel at the specified index in this directional IR. More...

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

void	setChannelCount (Size newChannelCount)
	Set the number of channels that are in this directional IR. More...

void	clearChannels ()
	Remove all channels and samples from this directional IR. More...

Size	getSampleCount (Index channelIndex) const
	Return the number of samples there are for the channel at the specified index. More...

const Vector3f &	getSampleDirection (Index channelIndex, Index sampleIndex) const
	Return the 3D cartesian vector for the specified sample. More...

Float	getSampleDelay (Index channelIndex, Index sampleIndex) const
	Return the delay time in seconds for the specified sample. More...

const Float32 *	getSampleData (Index channelIndex, Index sampleIndex) const
	Return the data for the specified sample. More...

Bool	addSample (Index channelIndex, const Vector3f &direction, Float delay, const FrequencyData &magnitude)
	Add a new sample of frequency-domain maginitude-only data to this directional IR. More...

Bool	addSample (Index channelIndex, const Vector3f &direction, Float delay, const Float32 *sampleData)
	Add a new sample to this directional IR. More...

void	clearSamples ()
	Clear all of the samples from this directional IR. More...

SampleRate	getSampleRate () const
	Return the sample rate that this directional IR is stored in. More...

void	setSampleRate (SampleRate newSampleRate)
	Set the sample rate that this directional IR is stored in. More...

const Matrix3f &	getOrientation () const
	Return a 3x3 orthonormal rotation matrix indicating the local coordinate basis of this directional IR. More...

void	setOrientation (const Matrix3f &newOrientation)
	Set a 3x3 orthonormal rotation matrix indicating the local coordinate basis of this directional IR. More...

const UTF8String &	getName () const
	Return a string containing the name of the acoustic system this directional IR was measured from. More...

void	setName (const UTF8String &newName)
	Set a string containing the name of the acoustic system this directional IR was measured from. More...

const UTF8String &	getDescription () const
	Return a string containing a description of this directional IR. More...

void	setDescription (const UTF8String &newDescription)
	Set a string containing a description of this directional IR. More...

Size	getSHOrder () const
	Return the spherical harmonic order that is used to represent this directional IR. More...

Size	getFilterLength () const
	Return the length of the internal filter data in the current domain type. More...

Size	getFilterLength (Domain domain) const
	Return the length of the output filter data in the specified domain type. More...

Size	getFilterDataLength () const
	Return the required floating-point storage for the output filter data. More...

Size	getFilter (Index channel, Domain domain, Phase phase, math::Interpolation interpolation, const Vector3f &xyz, Float *filterData) const
	Get the interpolated filter for a 3D cartesian direction for the channel with the specified index. More...

Size	getFilterSH (Index channel, Domain domain, Phase phase, Size shOrder, const Float shBasis, Float filterData) const
	Get the filter for a spherical harmonic basis for the channel with the specified index. More...

Bool	convertToSH (const math::SHProjection &projection, DirectionalIR &result) const
	Convert the data for this directional IR to the spherical harmonic representation using the specified parameters. More...

Bool	convertDomain (Domain domain, Phase phase, DirectionalIR &result) const
	Convert the data for this directional IR to the specified domain type. More...

Static Public Attributes
static const om::resources::ResourceType	RESOURCE_TYPE
	The resource type for a directional IR. More...

Detailed Description

A class that stores a directional transfer function for a linear acoustic system.

Multiple representations and filter domains are supported. The most common is sampled data, where the response is known at discrete direction samples. The data may also be stored in the spherical harmonic basis for more efficient interpolation and less memory usage.

Member Enumeration Documentation

enum om::sound::base::DirectionalIR::Representation

An enum type that specifies the various representations that a directional IR can have.

Enumerator

SAMPLED

The response is represented by data that is sampled for various discrete directions.

This is the raw format for a directional IR, consisting of transfer function measurements for a set of discrete directions. The response in other directions is interpolated from the nearest direction samples.

This format is generally less efficient for interpolation and filter reconstruction, and requires more memory.

SPHERICAL_HARMONIC

The response is represented in the spherical harmonic orthornormal function basis.

This representation is more efficient for runtime interpolation and filter reconstruction and generally uses much less memory. However, the spherical harmonic basis cannot easily represent sharp directivities, so some error may be introduced in the resulting filter versus the original sampled data.

enum om::sound::base::DirectionalIR::Domain

An enum type that specifies the domain that a directional IR is stored in.

Enumerator
TIME_DOMAIN	The response is stored as a sequence of time-domain pressure samples. This is the usual format for measured directional IR data and it is efficient for filter reconstruction, but is less suited to interpolation because it can introduce comb-filtering artifacts.
FREQUENCY_DOMAIN	The response is stored as complex (real+imaginary) frequency-domain samples. This format has better interpolation quality than time-domain data, but can still introduce some artifacts if the adjacent filters are very different in the frequency domain.
FREQUENCY_DOMAIN_MAGNITUDE	The response is stored as magnitude only in the frequency domain. This domain type tends to be the best for interpolation of HRTF data where the small-scale phase is less important. The phase is neglected and reconstructed after the magnitude response is interpolated. This reduces interpolation artifacts. A min-phase or linear-phase reconstruction is used to determine the phase.
FREQUENCY_DOMAIN_MAGNITUDE_PHASE	The response is stored as magnitude and phase in the frequency domain. This format does not have very good interpolation results, probably because the phase at different frequencies does not stay coherent between adjacent samples.

enum om::sound::base::DirectionalIR::Phase

An enum type that specifies the phase type of a filter reconstructed from magnitude-only data.

Enumerator

ORIGINAL_PHASE

When the filter is reconstructed from frequency domain data, the original phase data is used (if it exists).

If there is no phase data for the directional IR, a minimum phase filter is computed instead.

LINEAR_PHASE

When the filter is reconstructed from frequency domain data, a linear-phase filter is created.

This filter type has a latency of half the length of the directional IR in time domain.

To construct the filter, all imaginary components of the frequency-domain data are set to zero and an inverse FFT is performed. The first and last halves of the time-domain result are swapped to produce a causal linear-phase filter. While this filter type introduces more latency, the phase response is linear.

MIN_PHASE

When the filter is reconstructed from frequency domain data, a minimum-phase filter is created.

This filter type has the minimum possible latency for a causal filter at all frequencies.

To construct the filter, a Hilbert transform is performed on magnitude-only data to reconstruct the minimum phase for each frequency. An inverse FFT is performed to produce the time-domain result.

Constructor & Destructor Documentation

om::sound::base::DirectionalIR::DirectionalIR ( )

Create a new default sampled time-domain directional IR of length 256 with no channels.

om::sound::base::DirectionalIR::DirectionalIR	(	Size	numChannels,
		Size	length,
		SampleRate	sampleRate = `SampleRate(44100)`,
		Domain	domain = `TIME_DOMAIN`
	)

Create a new sampled directional IR with the specified number of channels.

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

Create a copy of the specified directional IR.

om::sound::base::DirectionalIR::~DirectionalIR ( )

Destroy a directional IR and release its internal data.

Member Function Documentation

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

Assign the state of another directional IR to this one.

Representation om::sound::base::DirectionalIR::getRepresentation ( ) const

inline

Return the representation type for this directional IR.

Domain om::sound::base::DirectionalIR::getDomain ( ) const

inline

Return the domain type for this directional IR.

Bool om::sound::base::DirectionalIR::setDomain ( Domain newDomain )

Change the domain type for this directional IR.

The data in ths directional IR is converted to the specified domain. If the method fails because the domain cannot be converted (e.g. if it is in a spherical harmonic representation), the method returns FALSE.

Size om::sound::base::DirectionalIR::getLength ( ) const

inline

Return the length in samples of this directional IR's time-domain impulse response.

void om::sound::base::DirectionalIR::setLength ( Size newLength )

Set the length in samples of this directional IR's time-domain impulse response.

The data stored in the response is converted so that it has the specified output length. Extra data is truncated or the response resampled if the length changes.

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

inline

Return the number of channels there are in this directional IR.

ChannelInfo& om::sound::base::DirectionalIR::getChannelInfo ( Index channelIndex )

inline

Return an object containing information about the channel at the specified index in this directional IR.

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

inline

Return an object containing information about the channel at the specified index in this directional IR.

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

inline

Set information about the channel at the specified index in this directional IR.

void om::sound::base::DirectionalIR::setChannelCount ( Size newChannelCount )

Set the number of channels that are in this directional IR.

If the number of channels increases, the new channels are empty. If the number of channels decreases, the last channels are discarded.

void om::sound::base::DirectionalIR::clearChannels ( )

Remove all channels and samples from this directional IR.

Size om::sound::base::DirectionalIR::getSampleCount ( Index channelIndex ) const

inline

Return the number of samples there are for the channel at the specified index.

const Vector3f& om::sound::base::DirectionalIR::getSampleDirection	(	Index	channelIndex,
		Index	sampleIndex
	)		const

inline

Return the 3D cartesian vector for the specified sample.

Float om::sound::base::DirectionalIR::getSampleDelay	(	Index	channelIndex,
		Index	sampleIndex
	)		const

inline

Return the delay time in seconds for the specified sample.

const Float32* om::sound::base::DirectionalIR::getSampleData	(	Index	channelIndex,
		Index	sampleIndex
	)		const

inline

Return the data for the specified sample.

Bool om::sound::base::DirectionalIR::addSample	(	Index	channelIndex,
		const Vector3f &	direction,
		Float	delay,
		const FrequencyData &	magnitude
	)

Add a new sample of frequency-domain maginitude-only data to this directional IR.

The method returns whether or not the sample data was able to be added.

Bool om::sound::base::DirectionalIR::addSample	(	Index	channelIndex,
		const Vector3f &	direction,
		Float	delay,
		const Float32 *	sampleData
	)

Add a new sample to this directional IR.

The sample data must be in the same domain as the directional IR and must be at least getFilterLength() floating-point numbers long.

The method returns whether or not the sample data was able to be added.

void om::sound::base::DirectionalIR::clearSamples ( )

Clear all of the samples from this directional IR.

SampleRate om::sound::base::DirectionalIR::getSampleRate ( ) const

inline

Return the sample rate that this directional IR is stored in.

void om::sound::base::DirectionalIR::setSampleRate ( SampleRate newSampleRate )

inline

Set the sample rate that this directional IR is stored in.

This method does not modify the directional IR data, just the sample rate that the data is interpreted in.

const Matrix3f& om::sound::base::DirectionalIR::getOrientation ( ) const

inline

Return a 3x3 orthonormal rotation matrix indicating the local coordinate basis of this directional IR.

This matrix transforms the directions in the directional IR before the filter is interpolated. This allows the HRTF to be rotated to match a given coordinate system convention.

void om::sound::base::DirectionalIR::setOrientation ( const Matrix3f & newOrientation )

inline

Set a 3x3 orthonormal rotation matrix indicating the local coordinate basis of this directional IR.

This matrix transforms the directions in the directional IR before the filter is interpolated. This allows the HRTF to be rotated to match a given coordinate system convention.

const UTF8String& om::sound::base::DirectionalIR::getName ( ) const

inline

Return a string containing the name of the acoustic system this directional IR was measured from.

void om::sound::base::DirectionalIR::setName ( const UTF8String & newName )

inline

Set a string containing the name of the acoustic system this directional IR was measured from.

const UTF8String& om::sound::base::DirectionalIR::getDescription ( ) const

inline

Return a string containing a description of this directional IR.

void om::sound::base::DirectionalIR::setDescription ( const UTF8String & newDescription )

inline

Set a string containing a description of this directional IR.

Size om::sound::base::DirectionalIR::getSHOrder ( ) const

inline

Return the spherical harmonic order that is used to represent this directional IR.

If the representation type is SPHERICAL_HARMONIC, the return value indicates the spherical harmonic order. Otherwise, the return value is 0.

Size om::sound::base::DirectionalIR::getFilterLength ( ) const

inline

Return the length of the internal filter data in the current domain type.

Size om::sound::base::DirectionalIR::getFilterLength ( Domain domain ) const

Return the length of the output filter data in the specified domain type.

The return value indicates the number of valid samples that will be written to the buffer. NOTE: The required storage for the output filter data is retured by getFilterDataLength().

Size om::sound::base::DirectionalIR::getFilterDataLength ( ) const

inline

Return the required floating-point storage for the output filter data.

This value may be more than the return value of getFilterLength() because extra space is required for intermediate data.

Size om::sound::base::DirectionalIR::getFilter	(	Index	channel,
		Domain	domain,
		Phase	phase,
		math::Interpolation	interpolation,
		const Vector3f &	xyz,
		Float *	filterData
	)		const

Get the interpolated filter for a 3D cartesian direction for the channel with the specified index.

The filter data buffer must have enough space to hold the number of values returned by getFilterDataLength().

The method returns the number of output samples that were written to the filter data buffer. A return value of 0 indicates that an error occurred.

Size om::sound::base::DirectionalIR::getFilterSH	(	Index	channel,
		Domain	domain,
		Phase	phase,
		Size	shOrder,
		const Float *	shBasis,
		Float *	filterData
	)		const

Get the filter for a spherical harmonic basis for the channel with the specified index.

This method should only be used for directional IRs that have the SPHERICAL_HARMONIC representation type.

NOTE: the SH basis must be specified in the response's local coordinate system if the orientation calibration matrix is not the identity matrix. Therefore, the orientation calbration must be applied externally when building the basis coefficients.

The filter data buffer must have enough space to hold the number of values returned by getFilterDataLength().

The method returns the number of output samples that were written to the filter data buffer. A return value of 0 indicates that an error occurred.

Bool om::sound::base::DirectionalIR::convertToSH	(	const math::SHProjection &	projection,
		DirectionalIR &	result
	)		const

Convert the data for this directional IR to the spherical harmonic representation using the specified parameters.

Bool om::sound::base::DirectionalIR::convertDomain	(	Domain	domain,
		Phase	phase,
		DirectionalIR &	result
	)		const

Convert the data for this directional IR to the specified domain type.

The output directional IR is initialized with the converted domain data from this response.

Member Data Documentation

const om::resources::ResourceType om::sound::base::DirectionalIR::RESOURCE_TYPE

static

The resource type for a directional IR.

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

omSoundDirectionalIR.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation