Loris::Partial Class Reference

#include <Partial.h>

List of all members.

Public Types

typedef std::map< double,
Breakpoint > 		container_type
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)
 Partial (const Partial &other)
 ~Partial (void)
 Destroy this Partial.
Partial & operator= (const Partial &other)
iterator begin (void)
const_iterator begin (void) const
iterator end (void)
const_iterator end (void) const
iterator erase (iterator beg, iterator end)
iterator findAfter (double time)
const_iterator findAfter (double time) const
iterator insert (double time, const Breakpoint &bp)
size_type size (void) const
double duration (void) const
double endTime (void) const
Breakpoint & first (void)
const Breakpoint & first (void) const
double initialPhase (void) const
label_type label (void) const
 Return the 32-bit label for this Partial as an integer.
Breakpoint & last (void)
const Breakpoint & last (void) const
size_type numBreakpoints (void) const
 Same as size(). Return the number of Breakpoints in this Partial.
double startTime (void) const
void absorb (const Partial &other)
void setLabel (label_type l)
 Set the label for this Partial to the specified 32-bit value.
iterator erase (iterator pos)
iterator findNearest (double time)
const_iterator findNearest (double time) const
Partial split (iterator pos)
double amplitudeAt (double time, double fadeTime=ShortestSafeFadeTime) const
double bandwidthAt (double time) const
double frequencyAt (double time) const
double phaseAt (double time) const
Breakpoint parametersAt (double time, double fadeTime=ShortestSafeFadeTime) const

Static Public Attributes

static const double ShortestSafeFadeTime

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)

Member Typedef Documentation

typedef std::map< double, Breakpoint > Loris::Partial::container_type

underlying Breakpoint container type, used by the iterator types defined below:

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.
const_iterator Loris::Partial::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 Loris::Partial::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.

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

The documentation for this class was generated from the following file:
Generated by  doxygen 1.6.2