MusicKit  0.0.0
OscgUG.h
00001 /*
00002   $Id$
00003   Defined In: This class is part of the Music Kit UnitGenerator Library.
00004 
00005   Description:
00006     Simple oscillator with no envelopes.
00007     classgroup Oscillators and Waveform Generators
00008 
00009     OscgUG  - from dsp macro /usr/lib/dsp/ugsrc/oscg.asm (see source for details).
00010 
00011     OscgUG<a><b>, where <a> is output space and <b> is table space.
00012 
00013     This is a non-interpolating oscillator. That means that its fidelity
00014     depends on the size of the table (larger tables have lower distortion)
00015     and the highest frequency represented in the table. For high-quality
00016     synthesis, an interpolating oscillator is preferable. However, an
00017     interpolating oscillator is also more expensive. OscgUG is useful
00018     in cases where density of texture is more important than fidelity of
00019     individual sounds.
00020 
00021     The wavetable length must be a power of 2.
00022     The wavetable increment must be nonnegative.
00023 
00024   Original Author: David A. Jaffe
00025 
00026   Copyright (c) 1988-1992, NeXT Computer, Inc.
00027   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00028   Portions Copyright (c) 1994 Stanford University
00029 */
00053 #ifndef __MK_OscgUG_H___
00054 #define __MK_OscgUG_H___
00055 
00056 #import <MusicKit/MKUnitGenerator.h>
00057 
00058 @interface OscgUG: MKUnitGenerator
00059 {
00060     double _reservedOscg1;
00061     double _reservedOscg2;
00062     double _reservedOscg3;
00063     id _reservedOscg4;
00064     int tableLength;          /* Or 0 if no table. */
00065 }
00066 
00075 + (BOOL) shouldOptimize: (unsigned) arg;
00076 
00080 - setInc: (int) anInc;
00081 
00090 - setFreq: (double) aFreq;
00091 
00099 - setAmp: (double) aAmp;
00100 
00110 - setPhase: (double) aPhase;
00111 
00123 -runSelf;
00124 /* Sets oscillator phase if -setPhase: was called before lookup table was 
00125    set, and sets oscillator frequency to the last value set with setFreq:.
00126    If wavetable has not been set, and table space is Y, uses DSP SINE ROM. */
00127 
00128 
00140 -idleSelf;
00141 /* Deallocates local wave table memory, if any, and patches output to Sink. */
00142 
00143 
00149 - setOutput: (id) aPatchPoint;
00150 
00178 - setTable: (id) anObj length: (int) aLength;
00179 /* 
00180    Sets the lookup table of the oscillator.
00181    anObj can be a SynthData object or a WaveTable (Partials or Samples).
00182 
00183    First releases its claim on the locally-allocated SynthData, if any. 
00184    (see below).
00185 
00186    If anObj is a SynthData object, the SynthData object is used directly.
00187 
00188    If anObj is a WaveTable, the receiver first searches in its Orchestra's
00189    shared object table to see if there is already an existing SynthData based 
00190    on the same WaveTable, of the same length, and in the required memory
00191    space. Otherwise, a local SynthData object is created and installed in the
00192    shared object table so that other unit generators running simultaneously 
00193    may share it. (This is important since DSP memory is limited.) 
00194    If the requested size is too large, because there is not sufficient DSP
00195    memory, smaller sizes are tried. (You can determine what size was used
00196    by sending the tableLength message.)
00197    
00198    Note that altering the contents of a WaveTable will have no effect once it 
00199    has been installed, even if you call setTable:length: again after 
00200    modifying the WaveTable. The reason is that the Orchestra's shared data
00201    mechanism finds the requested object based on its id, rather than its
00202    contents.
00203 
00204    If anObj is nil, simply releases the locally-allocated SynthData, if any. 
00205    If the table is not a power of 2, returns nil and generates the error
00206    MK_ugsPowerOf2Err. 
00207 */
00208 
00214 - setTable: (id) anObj;
00215 
00224 - setTableToSineROM;
00225 
00250 -setTable:anObj length:(int)aLength defaultToSineROM:(BOOL)yesOrNo;
00251 /* This method is provided as a convenience. It tries to do 'the right thing'
00252    in cases where the table cannot be allocated. 
00253 
00254    It functions like setTable:length:, but it defaults to the sine ROM in the 
00255    DSP if sineROMDefaultOK is YES, the DSP memory for anObj cannot be 
00256    allocated, and the table memory space of the receiver is Y.
00257    
00258    A common use of this method is to pass YES only if the SynthPatch is
00259    beginning a new phrase (the assumtion is that it is better to keep the
00260    old wavetable than to use the sine ROM in this case).
00261    Another use of this method is to specifically request the sine ROM by 
00262    passing nil as anObj. If the sine ROM is used, the aLength argument is
00263    ignored.
00264    
00265    Errors:
00266    If anObj is not nil and the sine ROM is used, generates the error 
00267    MK_spsSineROMSubstitutionErr. If sineROMDefaultOK is YES but the 
00268    receiver's table memory space is X, the error MK_spsCantGetMemoryErr 
00269    is generated.
00270 */   
00271 
00272 
00282 -setTable:anObj defaultToSineROM:(BOOL)yesOrNo;
00283 
00290 -(unsigned)tableLength;
00291 
00292 @end
00293 
00294 #endif