Cinder  0.8.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cinder::audio::Param Class Reference

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

#include <Param.h>

Classes

struct  Options
 Optional parameters when applying or appending ramps. More...
 

Public Member Functions

 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). More...
 
void setValue (float value)
 Sets the value of the Param, blowing away any scheduled Event's or processing Node. More...
 
float getValue () const
 Returns the current value of the Param. More...
 
const float * getValueArray () const
 
EventRef applyRamp (float valueEnd, float rampSeconds, const Options &options=Options())
 Replaces any existing Event's with a Event from the current value to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected. More...
 
EventRef applyRamp (float valueBegin, float valueEnd, float rampSeconds, const Options &options=Options())
 Replaces any existing Event's with a Event from valueBegin to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected. More...
 
EventRef appendRamp (float valueEnd, float rampSeconds, const Options &options=Options())
 Appends a Event from the end of the last scheduled Param (or the current time) to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected. More...
 
void setProcessor (const NodeRef &node)
 
void reset ()
 Resets Param, blowing away any Event's or processing Node. More...
 
size_t getNumEvents () const
 Returns the number of Event's that are currently scheduled. More...
 
bool eval ()
 
bool eval (float timeBegin, float *array, size_t arrayLength, size_t sampleRate)
 
float findDuration () const
 Returns the total duration of any scheduled Event's, including delay, or 0 if none are scheduled. More...
 
std::pair< float, float > findEndTimeAndValue () const
 Returns the end time and value of the latest scheduled Event, or [0, getValue()] if none are scheduled. More...
 

Protected Member Functions

void initInternalBuffer ()
 
void resetImpl ()
 
ContextRef getContext () const
 

Protected Attributes

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

Detailed Description

Allows an audio parameter to be controlled over time with sample accuracate 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.

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 ( ) const

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.
EventRef cinder::audio::Param::applyRamp ( float  valueEnd,
float  rampSeconds,
const Options options = Options() 
)

Replaces any existing Event's with a Event from the current value to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected.

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

Replaces any existing Event's with a Event from valueBegin to valueEnd over rampSeconds, according to options. Any existing processing Node is disconnected.

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

Appends a Event from the end of the last scheduled Param (or the current time) 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.
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 ( float  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< float, 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
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
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: