MusicKit  0.0.0
MKPartials.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     A MKPartials object contains arrays that specify the amplitudes,
00007     frequency ratios, and initial phases of a set of partials.  This
00008     information is used to synthesize a waveform.  The synthesized data is
00009     referenced by the methods inherited from MKWaveTable.
00010     
00011     Ordinarily, the frequency ratios are multiplied by the base frequency
00012     of the MKUnitGenerator that uses the MKPartials object.  Similarly, the
00013     amplitude ratios defined in the MKPartials object are multiplied by the
00014     MKUnitGenerator's amplitude term.
00015     
00016     MKPartials objects can also deliver their data as Waveshaping tables.
00017 
00018   Original Author: David A. Jaffe
00019 
00020   Copyright (c) 1988-1992, NeXT Computer, Inc.
00021   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00022   Portions Copyright (c) 1994 CCRMA, Stanford University.
00023   Portions Copyright (c) 1999-2001, The MusicKit Project.
00024 */
00131 #ifndef __MK_Partials_H___
00132 #define __MK_Partials_H___
00133 //sb:
00134 #import <Foundation/Foundation.h>
00135 
00136 #import <Foundation/NSObject.h>
00137 #import "MKWaveTable.h"
00138 #import "MKSamples.h"
00139 
00140 @interface MKPartials : MKWaveTable 
00141 {
00142     double *ampRatios;   
00143     double *freqRatios;  
00144     double *phases;      
00145     int partialCount;    
00146     double defaultPhase; 
00147     double minFreq;      
00148     double maxFreq;      
00150 @private
00151     BOOL _ampArrayFreeable,_freqArrayFreeable,_phaseArrayFreeable;
00152     BOOL dbMode;
00153     int tableType;
00154 }
00155  
00156 
00165 - init; 
00166 
00167  /* 
00168   * Returns a copy of the receiver with its own copy of arrays. 
00169   * See also superclass -copy.
00170   */
00171 - copyWithZone:(NSZone *)zone;
00172 
00173   /* Frees the receiver and all its arrays. */
00174 - (void)dealloc; 
00175 
00176 - (NSString*) description;
00177 
00187 - (double) highestFreqRatio;
00188 
00213 - setPartialCount: (int) count
00214        freqRatios: (double *) freqRatios
00215         ampRatios: (double *) ampRatios
00216            phases: (double *) phases
00217    orDefaultPhase: (double) defaultPhase;
00218  /* 
00219    This method is used to specify the amplitude and frequency
00220    ratios and initial phases (in degrees) of a set of partials representing a
00221    waveform.  If one of the data retrieval methods is called (inherited from 
00222    the MKWaveTable object), a wavetable is synthesized and returned.
00223    The resulting waveform is guaranteed to begin and end 
00224    at or near the same point only if the partial ratios are integers.
00225 
00226    If phs is NULL, the defPhase value is used for all
00227    harmonics.  If aRatios or fRatios is NULL, the corresponding value is
00228    unchanged. The array arguments are copied. */
00229 
00230 
00240 - setFromSamples:(MKSamples *)samplesObject;
00241     
00249 -prunePartials:(double)amplitudeThreshold;
00250 
00255 - (int)partialCount;
00256 
00264 - (double *)freqRatios; 
00265 
00273 - (double *)ampRatios; 
00274 
00279 - (double)defaultPhase;
00280 
00288 - (double *)phases; 
00289 
00307 - (int) getPartial: (int) n
00308          freqRatio: (double *) fRatio
00309           ampRatio: (double *) aRatio
00310              phase: (double *) phase;
00311  /* 
00312    Get specified partial by reference. n is the zero-based
00313    index of the partial. If the specified partial is the last value, 
00314    returns 2. If the specified value is out of bounds, 
00315    returns -1. Otherwise returns 0.
00316    The partial amplitude is scaled by the scaling constant.
00317    */
00318 
00319 
00329 -writeScorefileStream:(NSMutableData *)aStream;
00330 
00331   /* 
00332      You never send this message directly. It's invoked by 
00333      NXWriteRootObject() */
00334 - (void)encodeWithCoder:(NSCoder *)aCoder;
00335 
00336   /* 
00337      Note that -init is not sent to newly unarchived objects.
00338      You never send this message directly. It's invoked by NXReadObject() */
00339 - (id)initWithCoder:(NSCoder *)aDecoder;
00340 
00341   /* The following methods are obsolete.  See MKTimbre. */
00342 -setFreqRangeLow:(double)freq1 high:(double)freq2;
00343 -(double)minFreq;
00344 -(double)maxFreq;
00345 -(BOOL)freqWithinRange:(double)freq;
00346 
00347 
00356 -(int)tableType;
00357 
00358 @end
00359 
00360 @interface MKPartials(OscTable)
00361 
00362  /* The following methods are minor variations of 
00363     dataDoubleAsOscTableScaling:length: and
00364     dataDSPAsOscTableScaling:length: and are implemented in terms 
00365     of them. They use default or previously specified length, scaling or both. 
00366 
00367     Same as corresponding superclass methods.
00368 */
00369     
00379 - (DSPDatum *) dataDSPAsOscTable;
00380 
00398 - (DSPDatum *) dataDSPAsOscTableLength:(int)aLength;
00399 
00409 - (double *)   dataDoubleAsOscTable;
00410 
00428 - (double *)   dataDoubleAsOscTableLength:(int)aLength;
00429 
00446 - fillOscTableLength:(int)aLength scale:(double)aScaling ;
00447 
00464 - fillTableLength: (unsigned int) aLength scale: (double) aScaling;
00465 
00466 @end
00467 
00468 @interface MKPartials(WaveshapingTable)
00469 
00470  /* The following methods are minor variations of 
00471     dataDoubleAsWaveshapingTableScaling:length: and
00472     dataDSPAsWaveshapingTableScaling:length: and are implemented in terms 
00473     of them. They use default or previously specified length, scaling or both. 
00474     */
00487 - (DSPDatum *) dataDSPAsWaveshapingTable;
00501 - (DSPDatum *) dataDSPAsWaveshapingTableLength:(int)aLength;
00515 - (DSPDatum *) dataDSPAsWaveshapingTableScale:(double)aScaling;
00516 
00536 - (DSPDatum *) dataDSPAsWaveshapingTableLength: (unsigned int) aLength scale: (double) aScaling;
00537  
00550 - (double *)   dataDoubleAsWaveshapingTable;
00551 
00565 - (double *)   dataDoubleAsWaveshapingTableLength:(int)aLength;
00566 
00580 - (double *)   dataDoubleAsWaveshapingTableScale:(double)aScaling;
00581 
00601 - (double *) dataDoubleAsWaveshapingTableLength: (unsigned int) aLength scale: (double) aScaling; 
00602 
00622 - fillWaveshapingTableLength: (unsigned int) aLength scale: (double) aScaling;
00623 
00624 @end
00625 
00626 #endif