Loris::Partial Class Reference

An instance of class Partial represents a single component in the reassigned bandwidth-enhanced additive model. More...

#include <Partial.h>

List of all members.

Public Types
typedef std::map< double, Breakpoint >	container_type
	underlying Breakpoint container type, used by the iterator types defined below:
typedef int	label_type
	32 bit type for labeling Partials
typedef Partial_Iterator	iterator
	non-const iterator over (time, Breakpoint) pairs in this Partial
typedef Partial_ConstIterator	const_iterator
	const iterator over (time, Breakpoint) pairs in this Partial
typedef container_type::size_type	size_type
	size type for number of Breakpoints in this Partial
Public Member Functions
	Partial (void)
	Retun a new empty (no Breakpoints) Partial.
	Partial (const_iterator beg, const_iterator end)
	Retun a new Partial from a half-open (const) iterator range of time-Breakpoint pairs.
	Partial (const Partial &other)
	Return a new Partial that is an exact copy (has an identical set of Breakpoints, at identical times, and the same label) of another Partial.
	~Partial (void)
	Destroy this Partial.
Partial &	operator= (const Partial &other)
	Make this Partial an exact copy (has an identical set of Breakpoints, at identical times, and the same label) of another Partial.
iterator	begin (void)
	Return an iterator refering to the position of the first Breakpoint in this Partial's envelope, or end() if there are no Breakpoints in the Partial.
const_iterator	begin (void) const
	Return a const iterator refering to the position of the first Breakpoint in this Partial's envelope, or end() if there are no Breakpoints in the Partial.
iterator	end (void)
	Return an iterator refering to the position past the last Breakpoint in this Partial's envelope.
const_iterator	end (void) const
	Return a const iterator refering to the position past the last Breakpoint in this Partial's envelope.
iterator	erase (iterator beg, iterator end)
	Breakpoint removal: erase the Breakpoints in the specified range, and return an iterator referring to the position after the, erased range.
iterator	findAfter (double time)
	Return an iterator refering to the insertion position for a Breakpoint at the specified time (that is, the position of the first Breakpoint at a time later than the specified time).
const_iterator	findAfter (double time) const
	Return a const iterator refering to the insertion position for a Breakpoint at the specified time (that is, the position of the first Breakpoint at a time later than the specified time).
iterator	insert (double time, const Breakpoint &bp)
	Breakpoint insertion: insert a copy of the specified Breakpoint in the parameter envelope at time (seconds), and return an iterator refering to the position of the inserted Breakpoint.
size_type	size (void) const
	Return the number of Breakpoints in this Partial.
double	duration (void) const
	Return the duration (in seconds) spanned by the Breakpoints in this Partial.
double	endTime (void) const
	Return the time (in seconds) of the last Breakpoint in this Partial.
Breakpoint &	first (void)
	Return a reference to the first Breakpoint in the Partial's envelope.
const Breakpoint &	first (void) const
	Return a const reference to the first Breakpoint in the Partial's envelope.
double	initialPhase (void) const
	Return the phase (in radians) of this Partial at its start time (the phase of the first Breakpoint).
label_type	label (void) const
	Return the 32-bit label for this Partial as an integer.
Breakpoint &	last (void)
	Return a reference to the last Breakpoint in the Partial's envelope.
const Breakpoint &	last (void) const
	Return a const reference to the last Breakpoint in the Partial's envelope.
size_type	numBreakpoints (void) const
	Same as size(). Return the number of Breakpoints in this Partial.
double	startTime (void) const
	Return the time (in seconds) of the first Breakpoint in this Partial.
void	absorb (const Partial &other)
	Absorb another Partial's energy as noise (bandwidth), by accumulating the other's energy as noise energy in the portion of this Partial's envelope that overlaps (in time) with the other Partial's envelope.
void	setLabel (label_type l)
	Set the label for this Partial to the specified 32-bit value.
iterator	erase (iterator pos)
	Remove the Breakpoint at the position of the given iterator, invalidating the iterator.
iterator	findNearest (double time)
	Return an iterator refering to the position of the Breakpoint in this Partial nearest the specified time.
