Klang C++ 0.7.15
Language Reference (draft)
Loading...
Searching...
No Matches
klang::ADSR

Language Guide / DSP and Analysis

ADSR

klang::ADSR

Attack, decay, sustain, and release envelope.

Set the attack, decay and release times in seconds and the sustain level as a linear value. Read the envelope once per sample to advance it. On note-off, call release() so it moves towards zero from its current level.

Example · Configure an amplitude envelope

With ADSR adsr; and Sine sine; as members, configure the envelope when the note starts.

adsr.set(0.01, 0.15, 0.5, 0.3);

Example · Retrigger with the existing settings

Call restart() to begin the attack again with the existing settings. The envelope still holds at the sustain level until you call release().

adsr.restart();

In process(), use the configured object for each sample.

sine * adsr >> out;

Attack-Decay-Sustain-Release Envelope. More...

#include <klang.h>

+ Inheritance diagram for klang::ADSR:

Public Types

enum  Mode { Time , Rate }
 
enum  Stage { Sustain , Release , Off }
 Envelope stage. More...
 

Public Member Functions

 ADSR ()
 
void set (param attack, param decay, param sustain, param release) override
 
void release (float time=0.f, float level=0.f) override
 
bool operator== (Envelope::Stage stage) const
 
bool operator!= (Stage stage) const
 
void set (const std::vector< Point > &points)
 
void set (const Points &point)
 
void set (Ramp *ramp)
 
void sequence ()
 
void setLoop (int startPoint, int endPoint)
 
signal at (param time) const
 
void resetLoop ()
 
void setStage (Stage stage)
 
const Stage getStage () const
 
float getLength () const
 
bool finished () const
 
void initialise ()
 
void restart ()
 Restart from the first point, preserving the configured loop.
 
void resize (float length)
 
void setTarget (const Point &point, float time=0.0)
 
signal & operator++ (int)
 
void process ()
 
const Point & operator[] (int point) const
 
void setMode (Mode mode)
 
Mode mode () const
 
Output< signal > & operator() (params &&... p)
 
 operator const signal & () override
 
 operator const signal & () const override
 
virtual const signal & output () const
 
TYPE & operator>> (TYPE &destination)
 
signal operator+ (TYPE &other)
 
signal operator* (TYPE &other)
 
signal operator- (TYPE &other)
 
signal operator/ (TYPE &other)
 
void reset ()
 

Public Attributes

param A
 
param D
 
param S
 
param R
 
enum klang::ADSR::Mode mode = Time
 
signal out
 

Protected Attributes

void(Envelope::* setTargetFunction )(const Point &point, float time) = &Envelope::setTargetTime
 
std::vector< Point > points
 
Loop loop
 
int point
 
float time
 
float timeInc
 
Stage stage
 
std::shared_ptr< Ramp > ramp
 

Detailed Description

Definition at line 5429 of file klang.h.

Member Enumeration Documentation

◆ Mode

Values
Time 
Rate 

Definition at line 5435 of file klang.h.

5435{ Time, Rate } mode = Time;
enum klang::ADSR::Mode mode

◆ Stage

enum klang::Envelope::Stage
inherited
Values
Sustain 
Release 
Off 

Definition at line 5128 of file klang.h.

Constructor & Destructor Documentation

◆ ADSR()

klang::ADSR::ADSR ( )
inline

Definition at line 5437 of file klang.h.

5437{ set(0.5, 0.5, 1, 0.5); }
void set(param attack, param decay, param sustain, param release) override
Definition klang.h:5439

Member Function Documentation

◆ at()

signal klang::Envelope::at ( param time) const
inlineinherited

Definition at line 5247 of file klang.h.

5247 {
5248 if (points.empty()) return 0;
5249 Point last = { 0, points[0].y };
5250 for (const Point& point : points) {
5251 if (point.x >= time) {
5252 const float dx = point.x - last.x;
5253 const float dy = point.y - last.y;
5254 const float x = time - last.x;
5255 return dx == 0 ? last.y : (last.y + x * dy / dx);
5256 }
5257 last = point;
5258 }
5259 return points.back().y;
5260 }
std::vector< Point > points
Definition klang.h:5418

◆ finished()

bool klang::Envelope::finished ( ) const
inlineinherited

