OscgafUGs Class Reference

OscgafUGs is the superclass for OscgafUG and OscgafiUG oscillators. More...

#import <OscgafUGs.h>

Inheritance diagram for OscgafUGs:

List of all members.

Public Member Functions
(id)	- setIncScaler:
	Sets increment directly to an integer as specified.
(id)	- setPhase:
	Sets oscillator phase in degrees.
(id)	- setAmpInput:
	Sets amplitude envelope input to specified patchPoint.
(id)	- setOutput:
	Set output patchPoint of the oscillator.
(id)	- setIncInput:
	Set frequency envelope input to specified patchPoint.
(double)	- incAtFreq:
	Returns the phase increment for this unit generator based on aFreq.
(id)	- setIncRatio:
	This is an alternative to the -setIncScaler: method.
(id)	- setTable:length:
	Sets the lookup table of the oscillator.
(id)	- setTable:
	Like setTable:length:, but uses a default length.
(id)	- setTableToSineROM
	Sets the lookup table to the DSP sine ROM, if address space is Y.
(id)	- setTable:length:defaultToSineROM:
	This method is provided as a convenience.
(id)	- setTable:defaultToSineROM:
	Like setTable:length:defaultToSineROM:, but uses a default length.
(unsigned)	- tableLength
	Returns the length of the assigned table 0 if no table is assigned.
(double)	- incRatio
	Returns incRatio.
(id)	- runSelf
	Invoked by run method.
(id)	- idleSelf
	Deallocates local wave table memory, if any, and patches output to Sink.
Static Public Member Functions
(BOOL)	+ shouldOptimize:
	Specifies that all arguments are to be optimized if possible except the phase.
(int)	+ defaultTableLength:
	Returns a default table length determined by the type of subclass and type of argument.

---

Detailed Description

OscgafUGs is the superclass for OscgafUG and OscgafiUG oscillators.

OscgafUGs is the superclass for OscgafUG (non-interpolating or "drop-sample") and OscgafiUG (interpolating or "high-quality") oscillators. They are, in turn, derived from dsp macros /usr/local/lib/dsp/ugsrc/oscgaf.asm and oscgafi.asm. OscgafiUG and OscgafUG implement no methods of their own. They get all their behavior from OscgafUGs.

The fidelity of OscgafUG depends on the size of the table (larger tables have lower distortion) and the highest frequency represented in the table. For high-quality synthesis, OcgafiUG, is preferable. However, OscgafUG is less expensive (in terms of DSP cycles) and is useful in cases where density of texture is more important than fidelity of individual sounds.

The remainder of this discussion deals focuses on OscgafUGs, which embodies the characteristics that OscgafiUG and OscgafUG share.

OscgafUGs includes patchpoint arguments for amplitude and frequency control. That is, those parameters are intended to be determined by the output of some other unit generator, such as AsympUG. See the example synthpatch /LocalDeveloper/Examples/MusicKit/exampsynthpatch/FM.m for an example of its use.

Amplitude control is straightforward. The output of OscgafUGs is simply the value of the lookup table times whatever comes in via the ampEnvInput patchpoint. Frequency control is more complicated. The signal needed for freqEnvInput is not actually the frequency in Hertz, but the phase increment, which is the amount the lookup table index changes during each sample. This number depends on the desired frequency, the length of the lookup table, the sampling rate, and a constant called MK_OSCFREQSCALE. MK_OSCFREQSCALE is a power of two which represents the maximum possible increment. Input to freqEnvInput must be divided by this number in order to insure that it remains in the 24-bit signal range. The signal is then scaled back up by this number within OscgafUGs, with a possible additional scaling by the incRatio (see below).

A method called incAtFreq: has been provided which takes all the above factors into account and returns the increment for a given frequency. The lookup table must be set first, via the -setTable: method, since the length of the table must be known to perform the calculation. If more than one OscgafUGs is to be controlled by the same increment envelope signal (such as in a typical FM patch), they can have different frequencies by using the -setIncRatio: method. Since the input increment signal is scaled by MK_OSCFREQSCALE*incRatio within OscgafUGs, the resulting frequency will be correspondingly changed. The incRatio defaults to 1.0.

Alternatively, the increment scaler can be set directly with -setIncScaler:. This simply sets the increment scaler to the value you provide, ignoring MK_OSCFREQSCALE, incRatio, etc.

Memory Spaces

OscgafUGsabcd a output b amplitude input c increment (derivative of freq) input d table space

---

Member Function Documentation

+ (BOOL) shouldOptimize:

(unsigned)

arg

Specifies that all arguments are to be optimized if possible except the phase.

Parameters:

arg

is an unsigned.

Returns:

Returns an BOOL.

Reimplemented from MKUnitGenerator.

+ (int) defaultTableLength:

(id)

anObj

Returns a default table length determined by the type of subclass and type of argument.

Parameters:

anObj

is an id.

Returns:

Returns an int.

- (id) setIncScaler:

(int)

aScaler

Sets increment directly to an integer as specified.

Not normally called by the user.

Parameters:

aScaler

is an int.

Returns:

Returns an id.

- (id) setPhase:

(double)

aPhase

Sets oscillator phase in degrees.

Parameters:

aPhase

is a double.

Returns:

Returns an id. If wavetable has not yet been set, stores the value for -runSelf to use to set the phase later.

- (id) setAmpInput:

(id)