const_iterator	findNearest (double time) const
	Return a const iterator refering to the position of the Breakpoint in this Partial nearest the specified time.
Partial	split (iterator pos)
	Break this Partial at the specified position (iterator).
double	amplitudeAt (double time, double fadeTime=ShortestSafeFadeTime) const
	Return the interpolated amplitude of this Partial at the specified time.
double	bandwidthAt (double time) const
	Return the interpolated bandwidth (noisiness) coefficient of this Partial at the specified time.
double	frequencyAt (double time) const
	Return the interpolated frequency (in Hz) of this Partial at the specified time.
double	phaseAt (double time) const
	Return the interpolated phase (in radians) of this Partial at the specified time.
Breakpoint	parametersAt (double time, double fadeTime=ShortestSafeFadeTime) const
	Return the interpolated parameters of this Partial at the specified time, same as building a Breakpoint from the results of frequencyAt, ampitudeAt, bandwidthAt, and phaseAt, but performs only one Breakpoint envelope search.
Static Public Attributes
const double	ShortestSafeFadeTime
	Define the default fade time for computing amplitude at the ends of a Partial.

---

Detailed Description

An instance of class Partial represents a single component in the reassigned bandwidth-enhanced additive model.

A Partial consists of a chain of Breakpoints describing the time-varying frequency, amplitude, and bandwidth (or noisiness) envelopes of the component, and a 4-byte label. The Breakpoints are non-uniformly distributed in time. For more information about Reassigned Bandwidth-Enhanced Analysis and the Reassigned Bandwidth-Enhanced Additive Sound Model, refer to the Loris website: www.cerlsoundgroup.org/Loris/.

The constituent time-tagged Breakpoints are accessible through Partial:iterator and Partial::const_iterator interfaces. These iterator classes implement the interface for bidirectional iterators in the STL, including pre and post-increment and decrement, and dereferencing. Dereferencing a Partial::itertator or Partial::const_itertator yields a reference to a Breakpoint. Additionally, these iterator classes have breakpoint() and time() members, returning the Breakpoint (by reference) at the current iterator position and the time (by value) corresponding to that Breakpoint.

Partial is a leaf class, do not subclass.

Most of the implementation of Partial delegates to a few container-dependent members. The following members are container-dependent, the other members are implemented in terms of these: default construction copy (construction) operator= (assign) operator== (equivalence) size insert( pos, Breakpoint ) erase( b, e ) findAfter( time ) begin (const and non-const) end (const and non-const) first (const and non-const) last (const and non-const)

---

Constructor & Destructor Documentation

Loris::Partial::Partial (  const_iterator  beg, const_iterator  end )

Retun a new Partial from a half-open (const) iterator range of time-Breakpoint pairs. Parameters: beg  is the beginning of the range of time-Breakpoint pairs to insert into the new Partial. end  is the end of the range of time-Breakpoint pairs to insert into the new Partial.

Loris::Partial::Partial (  const Partial &  other  )

Return a new Partial that is an exact copy (has an identical set of Breakpoints, at identical times, and the same label) of another Partial. Parameters: other  is the Partial to copy.

---

Member Function Documentation

void Loris::Partial::absorb (  const Partial &  other  )

Absorb another Partial's energy as noise (bandwidth), by accumulating the other's energy as noise energy in the portion of this Partial's envelope that overlaps (in time) with the other Partial's envelope. Parameters: other  is the Partial to absorb.

double Loris::Partial::amplitudeAt (  double  time, double  fadeTime = ShortestSafeFadeTime )  const

Return the interpolated amplitude of this Partial at the specified time. If non-zero fadeTime is specified, then the amplitude at the ends of the Partial is computed using a linear fade. The default fadeTime is ShortestSafeFadeTime, see the definition of ShortestSafeFadeTime, above. Parameters: time  is the time in seconds at which to evaluate the Partial. fadeTime  is the duration in seconds over which Partial amplitudes fade at the ends. The default value is ShortestSafeFadeTime, 1 ns. Returns: The amplitude of this Partial at the specified time. Precondition: The Partial must have at least one Breakpoint. Exceptions: InvalidPartial  if the Partial has no Breakpoints.

