

SHAPE ENVELOPE 5
--------------------------------------------------------------------------------------

Multi-purpose Shape-based envelope generator with optional sustain point.

Optional Attack / Release time scaling and Amplitude scaling by keyboard Velocity are also supported.

Can work as both envelope generator or generic signed pulse generator.

A valid Shape shall be supplied to the Shape input pin.

Every time the Gate is turned on, an envelope of the specified shape, interpolation mode and duration in milliseconds (min allowed: 1 mS) is generated and reproduced until a node specified with the Sustain Node parameter is reached, if any (Attack stage); the Sustain Node level is held at the output (Sustain stage) until the Gate pin turns off, then reproduction is resumed from the remaining part of the envelope shape until its natural end (Release stage).

When no sustain node is specified, the envelope generator works in "one-shot" mode.


SIGNED MODE
-----------
By default, the envelope generator produces an unsigned signal ranging from 0 to +10 Volts, for shape levels ranging from -5 to +5, suitable as amplitude envelope. However, for usage as pitch envelope, filter envelope, pulse generator or other purposes, the hidden Signed pin can be enabled, so that a signed envelope (from -10 to +10 Volts) is produced.
For visual consistency, it is advisable to set the Baseline to -5 in the Shape Editor when working in unsigned mode, or 0 otherwise.


START AND END LEVELS
--------------------
You are free to specify a non-zero level for both the first and the last shape nodes, despite this will naturally lead to discontinuities or clicks, depending on the application. Keep in mind that the level of the last node will be held at the output as static voltage when the envelope is over, for logical consistency (i.e output will NOT be forced to zero !)
Whenever the first and the last node should remain fixed at zero or to another identical level, you should fix their position with "Lock First/Last nodes" option in the Shape Editor, to prevent editing.


SUSTAIN NODE
------------
If the specified Sustain Node index is negative or larger than the number of current shape nodes minus one (last node not allowed because pointless), there will be no Sustain stage and an "one-shot" envelope will be produced.
 

RE-TRIGGERING
-------------
Re-triggering refers to triggering the envelope generator before it has come to its natural end.

When this module is used in a polyphonic circuit, the envelope can either be fully retriggered (position reset to zero) or resumed from the first point whose level is the same as the current reached level, in order to prevent clicks, depending on voice stealing and other polyphonic settings: this choice is automatical.
In case a Sustain node is specified, the search for a matching level won't go past the Sustain node, and if no suitable level is found, the envelope will be stuck to the Sustain node (after a quick cross-fade), otherwise the Sustain stage could be skipped.

You can set the hidden Retrig Always Resets pin to always force a position reset on re-trigger. Please do NOT set this option when the module works in polyphony, otherwise clicks will occur !


GATE-OFF LOGIC
--------------
Is no Sustain point is specified, Gate OFF events are ignored and the envelope operates in "one-shot" mode.

If a Sustain point is specified and the envelope generation has reached it already, a Gate OFF event will resume envelope generation from the Sustain point all the ways to the end (Release stage).

If a Sustain point is specified and a Gate OFF event is received before reaching such point, the envelope behavior may vary depending on the following factors.

-If the (absolute of) current level is higher than the (absolute of) Sustain level, envelope generation will proceed from the Sustain node after a very quick ramp to Sustain level, to avoid clicks.
-If the (absolute of) current level is lower instead, the envelope will proceed from the Sustain point scaling and shifting the Release stage, so that the Sustain level matches the current level, while the end level remains unchanged.

Please understand that the gate-off behaviour in Signed mode may not always be optimal, but an universally good solution likely does not exist.


CLIPPING
--------
Curve interpolation modes can produce values beyond the Overall Level set. Such values can be clipped by enabling the hidden Clip Shape pin.


ATTACK AND RELEASE VELOCITY SCALING
-----------------------------------
Durations of Attack and Release stages can be scaled independently by keyboard Velocity. A Velocity value from 0 to 10 V will cause a gradual shortening of the duration specified up to a maximum scaling factor specified with the Attack Vel Scal and Release Vel Scal pins, respectively (allowed range is 1x to 10x). When no Sustain node is specified, the whole envelope is considered an Attack stage and the Release Vel Scal value is ignored.
This is especially useful with some sounds like violins, to easily control the attack and release time with your keyboard's note-on and note-off velocity, for realistic performance.
Note: to properly scale the Release stage, your MIDI controller must transmit a valid Note-Off Velocity value (cheap controllers usually set Note-Off Velocity to zero or to a bogus value; therefore, it is always better to leave this as an option).
Note: velocity value is sampled only the very instant Gate turns ON or OFF.


LEVEL VELOCITY SCALING
----------------------
The envelope level can be scaled by keyboard Velocity by a variable amount, which can be specified with the Level Vel Scaling pin.
Note: velocity value for this purpose is sampled only the very instant Gate turns ON or a note switch on a same voice occurs. Any further changes or modulations will be ignored. LFO (tremolo) or Aftertouch level modulations, if required, shall be performed downstream.


POSITION OUTPUT
---------------
The Norm Pos output pin constantly outputs the current envelope position as a normalized float value (i.e in [0,1]). This pin together with a Patch Memory Float Out can be used for visual feedback, i.e to drive a vertical moving line overlaid on the Shape Editor. Also suitable for polyphonic usage (the position for the newest voice playing will be plotted)


->HINT: you can conveniently use the Shape Node Selector module to simplify the selection of Sustain node.

->Please consult the Shape Editor documentation for further details about using standard Shapes.


