#import <MKEnvelope.h>
Public Member Functions | |
Creating and Freeing an Envelope | |
| (id) | - init |
| Initializes the object by setting its default smoothing to 1.0, its sampling period to 1.0, and its stickpoint to MAXINT. | |
Querying the Object | |
| (int) | - pointCount |
| Returns the number of breakpoints in the object. | |
| (double) | - defaultSmoothing |
| Returns the object's default smoothing value, or MK_NODVAL if there's a smoothing array. | |
| (double) | - samplingPeriod |
| Returns the sampling period, or MK_NODVAL if there's an x array. | |
| (int) | - stickPoint |
| Returns the stickpoint, or MAXINT if none. | |
| (double *) | - yArray |
| Returns a pointer to the object's y array, or NULL if none. | |
| (double *) | - xArray |
| Returns a pointer to the object's x array, or NULL if none. | |
| (double *) | - smoothingArray |
| Returns a pointer to the object's smoothing array, or NULL if none. | |
| (MKEnvStatus) | - getNth:x:y:smoothing: |
| Returns, by reference, the x, y, and smoothing values for the n'th breakpoint in the object counting from breakpoint 0. | |
| (id) | - writeScorefileStream: |
| Writes the object to the stream aStream in scorefile format. | |
| (double) | - lookupYForX: |
| Returns the y value that corresponds to xVal. | |
| (double) | - lookupYForXAsymptotic: |
| Same as lookupYForX, but assumes an asymptotic envelope, such as is produced by the AsympUG MKUnitGenerator. | |
| (double) | - releaseDur |
| Returns the duration of the release portion of the object. | |
| (double) | - attackDur |
| Returns the duration of the attack portion of the object. | |
Modifying the Object | |
| (id) | - setStickPoint: |
| Sets the object's stickpoint to the stickPointIndex'th breakpoint, counting from 0. | |
| (id) | - setPointCount:xArray:orSamplingPeriod:yArray:smoothingArray:orDefaultSmoothing: |
| Fills the object with data by copying the values from xPtr, yPtr, and smoothingPtr. | |
| (id) | - setPointCount:xArray:yArray: |
| This is a cover for the more complete setPointCount:xArray:orSamplingPeriod:... method. | |
Protected Attributes | |
| double | defaultSmoothing |
| double | samplingPeriod |
| double * | xArray |
| double * | yArray |
| double * | smoothingArray |
| int | stickPoint |
| int | pointCount |
The MKEnvelope class provides basic support for creating line segment functions. An MKEnvelope consists of a series of breakpoints each consisting of three values: x, y, and smoothing. The x and y values locate a value y at a particular time x. There is also a smoothing value associated with each breakpoint that is used primarily in AsympUG, a MKUnitGenerator that creates asymptotic envelope functions on the DSP. Smoothing defines the shape of the curve between breakpoints.
There are two ways to use an MKEnvelope: as a continuous function during DSP synthesis or to return a discrete value y for a given x.
To fill an MKEnvelope object with data, you invoke the method
setPointCount: xArray: orSamplingPeriod: yArray: smoothingArray: orDefaultSmoothing:
The argument to setPointCount: specifies the number of breakpoints in the MKEnvelope; the arguments to xArray:, yArray:, and smoothingArray: are pointers to arrays of x, y, and smoothing values for the Envelope's breakpoints. The range of musically useful y values depends on the parameter that the MKEnvelope will affect. For example, amplitude normally is between 0.0 and 1.0, while frequency is expressed in Hz and assumes values over the range of human hearing. The breakpoints in an MKEnvelope must succeed each other in time; thus, the values in the x array must get successively larger. By default, the x values are taken as seconds, although this interpretation can be modified through the use of auxilliary parameters, as explained below.
While you must always supply an array of y values, the same isn't true for x and smoothing. Rather than provide an x array, you can specify, as the argument to orSamplingPeriod:, a sampling period that's used as an x increment: The x value of the first breakpoint is 0.0, successive x values are integer multiples of the sampling period value. Similarly, you can supply a constant smoothing value, as the argument to orDefaultSmoothing:, rather than provide a smoothing array. In the presence of both an x array and a sampling period, or both a smoothing array and a default smoothing, the array takes precedence.
The shorthand method setPointCount:xArray:yArray: can also be used to fill an MKEnvelope with data.
Envelopes are described as having three parts: attack, sustain, and release. You can set the sustain portion of an MKEnvelope by designating one of its breakpoints as the stickpoint through the setStickPoint: method. Everything up to the stickpoint is the Envelope's attack; everything after the stickpoint is its release. When the stickpoint is reached during DSP synthesis, its y value is sustained until a noteOff arrives to signal the release (keep in mind that a noteDur is split into a noteOn/noteOff pair by MKSynthInstrumentobjects).
An MKEnvelope object is set as the value of a Note's parameter through Note's setPar:toEnvelope: method. Parameters that accept MKEnvelope objects usually have associated with them several other parameters that interpret the MKEnvelope by scaling and offsetting the Envelope's x and y values.
For example, the MK_ampEnv parameter takes an MKEnvelope as its value; MK_amp0and MK_amp1 are constant-valued parameters that scale and offset the y values in MK_ampEnv according to the formula
(scale* y) + offset
where scale is calculated as MK_amp1 - MK_amp0 and offset is simply the value of MK_amp0. In other words, MK_amp0 defines the interpreted value when y is 0.0 and MK_amp1 is the interpreted value when y is 1.0. While an Envelopes's x values are normally taken as an absolute time in seconds, MKSynthPatches usually provide additional parameters that let you reset the attack and release durations. For example, the MK_ampAtt parameter resets the duration of the attack portion of a Note's amplitude MKEnvelope; similarly, MK_ampRel resets the release duration.
When used in DSP synthesis, MKEnvelope objects are applied by a MKUnitGenerator such as AsympUG. AsympUG creates asymptotic curves between breakpoints. The shape of a segment going into a particular breakpoint is determined by that breakpoint's smoothing value (the smoothing value of the first breakpoint is ignored). Smoothing values should be between 0.0 and 1.0 where 0.0 means no smoothing (a stairstep function), and 1.0 takes the entire duration between points to arrive at (near) the y value. More precisely, a smoothing of 1.0 signifies that the AsympUG will reach within -48dB of the y value. A smoothing in excess of 1.0 causes the AsympUG trajectory to fall short of the next point's y value. See the AsympUG class description for the formula used to compute the asymptotic function.
Although MKEnvelope objects are most commonly used in DSP synthesis, they can also be used to return a discrete value of y for a given x, as provided in the method lookupYForX:. Discrete-value lookup is useful for controlling the way a constant-valued parameter evolves over a series of MKNotes. If the x value doesn't correspond exactly to a breakpoint in the MKEnvelope, the method does a linear interpolation between the immediately surrounding breakpoints.
Envelopes are automatically created by the Music Kit in a number of circumstances, such as when reading a Scorefile. The function MKSetEnvelopeClass() allows you to specify that your own subclass of MKEnvelope be used when Envelopes are automatically created.
| - (id) init |
Initializes the object by setting its default smoothing to 1.0, its sampling period to 1.0, and its stickpoint to MAXINT.
| - (int) pointCount |
Returns the number of breakpoints in the object.
| - (double) defaultSmoothing |
Returns the object's default smoothing value, or MK_NODVAL if there's a smoothing array.
| - (double) samplingPeriod |
Returns the sampling period, or MK_NODVAL if there's an x array.
| - (int) stickPoint |
Returns the stickpoint, or MAXINT if none.
| - (double *) yArray |
Returns a pointer to the object's y array, or NULL if none.
| - (double *) xArray |
Returns a pointer to the object's x array, or NULL if none.
| - (double *) smoothingArray |
Returns a pointer to the object's smoothing array, or NULL if none.
| - (MKEnvStatus) getNth: | (int) | n | ||
| x: | (double *) | xPtr | ||
| y: | (double *) | yPtr | ||
| smoothing: | (double *) | smoothingPtr | ||
Returns, by reference, the x, y, and smoothing values for the n'th breakpoint in the object counting from breakpoint 0.
| n | is an int. | |
| xPtr | is a double *. | |
| yPtr | is a double *. | |
| smoothingPtr | is a double *. |
| Position | Constant |
| last point in the object | MK_lastPoint |
| stickpoint | MK_stickPoint |
| point out of bounds | MK_noMorePoints |
| any other point | MK_noEnvError |
If the object's y array is NULL,or its x array is NULL and its sampling period is 0.0, MK_noMorePoints is returned.
| - (id) writeScorefileStream: | (NSMutableData *) | aStream |
Writes the object to the stream aStream in scorefile format.
| aStream | is a NSMutableData instance. |
(0.0, 0.0, 0.0) (0.3, 1.0, 0.05) | (0.5, 0.0, 0.2)Returns nil if the object's y array is NULL. Otherwise returns the object.
| - (double) lookupYForX: | (double) | xVal |
Returns the y value that corresponds to xVal.
| xVal | is a double. |
| - (double) lookupYForXAsymptotic: | (double) | xVal |
Same as lookupYForX, but assumes an asymptotic envelope, such as is produced by the AsympUG MKUnitGenerator.
| xVal | is a double. |
| - (double) releaseDur |
Returns the duration of the release portion of the object.
| - (double) attackDur |
Returns the duration of the attack portion of the object.
| - (id) setStickPoint: | (int) | stickPointIndex |
Sets the object's stickpoint to the stickPointIndex'th breakpoint, counting from 0.
Returns the object, or nil if stickPointIndex is out of bounds. Setting the stickpoint to MAXINT removes it.
| stickPointIndex | is an int. |
| - (id) setPointCount: | (int) | n | ||
| xArray: | (double *) | xPtr | ||
| orSamplingPeriod: | (double) | period | ||
| yArray: | (double *) | yPtr | ||
| smoothingArray: | (double *) | smoothingPtr | ||
| orDefaultSmoothing: | (double) | smoothing | ||
Fills the object with data by copying the values from xPtr, yPtr, and smoothingPtr.
If xPtr is NULL, the object's sampling period is set to period (otherwise period is ignored). Similarly, smoothing is used as the object's default smoothing in the absence of smoothingPtr. If yPtr is NULL, the object's y array is unchanged. Returns the object.
| n | is an int. | |
| xPtr | is a double *. | |
| period | is a double. | |
| yPtr | is a double *. | |
| smoothingPtr | is a double *. | |
| smoothing | is a double. |
| - (id) setPointCount: | (int) | n | ||
| xArray: | (double *) | xPtr | ||
| yArray: | (double *) | yPtr | ||
This is a cover for the more complete setPointCount:xArray:orSamplingPeriod:... method.
| n | is an int. | |
| xPtr | is a double *. | |
| yPtr | is a double *. |
- (double) defaultSmoothing [protected] |
If no Smoothing-array, this is time constant.
- (double) samplingPeriod [protected] |
If no X-array, this is abcissa scale
- (double*) xArray [protected] |
Array of x values, if any.
- (double*) yArray [protected] |
Arrays of data values
- (double*) smoothingArray [protected] |
Array of time constants.
- (int) stickPoint [protected] |
Index of "steady-state", if any
- (int) pointCount [protected] |
Number of points in envelope
1.5.6