< SndEnveloping > Protocol Reference

Declares a formal protocol for objects to be used as envelopes. More...

#import <SndEnvelope.h>

Inheritance diagram for < SndEnveloping >:

List of all members.

Public Member Functions
(float)	- lookupYForX:
	Returns a y value for the given x value, according to its internal envelope.
(int)	- breakpointIndexBeforeOrEqualToX:
	Returns the index of the last breakpoint with exactly the given xVal, or the last breakpoint with less than the given xVal.
(int)	- breakpointIndexAfterX:
	Returns the index of the first breakpoint with an x value greater than the given xVal.
(double)	- lookupXForBreakpoint:
	Returns the x value corresponding to the requested breakpoint.
(float)	- lookupYForBreakpoint:
	Returns the y value corresponding to the requested breakpoint.
(int)	- lookupFlagsForBreakpoint:
	Returns the flags corresponding to the requested breakpoint.
(int)	- breakpointCount
	Returns the number of breakpoints in the envelope.
(int)	- insertXValue:yValue:flags:
	Creates a new breakpoint in the envelope and returns the new breakpoint index.
(int)	- insertXValue:yValue:flags:atBreakpoint:
	Creates a new breakpoint with the given data, and inserts it in the envelope at the specified location.
(BOOL)	- removeBreakpoint:
	Removes the breakpoint at the specified index.
(BOOL)	- removeBreakpointsBefore:
	Removes all breakpoints with index less than (not including) the index specified.
(BOOL)	- removeBreakpointsAfter:
	Removes all breakpoints with index greater than (not including) the index specified.
(BOOL)	- replaceXValue:yValue:flags:atBreakpoint:
	Changes the values at a specified breakpoint.

---

Detailed Description

Declares a formal protocol for objects to be used as envelopes.

This protocol describes the minimum functionality required from a class for it to be able to function within SndAudioFader as an envelope storage and lookup class.

The primary implementation of this protocol is the SndEnvelope class, but it is intended that the MusicKit's MKEnvelope should conform to SndEnveloping too in future, by way of a category.

As the protocol is used for envelopes used in shaping audio streams just before audio output, implementations should be as fast and efficient as possible.

An envelope in this context is a series of breakpoints, which describe points on a graph of some parameter vs. time. If the parameter being described is amplitude, the envelope might hold the following breakpoints: amplitude 0.9 at time 0.0, amplitude 0.5 at time 3.0, amplitude 0.6 at time 10.03.

Further to these x (time) and y (amplitude) values however, SndEnveloping implementations also hold information with each breakpoint about how that breakpoint relates or joins to its surrounding breakpoints. Should each y value be held static until the next breakpoint arrives (stepping), or should the value of the parameter move steadily from one point to another (ramping)?

SndEnveloping itself does not make any assumptions about these flags; it simply defines their existance and provides a means for them to be accessed by the calling object. Nevertheless, a SndEnveloping implementation is free to make assumptions about these flags if it wishes - in fact, it will need to make some decisions like this in order to implement -lookupYForX: for inter-breakpoint x-values.

SndEnveloping defines the following types for use in its breakpoints: x-values (time) are doubles, y-values are floats (eg for amplitudes of 0.0 to 1.0, or balance values from -1.0 to +1.0), and flags are signed integers. Breakpoint indices are signed ints, as they need to allow for BP_NOT_FOUND, which can returned by the -breakpointIndex... methods as an error value.

---

Member Function Documentation

- (float) lookupYForX:

(double)

xVal

Returns a y value for the given x value, according to its internal envelope.

Implementations are free to implement this in any way they wish, but the most obvious implementation is to return a linear interpolation between adjacent breakpoints, if the given x vale does not correspond exactly with a breakpoint.

Parameters:

xVal

(assumed positive)

Returns:

float

- (int) breakpointIndexBeforeOrEqualToX:

(double)

xVal

Returns the index of the last breakpoint with exactly the given xVal, or the last breakpoint with less than the given xVal.

Returns BP_NOT_FOUND if xVal is less than the x value of the first breakpoint, or if there are no breakpoints.

Parameters:

xVal

Returns:

int

- (int) breakpointIndexAfterX:

(double)

xVal

Returns the index of the first breakpoint with an x value greater than the given xVal.

Parameters:

xVal

Returns:

Returns BP_NOT_FOUND if there are no breakpoints after xVal.

Reimplemented in SndEnvelope.

- (double) lookupXForBreakpoint:

(int)

bp

Returns the x value corresponding to the requested breakpoint.

Behaviour is undefined (implementation specific) if the breakpoint does not exist. There's no point in returning BP_NOT_FOUND as that could be a valid x value to return.

Parameters:

bp

Returns:

double a valid x value

- (float) lookupYForBreakpoint:

(int)

bp

Returns the y value corresponding to the requested breakpoint.

Behaviour is undefined (implementation specific) if the breakpoint does not exist. There's no point in returning BP_NOT_FOUND as that could be a valid y value to return.

Parameters:

bp

Returns:

To come

Reimplemented in SndEnvelope.

- (int) lookupFlagsForBreakpoint:

(int)

bp

Returns the flags corresponding to the requested breakpoint.

Behaviour is undefined (implementation specific) if the breakpoint does not exist. There's no point in returning BP_NOT_FOUND as that could be a valid flags value to return.

Parameters:

bp

Returns:

To come

- (int) breakpointCount

Returns the number of breakpoints in the envelope.

Returns:

The number of breakpoints in the envelope.

- (int) insertXValue:		(double)	xVal
yValue:		(float)	yVal
flags:		(int)	flags

Creates a new breakpoint in the envelope and returns the new breakpoint index.

Subsequent breakpoints have their indices incremented by one

Parameters:

	xVal
	yVal
	flags

Returns:

returns new breakpoint index

Reimplemented in SndEnvelope.

- (int) insertXValue:		(double)	xVal
yValue:		(float)	yVal
flags:		(int)	flags
atBreakpoint:		(int)	bp

Creates a new breakpoint with the given data, and inserts it in the envelope at the specified location.

If you know in advance that a given breakpoint should be slotted in at a given index, use this method instead of -insertXValue:yValue:flags:, as this avoids unecessary walking through the breakpoints. Implementations are not obligated to actually use the given breakpoint, but must return the actual index used.

Parameters:

	xVal
	yVal
	flags
	bp

Returns:

int the index of the inserted breakpoint.

Reimplemented in SndEnvelope.

- (BOOL) removeBreakpoint:

(int)

bp

Removes the breakpoint at the specified index.

Parameters:

bp

Returns:

BOOL whether or not a breakpoint was removed

Reimplemented in SndEnvelope.

- (BOOL) removeBreakpointsBefore:

(int)

aBreakpoint

Removes all breakpoints with index less than (not including) the index specified.

Parameters:

aBreakpoint

Returns:

BOOL whether or not any breakpoints were removed

Reimplemented in SndEnvelope.

- (BOOL) removeBreakpointsAfter:

(int)

aBreakpoint

Removes all breakpoints with index greater than (not including) the index specified.

Parameters:

aBreakpoint

Returns:

BOOL whether or not any breakpoints were removed

Reimplemented in SndEnvelope.

- (BOOL) replaceXValue:		(double)	xVal
yValue:		(float)	yVal
flags:		(int)	flags
atBreakpoint:		(int)	bp

Changes the values at a specified breakpoint.

If you just want to change one value, you'll need to request all the other values from the specified breakpoint first, then call this method.

Parameters:

	xVal
	yVal
	flags
	bp

Returns:

BOOL whether or not the operation was successful

Reimplemented in SndEnvelope.

---

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

• SndEnvelope.h