double Loris::Partial::bandwidthAt (  double  time  )  const

Return the interpolated bandwidth (noisiness) coefficient of this Partial at the specified time. At times beyond the ends of the Partial, return the bandwidth coefficient at the nearest envelope endpoint. Parameters: time  is the time in seconds at which to evaluate the Partial. Returns: The bandwidth of this Partial at the specified time. Precondition: The Partial must have at least one Breakpoint. Exceptions: InvalidPartial  if the Partial has no Breakpoints.

double Loris::Partial::duration (  void   )  const

Return the duration (in seconds) spanned by the Breakpoints in this Partial. Note that the synthesized onset time will differ, depending on the fade time used to synthesize this Partial (see class Synthesizer).

const_iterator Loris::Partial::end (  void   )  const

Return a const iterator refering to the position past the last Breakpoint in this Partial's envelope. The iterator returned by end() (like the iterator returned by the end() member of any STL container) does not refer to a valid Breakpoint.

iterator Loris::Partial::end (  void   )

Return an iterator refering to the position past the last Breakpoint in this Partial's envelope. The iterator returned by end() (like the iterator returned by the end() member of any STL container) does not refer to a valid Breakpoint.

double Loris::Partial::endTime (  void   )  const

Return the time (in seconds) of the last Breakpoint in this Partial. Note that the synthesized onset time will differ, depending on the fade time used to synthesize this Partial (see class Synthesizer).

iterator Loris::Partial::erase (  iterator  pos  )

Remove the Breakpoint at the position of the given iterator, invalidating the iterator. Return a iterator referring to the next valid position, or to the end of the Partial if the last Breakpoint is removed. Parameters: pos  is the position of the time-Breakpoint pair to be removed. Returns: The position (iterator) of the time-Breakpoint pair after the one that was removed. Postcondition: The iterator pos is invalid.

iterator Loris::Partial::erase (  iterator  beg, iterator  end )

Breakpoint removal: erase the Breakpoints in the specified range, and return an iterator referring to the position after the, erased range. Parameters: beg  is the beginning of the range of Breakpoints to erase end  is the end of the range of Breakpoints to erase Returns: The position of the first Breakpoint after the range of removed Breakpoints, or end() if the last Breakpoint in the Partial was removed.

const_iterator Loris::Partial::findAfter (  double  time  )  const

Return a const iterator refering to the insertion position for a Breakpoint at the specified time (that is, the position of the first Breakpoint at a time later than the specified time). Parameters: time  is the time in seconds to find Returns: The last position (iterator) at which a Breakpoint at the specified time could be inserted (the position of the first Breakpoint later than time).

iterator Loris::Partial::findAfter (  double  time  )

Return an iterator refering to the insertion position for a Breakpoint at the specified time (that is, the position of the first Breakpoint at a time later than the specified time). Parameters: time  is the time in seconds to find Returns: The last position (iterator) at which a Breakpoint at the specified time could be inserted (the position of the first Breakpoint later than time).

const_iterator Loris::Partial::findNearest (  double  time  )  const

Return a const iterator refering to the position of the Breakpoint in this Partial nearest the specified time. Parameters: time  is the time to find. Returns: The position (iterator) of the time-Breakpoint pair nearest (in time) to the specified time.

iterator Loris::Partial::findNearest (  double  time  )

Return an iterator refering to the position of the Breakpoint in this Partial nearest the specified time. Parameters: time  is the time to find. Returns: The position (iterator) of the time-Breakpoint pair nearest (in time) to the specified time.

const Breakpoint& Loris::Partial::first (  void   )  const

Return a const reference to the first Breakpoint in the Partial's envelope. Exceptions: InvalidPartial  if there are no Breakpoints.

Breakpoint& Loris::Partial::first (  void   )

Return a reference to the first Breakpoint in the Partial's envelope. Exceptions: InvalidPartial  if there are no Breakpoints.

double Loris::Partial::frequencyAt (  double  time  )  const

