MKPartials.h

/*
  $Id: MKPartials.h 3251 2005-05-11 07:59:04Z leighsmith $
  Defined In: The MusicKit

  Description:
    A MKPartials object contains arrays that specify the amplitudes,
    frequency ratios, and initial phases of a set of partials.  This
    information is used to synthesize a waveform.  The synthesized data is
    referenced by the methods inherited from MKWaveTable.
    
    Ordinarily, the frequency ratios are multiplied by the base frequency
    of the MKUnitGenerator that uses the MKPartials object.  Similarly, the
    amplitude ratios defined in the MKPartials object are multiplied by the
    MKUnitGenerator's amplitude term.
    
    MKPartials objects can also deliver their data as Waveshaping tables.

  Original Author: David A. Jaffe

  Copyright (c) 1988-1992, NeXT Computer, Inc.
  Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
  Portions Copyright (c) 1994 CCRMA, Stanford University.
  Portions Copyright (c) 1999-2001, The MusicKit Project.
*/
#ifndef __MK_Partials_H___
#define __MK_Partials_H___
//sb:
#import <Foundation/Foundation.h>

#import <Foundation/NSObject.h>
#import "MKWaveTable.h"
#import "MKSamples.h"

@interface MKPartials : MKWaveTable 
{
    double *ampRatios;   
    double *freqRatios;  
    double *phases;      
    int partialCount;    
    double defaultPhase; 
    double minFreq;      
    double maxFreq;      
@private
    BOOL _ampArrayFreeable,_freqArrayFreeable,_phaseArrayFreeable;
    BOOL dbMode;
    int tableType;
}
 

- init; 

 /* 
  * Returns a copy of the receiver with its own copy of arrays. 
  * See also superclass -copy.
  */
- copyWithZone:(NSZone *)zone;

  /* Frees the receiver and all its arrays. */
- (void)dealloc; 

- (NSString*) description;

- (double) highestFreqRatio;

- setPartialCount: (int) count
       freqRatios: (double *) freqRatios
        ampRatios: (double *) ampRatios
           phases: (double *) phases
   orDefaultPhase: (double) defaultPhase;
 /* 
   This method is used to specify the amplitude and frequency
   ratios and initial phases (in degrees) of a set of partials representing a
   waveform.  If one of the data retrieval methods is called (inherited from 
   the MKWaveTable object), a wavetable is synthesized and returned.
   The resulting waveform is guaranteed to begin and end 
   at or near the same point only if the partial ratios are integers.

   If phs is NULL, the defPhase value is used for all
   harmonics.  If aRatios or fRatios is NULL, the corresponding value is
   unchanged. The array arguments are copied. */


- setFromSamples:(MKSamples *)samplesObject;
    
-prunePartials:(double)amplitudeThreshold;

- (int)partialCount;

- (double *)freqRatios; 

- (double *)ampRatios; 

- (double)defaultPhase;

- (double *)phases; 

- (int) getPartial: (int) n
         freqRatio: (double *) fRatio
          ampRatio: (double *) aRatio
             phase: (double *) phase;
 /* 
   Get specified partial by reference. n is the zero-based
   index of the partial. If the specified partial is the last value, 
   returns 2. If the specified value is out of bounds, 
   returns -1. Otherwise returns 0.
   The partial amplitude is scaled by the scaling constant.
   */


-writeScorefileStream:(NSMutableData *)aStream;

  /* 
     You never send this message directly. It's invoked by 
     NXWriteRootObject() */
- (void)encodeWithCoder:(NSCoder *)aCoder;

  /* 
     Note that -init is not sent to newly unarchived objects.
     You never send this message directly. It's invoked by NXReadObject() */
- (id)initWithCoder:(NSCoder *)aDecoder;

  /* The following methods are obsolete.  See MKTimbre. */
-setFreqRangeLow:(double)freq1 high:(double)freq2;
-(double)minFreq;
-(double)maxFreq;
-(BOOL)freqWithinRange:(double)freq;


-(int)tableType;

@end

@interface MKPartials(OscTable)

 /* The following methods are minor variations of 
    dataDoubleAsOscTableScaling:length: and
    dataDSPAsOscTableScaling:length: and are implemented in terms 
    of them. They use default or previously specified length, scaling or both. 

    Same as corresponding superclass methods.
*/
    
- (DSPDatum *) dataDSPAsOscTable;

- (DSPDatum *) dataDSPAsOscTableLength:(int)aLength;

- (double *)   dataDoubleAsOscTable;

- (double *)   dataDoubleAsOscTableLength:(int)aLength;

- fillOscTableLength:(int)aLength scale:(double)aScaling ;

- fillTableLength: (unsigned int) aLength scale: (double) aScaling;

@end

@interface MKPartials(WaveshapingTable)

 /* The following methods are minor variations of 
    dataDoubleAsWaveshapingTableScaling:length: and
    dataDSPAsWaveshapingTableScaling:length: and are implemented in terms 
    of them. They use default or previously specified length, scaling or both. 
    */
- (DSPDatum *) dataDSPAsWaveshapingTable;
- (DSPDatum *) dataDSPAsWaveshapingTableLength:(int)aLength;
- (DSPDatum *) dataDSPAsWaveshapingTableScale:(double)aScaling;

- (DSPDatum *) dataDSPAsWaveshapingTableLength: (unsigned int) aLength scale: (double) aScaling;
 
- (double *)   dataDoubleAsWaveshapingTable;

- (double *)   dataDoubleAsWaveshapingTableLength:(int)aLength;

- (double *)   dataDoubleAsWaveshapingTableScale:(double)aScaling;

- (double *) dataDoubleAsWaveshapingTableLength: (unsigned int) aLength scale: (double) aScaling; 

- fillWaveshapingTableLength: (unsigned int) aLength scale: (double) aScaling;

@end

#endif

---