Definition at line 5287 of file klang.h.

5287 {
5288 return getStage() == Stage::Off;
5289 }
const Stage getStage() const
Definition klang.h:5273

◆ getLength()

float klang::Envelope::getLength ( ) const
inlineinherited

Definition at line 5276 of file klang.h.

5276{ return points.size() ? points[points.size() - 1].x : 0.f; }

◆ getStage()

const Stage klang::Envelope::getStage ( ) const
inlineinherited

Definition at line 5273 of file klang.h.

5273{ return stage; }

◆ initialise()

void klang::Envelope::initialise ( )
inlineinherited

Definition at line 5292 of file klang.h.

5292 {
5293 loop.reset();
5294 restart();
5295 }
void restart()
Restart from the first point, preserving the configured loop.
Definition klang.h:5298

◆ mode()

Mode klang::Envelope::mode ( ) const
inlineinherited

Definition at line 5395 of file klang.h.

void setTargetTime(const Point &point, float time=0.0)
Definition klang.h:5401
void(Envelope::* setTargetFunction)(const Point &point, float time)
Definition klang.h:5399

◆ operator const signal &() [1/2]

klang::Generic::Generator< signal >::operator const signal & ( ) const
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Output< signal >.

Definition at line 3057 of file klang.h.

3057{ return out; } // return last output

◆ operator const signal &() [2/2]

klang::Generic::Generator< signal >::operator const signal & ( )
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Output< signal >.

Definition at line 3056 of file klang.h.

3056{ this->process(); return out; } // return processed output

◆ operator!=()

bool klang::Envelope::operator!= ( Stage stage) const
inlineinherited

Definition at line 5200 of file klang.h.

5200{ return Envelope::stage != stage; }

◆ operator()()

Output< signal > & klang::Generic::Generator< signal >::operator() ( params &&... p)
inlineinherited

Definition at line 3050 of file klang.h.

3050 {
3051 set(std::forward<params>(p)...); return *this;
3052 }

◆ operator*()

signal klang::Generic::Output< signal >::operator* ( TYPE & other)
inlineinherited

Definition at line 2977 of file klang.h.

2977{ this->process(); return out * SIGNAL(other); }

◆ operator+()

signal klang::Generic::Output< signal >::operator+ ( TYPE & other)
inlineinherited

Definition at line 2976 of file klang.h.

2976{ this->process(); return out + SIGNAL(other); }

◆ operator++()

signal & klang::Envelope::operator++ ( int )
inlineinherited

Definition at line 5337 of file klang.h.

5337 {
5338 this->process();
5339 return out;
5340 }
void process()
Definition klang.h:5342

◆ operator-()

signal klang::Generic::Output< signal >::operator- ( TYPE & other)
inlineinherited

Definition at line 2978 of file klang.h.

2978{ this->process(); return out - SIGNAL(other); }

◆ operator/()

signal klang::Generic::Output< signal >::operator/ ( TYPE & other)
inlineinherited

Definition at line 2979 of file klang.h.

2979{ this->process(); return out / SIGNAL(other); }

◆ operator==()

bool klang::ADSR::operator== ( Envelope::Stage stage) const
inline

Definition at line 5458 of file klang.h.

5458 {
5459 return getStage() == stage;
5460 }

◆ operator>>()

TYPE & klang::Generic::Output< signal >::operator>> ( TYPE & destination)
inlineinherited

Definition at line 2969 of file klang.h.

2969{ this->process(); return destination = out; }

◆ operator[]()

const Point & klang::Envelope::operator[] ( int point) const
inlineinherited

Definition at line 5378 of file klang.h.

5378 {
5379 return points[point];
5380 }

◆ output()

virtual const signal & klang::Generic::Output< signal >::output ( ) const
inlinevirtualinherited

Definition at line 2964 of file klang.h.

2964{ return out; }

◆ process()

void klang::Envelope::process ( )
inlinevirtualinherited

Implements klang::Generic::Output< signal >.

Definition at line 5342 of file klang.h.