Return the interpolated frequency (in Hz) of this Partial at the specified time. At times beyond the ends of the Partial, return the frequency at the nearest envelope endpoint. Parameters: time  is the time in seconds at which to evaluate the Partial. Returns: The frequency of this Partial at the specified time. Precondition: The Partial must have at least one Breakpoint. Exceptions: InvalidPartial  if the Partial has no Breakpoints.

double Loris::Partial::initialPhase (  void   )  const

Return the phase (in radians) of this Partial at its start time (the phase of the first Breakpoint). Note that the initial synthesized phase will differ, depending on the fade time used to synthesize this Partial (see class Synthesizer).

iterator Loris::Partial::insert (  double  time, const Breakpoint &  bp )

Breakpoint insertion: insert a copy of the specified Breakpoint in the parameter envelope at time (seconds), and return an iterator refering to the position of the inserted Breakpoint. Parameters: time  is the time in seconds at which to insert the new Breakpoint. bp  is the new Breakpoint to insert. Returns: the position (iterator) of the newly-inserted time-Breakpoint pair.

const Breakpoint& Loris::Partial::last (  void   )  const

Return a const reference to the last Breakpoint in the Partial's envelope. Exceptions: InvalidPartial  if there are no Breakpoints.

Breakpoint& Loris::Partial::last (  void   )

Return a reference to the last Breakpoint in the Partial's envelope. Exceptions: InvalidPartial  if there are no Breakpoints.

Partial& Loris::Partial::operator= (  const Partial &  other  )

Make this Partial an exact copy (has an identical set of Breakpoints, at identical times, and the same label) of another Partial. Parameters: other  is the Partial to copy.

Breakpoint Loris::Partial::parametersAt (  double  time, double  fadeTime = ShortestSafeFadeTime )  const

Return the interpolated parameters of this Partial at the specified time, same as building a Breakpoint from the results of frequencyAt, ampitudeAt, bandwidthAt, and phaseAt, but performs only one Breakpoint envelope search. If non-zero fadeTime is specified, then the amplitude at the ends of the Partial is coomputed using a linear fade. The default fadeTime is ShortestSafeFadeTime. Parameters: time  is the time in seconds at which to evaluate the Partial. fadeTime  is the duration in seconds over which Partial amplitudes fade at the ends. The default value is ShortestSafeFadeTime, 1 ns. Returns: A Breakpoint describing the parameters of this Partial at the specified time. Precondition: The Partial must have at least one Breakpoint. Exceptions: InvalidPartial  if the Partial has no Breakpoints.

double Loris::Partial::phaseAt (  double  time  )  const

Return the interpolated phase (in radians) of this Partial at the specified time. At times beyond the ends of the Partial, return the extrapolated from the nearest envelope endpoint (assuming constant frequency, as reported by frequencyAt()). Parameters: time  is the time in seconds at which to evaluate the Partial. Returns: The phase of this Partial at the specified time. Precondition: The Partial must have at least one Breakpoint. Exceptions: InvalidPartial  if the Partial has no Breakpoints.

size_type Loris::Partial::size (  void   )  const

Return the number of Breakpoints in this Partial. Returns: The number of Breakpoints in this Partial.

Partial Loris::Partial::split (  iterator  pos  )

Break this Partial at the specified position (iterator). The Breakpoint at the specified position becomes the first Breakpoint in a new Partial. Breakpoints at the specified position and subsequent positions are removed from this Partial and added to the new Partial, which is returned. Parameters: pos  is the position at which to split this Partial. Returns: A new Partial consisting of time-Breakpoint pairs beginning with pos and extending to the end of this Partial. Postcondition: All positions beginning with pos and extending to the end of this Partial have been removed.

double Loris::Partial::startTime (  void   )  const

Return the time (in seconds) of the first Breakpoint in this Partial. Note that the synthesized onset time will differ, depending on the fade time used to synthesize this Partial (see class Synthesizer).

---

Member Data Documentation

const double Loris::Partial::ShortestSafeFadeTime [static]

Define the default fade time for computing amplitude at the ends of a Partial. Floating point round-off errors make fadeTime == 0.0 dangerous and unpredictable. 1 ns is short enough to prevent rounding errors in the least significant bit of a 48-bit mantissa for times up to ten hours. 1 nanosecond, see Partial.C

---