aPatchPoint

Sets amplitude envelope input to specified patchPoint.

Parameters:

aPatchPoint

is an id.

Returns:

Returns an id. The signal received via aPatchPoint serves as a multiplier on the output of the oscillator.

- (id) setOutput:

(id)

aPatchPoint

Set output patchPoint of the oscillator.

Parameters:

aPatchPoint

is an id.

Returns:

Returns an id.

- (id) setIncInput:

(id)

aPatchPoint

Set frequency envelope input to specified patchPoint.

Parameters:

aPatchPoint

is an id.

Returns:

Returns an id. Note that OscgafUGs implements a multiplicative frequency envelope. The actual phase increment is the value of the signal received via aPatchPoint multiplied by the incScaler. To get the proper increment value for a certain frequency, e.g, for use in a frequency envelope generator writing to the incEnvInput, see incAtFreq: below.

- (double) incAtFreq:

(double)

aFreq

Returns the phase increment for this unit generator based on aFreq.

Parameters:

aFreq

is a double.

Returns:

Returns a double. This value is suitable for use as the amplitude to a unit generator whose output is being used as the incEnvInput of this unit generator. The lookup table must be set before sending this message.

- (id) setIncRatio:

(double)

aRatio

This is an alternative to the -setIncScaler: method.

Parameters:

aRatio

is a double.

Returns:

Returns an id. The ratio specified here acts as a straight multiplier on the increment scaler, and hence on the frequency. For example, in an FM MKSynthPatch with one frequency envelope for both carrier and modulator, setIncRatio: sent to the modulator specifies the frequency ratio of the modulator/carrier. The ratio defaults to 1.0.

- (id) setTable:		(id)	anObj
length:		(int)	aLength

Sets the lookup table of the oscillator.

Parameters:

	anObj	is an id.
	aLength	is an int.

Returns:

Returns an id. anObj can be a MKSynthData object or a MKWaveTable (Partials or Samples).

This method first releases its claim on the locally-allocated MKSynthData, if any. (see below). Then, if anObj is a MKSynthData object, the MKSynthData object is used directly. If anObj is a MKWaveTable, the receiver first searches in its Orchestra's shared object table to see if there is already an existing MKSynthData based on the same MKWaveTable, of the same length, and in the required memory space. Otherwise, a local MKSynthData object is created and installed in the shared object table so that other unit generators running simultaneously may share it. If the requested size is too large, because there is not sufficient DSP memory, smaller sizes are tried. You can determine what size was used by sending the tableLength message. If anObj is nil, this method simply releases the locally-allocated MKSynthData, if any.

Note that altering the contents of a MKWaveTable will have no effect once it has been installed, even if you call setTable:length: again after modifying the MKWaveTable. The reason is that the Orchestra's shared data mechanism finds the requested object based on its id, rather than its contents.

You should not free WaveTables used as arguments to OscgafUGs until the performance is over.

If the table is not a power of 2, returns nil and generates the error MK_ugsPowerOf2Err.

- (id) setTable:

(id)

anObj

Like setTable:length:, but uses a default length.

Parameters:

anObj

is an id.

Returns:

Returns an id.

- (id) setTableToSineROM

Sets the lookup table to the DSP sine ROM, if address space is Y.

Returns:

Returns an id. Otherwise generates an error. Deallocates local wave table, if any.

- (id) setTable:		(id)	anObj
length:		(int)	aLength
defaultToSineROM:		(BOOL)	yesOrNo

This method is provided as a convenience.

Parameters:

	anObj	is an id.
	aLength	is an int.
	yesOrNo	is a BOOL.

Returns:

Returns an id. It tries to do 'the right thing' in cases where the table cannot be allocated.

If the table can be allocated, it behaves like setTable:length:. If the table cannot be allocated, and the table memory space of the receiver is Y, sends [self setTableToSineROM].

A common use of this method is to pass YES as the argument yesOrNo only if the MKSynthPatch is beginning a new phrase (the assumtion is that it is better to keep the old wavetable than to use the sine ROM in this case). Another use of this method is to specifically request the sine ROM by passing nil as anObj. If the sine ROM is used, the aLength argument is ignored.

If anObj is not nil and the sine ROM is used, generates the error MK_spsSineROMSubstitutionErr. If yesOrNo is YES but the receiver's table memory space is X, the error MK_spsCantGetMemoryErr is generated.

- (id) setTable:		(id)	anObj
defaultToSineROM:		(BOOL)	yesOrNo

Like setTable:length:defaultToSineROM:, but uses a default length.

Parameters:

	anObj	is an id.
	yesOrNo	is a BOOL.

Returns:

Returns an id.

- (unsigned) tableLength

Returns the length of the assigned table 0 if no table is assigned.

Returns:

Returns an unsigned int.

- (double) incRatio

Returns incRatio.

Returns:

Returns a double.

- (id) runSelf

Invoked by run method.

Returns:

Returns an id. Sets phase if -setPhase: was called before lookup table was set, and sets increment scaler if not already set by a call to -setIncRatio:. If wavetable has not been set, and table space is Y, uses DSP sine ROM.

Reimplemented from MKUnitGenerator.

- (id) idleSelf

Deallocates local wave table memory, if any, and patches output to Sink.

Returns:

Returns an id.

Reimplemented from MKUnitGenerator.

---

The documentation for this class was generated from the following file:

• OscgafUGs.h