5342 {
5343 out = (*ramp)++;
5344
5345 switch (stage) {
5346 case Sustain:
5347 time += timeInc;
5348 if (!ramp->isActive()) { // envelop segment end reached
5349 if (loop.isActive() && (point + 1) >= loop.end) {
5350 point = loop.start;
5351 ramp->setValue(points[point].y);
5352 if (loop.start != loop.end)
5353 setTarget(points[point + 1], points[point].x);
5354 }
5355 else if ((point + 1) < points.size()) {
5356 if (mode() == Rate || time >= points[point + 1].x) { // reached target point
5357 point++;
5358 ramp->setValue(points[point].y); // make sure exact value is set
5359
5360 if ((point + 1) < points.size()) // new target point?
5361 setTarget(points[point + 1], points[point].x);
5362 }
5363 }
5364 else {
5365 stage = Off;
5366 }
5367 } break;
5368 case Release:
5369 if (!ramp->isActive()) //if(out == 0.0)
5370 stage = Off;
5371 break;
5372 case Off:
5373 break;
5374 }
5375 }
std::shared_ptr< Ramp > ramp
Definition klang.h:5425
Mode mode() const
Definition klang.h:5395
void setTarget(const Point &point, float time=0.0)
Definition klang.h:5332
float timeInc
Definition klang.h:5422
bool isActive() const
Definition klang.h:5178

◆ release()

void klang::ADSR::release ( float time = 0.f,
float level = 0.f )
inlineoverridevirtual

Reimplemented from klang::Envelope.

Definition at line 5454 of file klang.h.

5454 {
5455 Envelope::release(time ? time : float(R), level);
5456 }
virtual void release(float time, float level=0.f)
Definition klang.h:5279
param R
Definition klang.h:5433

◆ reset()

void klang::Generic::Output< signal >::reset ( )
inlineinherited

Definition at line 2981 of file klang.h.

2981{ out = 0; }

◆ resetLoop()

void klang::Envelope::resetLoop ( )
inlineinherited

Definition at line 5263 of file klang.h.

5263 {
5264 loop.reset();
5265 if (stage == Sustain && (point + 1) < points.size())
5266 setTarget(points[point + 1], points[point].x);
5267 }

◆ resize()

void klang::Envelope::resize ( float length)
inlineinherited

Definition at line 5316 of file klang.h.

5316 {
5317 const float old_length = getLength();
5318 if (old_length == 0.0)
5319 return;
5320
5321 const float multiplier = length / (fs * old_length);
5322 std::vector<Point>::iterator point = points.begin();
5323 while (point != points.end()) {
5324 point->x *= multiplier;
5325 point++;
5326 }
5327
5328 initialise();
5329 }
void initialise()
Definition klang.h:5292
float getLength() const
Definition klang.h:5276
klang::dB fs

◆ restart()

void klang::Envelope::restart ( )
inlineinherited

Definition at line 5298 of file klang.h.

5298 {
5299 point = 0;
5300 time = 0;
5301 timeInc = 1.0f / fs;
5302 stage = Sustain;
5303 if (points.size()) {
5304 out = points[0].y;
5305 ramp->setValue(points[0].y);
5306 if (points.size() > 1)
5307 setTarget(points[1], points[0].x);
5308 }
5309 else {
5310 out = 1.0f;
5311 ramp->setValue(1.0f);
5312 }
5313 }

◆ sequence()

void klang::Envelope::sequence ( )
inlineinherited

Definition at line 5230 of file klang.h.

5230 {
5231 float time = 0.f;
5232 for (Point& point : points) {
5233 const float delta = point.x;
5234 time += delta + 0.00001f;
5235 point.x = time;
5236 }
5237 initialise();
5238 }

◆ set() [1/4]

void klang::ADSR::set ( param attack,
param decay,
param sustain,
param release )
inlineoverride

Definition at line 5439 of file klang.h.

5439 {
5440 A = attack;
5441 D = decay + 0.005f;
5442 S = sustain;
5443 R = release + 0.005f;
5444
5445 points.resize(3);
5446 points[0] = { 0, 0 };
5447 points[1] = { A, 1 };
5448 points[2] = { A + D, S };
5449
5450 initialise();
5451 setLoop(2, 2);
5452 }
void setLoop(int startPoint, int endPoint)
Definition klang.h:5241
param S
Definition klang.h:5433
param D
Definition klang.h:5433
void release(float time=0.f, float level=0.f) override
Definition klang.h:5454
param A
Definition klang.h:5433

