Cinder  0.9.1
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cinder::audio::Param Class Reference

#include <Param.h>

Classes

struct  Options
 

Public Member Functions

 Param (Node *parentNode, float initialValue=0)
 
void setValue (float value)
 
float getValue () const
 
const float * getValueArray ()
 
EventRef applyRamp (float valueEnd, double rampSeconds, const Options &options=Options())
 
EventRef applyRamp (float valueBegin, float valueEnd, double rampSeconds, const Options &options=Options())
 
EventRef appendRamp (float valueEnd, double rampSeconds, const Options &options=Options())
 
EventRef appendRamp (float valueBegin, float valueEnd, double rampSeconds, const Options &options=Options())
 
void setProcessor (const NodeRef &node)
 
NodeRef getProcessor () const
 
void reset ()
 
size_t getNumEvents () const
 
bool eval ()
 
bool eval (double timeBegin, float *array, size_t arrayLength, size_t sampleRate)
 
float findDuration () const
 
std::pair< double, float > findEndTimeAndValue () const
 

Protected Member Functions

void initInternalBuffer ()
 
void resetImpl ()
 
void removeEventsAt (double time)
 
ContextRef getContext () const
 

Protected Attributes

std::list< EventRefmEvents
 
std::atomic< float > mValue
 
bool mIsVaryingThisBlock
 
NodemParentNode
 
NodeRef mProcessor
 
BufferDynamic mInternalBuffer
 

Detailed Description

Allows an audio parameter to be controlled over time with sample accurate curves.

The Param class enables expressive control over variables that control audio::Node's with a Timeline-esque API. It supports appending 'ramps' (audio animations) and maintains these in an internal timeline that is evaluated from the audio thread. You can also set a Node as the 'processor' with Param::setProcessor(), enabling you to control it with an arbitrary signal.

A Param is owned by a parent Node, from which it gains access to the current Context. This is a necessary step in making it sample accurate yet still controllable in a thread-safe manager on the user thread.

Note
Ramp Events should not overlap, or you may get discontinuities in the evaluated curve. This could potentially happen when using multiple appendRamp() calls. Instead, use applyRamp() and set Options::beginTime() accordingly, which will remove any Events that would otherwise be overlapping.

Constructor & Destructor Documentation

cinder::audio::Param::Param ( Node parentNode,
float  initialValue = 0 
)

Constructs a Param with a pointer (weak reference) to the owning parent Node and an optional initialValue (default = 0).

Member Function Documentation

void cinder::audio::Param::setValue ( float  value)

Sets the value of the Param, blowing away any scheduled Event's or processing Node.

Note
Must be called from a non-audio thread.
float cinder::audio::Param::getValue ( ) const

Returns the current value of the Param.

const float * cinder::audio::Param::getValueArray ( )

Returns an array of values, time varying if Events were processed, or filled with the a constant value if there were no Events this block.

Returns a pointer to the buffer used when evaluating a Param that is varying over the current processing block, of equal size to the owning Context's frames per block.

Note
If not varying (eval() returns false), the returned pointer will be invalid.
Must call eval() once per block before using this method.
EventRef cinder::audio::Param::applyRamp ( float  valueEnd,
double  rampSeconds,
const Options options = Options() 
)

Apply a ramp Event from the current value to valueEnd over rampSeconds, replacing any existing Events when this one begins. Any existing processing Node is disconnected.

See also
Options.
EventRef cinder::audio::Param::applyRamp ( float  valueBegin,
float  valueEnd,
double  rampSeconds,
const Options options = Options() 
)

Apply a ramp Event from tvalueBegin to valueEnd over rampSeconds, replacing any existing Events when this one begins. Any existing processing Node is disconnected.

See also
Options.
EventRef cinder::audio::Param::appendRamp ( float  valueEnd,
double  rampSeconds,
const Options options = Options() 
)

Appends a ramp Event onto the end of the last scheduled Event (or the current time) to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected.

EventRef cinder::audio::Param::appendRamp ( float  valueBegin,
float  valueEnd,
double  rampSeconds,
const Options options = Options() 
)

Appends an ramp Event onto the end of the last scheduled Event (or the current time), from valueBegin to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected.

void cinder::audio::Param::setProcessor ( const NodeRef node)

Sets this Param's input to be the processing performed by node. Any existing Event's are discarded.

Note
Forces node to be mono.
NodeRef cinder::audio::Param::getProcessor ( ) const

Returns this Param's processing Node, or an empty NodeRef if none is set.

void cinder::audio::Param::reset ( )

Resets Param, blowing away any Event's or processing Node.

Note
Must be called from a non-audio thread.
size_t cinder::audio::Param::getNumEvents ( ) const

Returns the number of Event's that are currently scheduled.

bool cinder::audio::Param::eval ( )

Evaluates the Param for the current processing block, with current time determined from the parent Node's Context.

Returns
true if the Param is varying this block (there are Event's or a processing Node) and getValueArray() should be used, or false if the Param's value is constant for this block (use getValue()).
Note
Safe to call on the audio thread.
bool cinder::audio::Param::eval ( double  timeBegin,
float *  array,
size_t  arrayLength,
size_t  sampleRate 
)

Evaluates the Param from timeBegin for arrayLength samples at sampleRate.

Returns
true if the Param is varying this block (there are Event's or a processing Node) and getValueArray() should be used, or false if the Param's value is constant for this block (use getValue()).
Note
Safe to call on the audio thread.
float cinder::audio::Param::findDuration ( ) const

Returns the total duration of any scheduled Event's, including delay, or 0 if none are scheduled.

pair< double, float > cinder::audio::Param::findEndTimeAndValue ( ) const

Returns the end time and value of the latest scheduled Event, or [0, getValue()] if none are scheduled.

void cinder::audio::Param::initInternalBuffer ( )
protected
void cinder::audio::Param::resetImpl ( )
protected
void cinder::audio::Param::removeEventsAt ( double  time)
protected
ContextRef cinder::audio::Param::getContext ( ) const
protected

Member Data Documentation

std::list<EventRef> cinder::audio::Param::mEvents
protected
std::atomic<float> cinder::audio::Param::mValue
protected
bool cinder::audio::Param::mIsVaryingThisBlock
protected
Node* cinder::audio::Param::mParentNode
protected
NodeRef cinder::audio::Param::mProcessor
protected
BufferDynamic cinder::audio::Param::mInternalBuffer
protected

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