◆ set() [2/4]

void klang::Envelope::set ( const Points & point)
inlineinherited

Definition at line 5217 of file klang.h.

5217 {
5218 points.clear();
5219
5220 const Points* pPoint = &point;
5221 while (pPoint) {
5222 points.push_back(*pPoint);
5223 pPoint = pPoint->next;
5224 }
5225
5226 initialise();
5227 }

◆ set() [3/4]

void klang::Envelope::set ( const std::vector< Point > & points)
inlineinherited

Definition at line 5211 of file klang.h.

5211 {
5213 initialise();
5214 }

◆ set() [4/4]

void klang::Envelope::set ( Ramp * ramp)
inlineinherited

Definition at line 5383 of file klang.h.

5383 {
5384 Envelope::ramp = std::shared_ptr<Ramp>(ramp);
5385 initialise();
5386 }

◆ setLoop()

void klang::Envelope::setLoop ( int startPoint,
int endPoint )
inlineinherited

Definition at line 5241 of file klang.h.

5241 {
5242 if (startPoint >= 0 && endPoint < points.size())
5243 loop.set(startPoint, endPoint);
5244 }
void set(int from, int to)
Definition klang.h:5175

◆ setMode()

void klang::Envelope::setMode ( Mode mode)
inlineinherited

Definition at line 5388 of file klang.h.

5388 {
5389 if (mode == Time)
5391 else
5393 }
void setTargetRate(const Point &point, float rate=0.0)
Definition klang.h:5407

◆ setStage()

void klang::Envelope::setStage ( Stage stage)
inlineinherited

Definition at line 5270 of file klang.h.

5270{ this->stage = stage; }

◆ setTarget()

void klang::Envelope::setTarget ( const Point & point,
float time = 0.0 )
inlineinherited

Definition at line 5332 of file klang.h.

5332 {
5333 (this->*setTargetFunction)(point, time);
5334 }

◆ setTargetRate()

void klang::Envelope::setTargetRate ( const Point & point,
float rate = 0.0 )
inlineprotectedinherited

Definition at line 5407 of file klang.h.

5407 {
5408 this->time = 0;
5409 if (point.x == 0) {
5410 ramp->setValue(point.y);
5411 }
5412 else {
5413 ramp->setTarget(point.y);
5414 ramp->setRate(point.x);
5415 }
5416 }

◆ setTargetTime()

void klang::Envelope::setTargetTime ( const Point & point,
float time = 0.0 )
inlineprotectedinherited

Definition at line 5401 of file klang.h.

5401 {
5402 this->time = time;
5403 ramp->setTarget(point.y);
5404 ramp->setRate(abs(point.y - ramp->out) / ((point.x - time) * fs));
5405 }

Member Data Documentation

◆ A

param klang::ADSR::A

Definition at line 5433 of file klang.h.

◆ D

param klang::ADSR::D

Definition at line 5433 of file klang.h.

◆ loop

Loop klang::Envelope::loop
protectedinherited

Definition at line 5419 of file klang.h.

◆ mode

enum klang::ADSR::Mode klang::ADSR::mode = Time

◆ out

Definition at line 2961 of file klang.h.

2961{ 0.f };

◆ point

int klang::Envelope::point
protectedinherited

Definition at line 5421 of file klang.h.

◆ points

std::vector<Point> klang::Envelope::points
protectedinherited

Definition at line 5418 of file klang.h.

◆ R

param klang::ADSR::R

Definition at line 5433 of file klang.h.

◆ ramp

std::shared_ptr<Ramp> klang::Envelope::ramp
protectedinherited

Definition at line 5425 of file klang.h.

◆ S

param klang::ADSR::S

Definition at line 5433 of file klang.h.

◆ setTargetFunction

void(Envelope::* klang::Envelope::setTargetFunction) (const Point &point, float time) = &Envelope::setTargetTime
protectedinherited

Definition at line 5399 of file klang.h.

◆ stage

Stage klang::Envelope::stage
protectedinherited

Definition at line 5423 of file klang.h.

◆ time

float klang::Envelope::time
protectedinherited

Definition at line 5422 of file klang.h.

◆ timeInc

float klang::Envelope::timeInc
protectedinherited

Definition at line 5422 of file klang.h.