ED Shape Envelope 5

Note: This is a complex subject, so please, please read carefully. You will be rewarded with a very versatile Envelope generator module. It’s essential with this module and it’s other associated modules to understand the operation before attempting to use it. This will save a lot of frustration and hassle!
This post will just cover the use of the Shape Editor, and modules used with it:
1) Shape Envelope 5 module.
2) Shape Editor 6 module.

Shape Envelope 5 Help file (edited)

Overview.
1) This is a Multi-purpose Shape-based envelope generator with an optional sustain point setting for versatility.
2) Optional Attack / Release time scaling and Amplitude scaling by keyboard Velocity are also supported.
3) The module can work as both an envelope generator, or alternatively a generic signed pulse generator.
4) A valid Shape must be supplied to the Shape input pin using the appropriate modules.

Operation of the module.
Every time the Gate is turned on, an envelope of the specified shape, interpolation mode and duration in milliseconds (minimum time allowed = 1 mS) is generated and reproduced until a node specified with the Sustain Node parameter is reached, if any Sustain Node is set (Attack/Decay stage); then the Sustain Node level is held at the output (Sustain stage) until the Gate pin turns off, then reproduction of the shape 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 and Unsigned modes.

The default mode (Unsigned) for the envelope generator produces an unsigned signal ranging from 0 to +10 Volts, suitable for use with a VCA as an amplitude envelope.
However, for usage as pitch envelope, filter envelope, pulse generator (or any other purposes you can think of), the Signed option can be enabled in the modules properties, so that a signed envelope (ranging from -10 to +10 Volts) is produced.
Note: For visual consistency, it is advisable to set the Baseline to -5 in the Shape Editor when working in unsigned mode, or 0 Signed mode.

Start and End levels.

You are free to specify a non-zero level for both the first and the last shape nodes, despite the fact that this will naturally lead to discontinuities in operation, or audible clicks, depending on the application.
Keep in mind that the level of the last node will be held at the output as a static voltage when the envelope is over, for logical consistency (i.e. the output will not be forced to return to zero !)
Whenever the first and the last node is required to remain fixed at zero or to another 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 (the last node is not allowed because it would be pointless), there will be NO Sustain stage and a “one-shot” envelope will be produced.

Re-Triggering

Re-triggering refers to triggering the envelope generator before it has come to the natural end of the envelope.
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 level reached, in order to prevent clicks, depending on voice stealing and other polyphonic settings: this choice is automatic.
If a Sustain node is specified, the search for a matching level will not go past this Sustain node, and if no suitable level is found, the envelope level will be stuck to the Sustain node level (after a quick cross-fade), otherwise the Sustain stage could be skipped.
You can set the Retrig Always Resets to always force a position reset on re-trigger in the modules properties panel.
Important note: Please do not set this option when the module works in polyphony, otherwise clicks will occur!

The Gate Off logic.

No Sustain point set:
If no Sustain point is specified, Gate Off events are ignored and the envelope operates in the “one-shot” mode.
Sustain point set:
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 way to the Release stage.
If a Sustain point is specified and a Gate Off event is received before reaching the Sustain point, the envelope behavior may vary depending on the following factors:
1) If the absolute value of the current level is higher than the absolute value of the Sustain level, envelope generation will proceed from the Sustain node after a very quick ramp to the Sustain level, to avoid clicks.
2) If the absolute value of the current level is lower than the absolute value of the sustain level, 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 release remains unchanged
Please note:
Please understand that the gate-off behaviour in Signed mode may not always be optimal, but however, unfortunately a universally good solution probably does not exist.

Clipping of curves.

Important Note: Curve interpolation modes can at times produce values beyond the Overall Level set. Such out of range values can be clipped by the module to prevent problems with other modules by enabling Clip Shape in the modules properties panel.

Attack and Release velocity scaling

The durations of the Attack and Release stages can be scaled independently by using 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 plugs, respectively (the allowed range is 1x to 10x). This means that the harder the keys a depressed the shorter the times become.
Note: 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.
Important: Cheap keyboard controllers usually set Note-Off Velocity to zero or to a bogus value; therefore, it is always better to leave this as an option for the user.
Note: Please remember that velocity value is sampled only at the instant the Gate turns On or Off.

Level Velocity scaling.

The overall envelope level can be scaled by keyboard Velocity by a variable amount, which can be specified with the Level Vel Scal plug.
Note: The velocity value for this purpose is sampled only the very instant that the 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, must be performed after this module.

Position Output.

The Norm Pos output plug constantly outputs the current envelope position as a normalized float value i.e. between 0 and 1. This plug 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.
This is also suitable for polyphonic usage (the position for the newest voice playing will be plotted)

Hint: You can use the Shape Node Selector module to greatly simplify the selection of the Sustain node.

Shape Editor 6 Help File. (Edited)

This is a fully configurable graphical editor for standard ED Shapes using the new efficient binary BLOB transmission format.
Note: The “Legacy” Shape format (string-based, and using Volts values) is still supported to allow for entering Shapes as strings by hand or through the appropriate conversion modules provided for compatibility.
However: The legacy mode usage for shape transmission should now be avoided.

Keeping it simple.
There are also compact, and ultra-compact versions of the module included, which occupy less space in the structure view, by having fewer plugs exposed (most times you may not need to have all the plugs visible for connection anyway).
Stacking shape editors:
More shape editors can be stacked making the background transparent.
In this case, to still allow editing of the background editor (click-thru), the bool option for LockAddRemNodes must be enabled or Editing must be disabled totally for the foremost editor, otherwise any mouse click in empty areas will be intercepted.

Features and usage:

Shapes: Shapes support from two to 100 nodes. A shape can never have less than two nodes. No such thing exists as an “empty” shape: a “void” or default shape is a shape with just the first and the last node set to zero.
Nodes: What are these node things? They are points that you specify to define the shape, set within an X-Y axis. The values define the positions of the points defining the curves.
Node values: Node values are internally represented in normalized float units: Vertically from 0 to, and including 1.
Horizontally, from -1 to, and including 1.
Compatibility: However, for compatibility reasons, node positions are still displayed, and accepted in Volts by all the ED Shape modules:
Horizontally from -5 to +5 Volts.
Vertically from -5 to +5 Volts.
First and last nodes: The first and the last node are fixed at the positions -5 and +5 and cannot be moved horizontally. This is intentional and not a bug.

“Legacy” string format:

The legacy format consists of a series of nodes defined between parentheses in Volt units, e.g. (-5,0)(1,-1)(5,1).
Legacy First and Last nodes: The first and the last node must always be present, and have the positions -5 and 5 respectively, and they must all be sequential. Vertical positions: The vertical node positions must be in the -5 to 5 range.
No other characters or spaces are permitted. Invalid strings will be rejected.
(This format was inherited from the stock SynthEdit WaveShaper 3)

New BLOB shape format:

Shape information is now stored and transmitted using a new efficient binary BLOB format (Binary Large OBject if you like your acronyms).
Every Shape Editor must therefore be linked to the destination user module(s) via a Patch Memory Blob module. (Diagram below)

Adding and removing shape nodes.
Shape nodes can be added or removed by a double-click.
New nodes: A double click anywhere in and empty space in the editing field will create a new node at the corresponding mouse position.
Removing Nodes: Double-clicking on a selected node will delete
it (unless deletion is disabled, see later).
The first and last nodes cannot be deleted: a double click on a node which can’t be deleted will snap it to the specified baseline for convenience.
Moving Nodes: Shape nodes can be selected with a mouse click and dragged around within their allowed limits:
1) Between the neighboring nodes, and
2) Vertically within -5 and 5 or within a smaller range, in case of a custom range of MinY/MaxY values being specified.
Interpolation: Interpolation Type is still transmitted separately from Shape data. Since different Shape-utilizing modules may support only certain Interpolation Types or even just one, their DSP List pin is always properly set to back-transmit this information to the main Patch Memory List, whose Value plug must be connected to the corresponding Shape Editor plug, and which will be automatically configured to only list the supported mode(s). The connection method is shown below in use with the ED Shape Envelope module. (Ultra Compact module shown for simplicity)

Important note: Users must never make any assumptions about the list position of Interpolation Types and their corresponding integer values, since they might change in the future and/or more Types could be added upon need.

Plugs and Parameters

<->Shape I/O: The input-output Plug for the BLOB description on the shape.

<->Interpolation Choice In: Specifies how the Shape is to be interpolated always use the connection method shown with a Patch Memory List Module!
Shape Interpolation Types:
None : This mode does not correspond to any physical interpolation and is module-specific. It really means that a module actually only needs node positions (e.g. to render spectral peaks or sinc pulses …) and not represent an actual curve. The Shape Editor will simply draw vertical lines starting from the specified baseline. In general, this option can be useful to have a Shape representing just a set of points.
Important: Not all modules support ” None”.
Note: when the Interpolation Type is set to None, the nodes can slide freely beyond the adjacent ones for convenience.
Linear:
This plain linear interpolation (default). This results in a straight line, and no smoothing at all.
Curve 1:
Equivalent to the former “Spline” method, this method uses modified cubic splines for smoothing.
Notes: This is a Curve interpolation which will never fluctuate but can still result in unsmoothed transitions from intervals of very different width, however it still produces a very smooth result (almost comparable to Curve 2) when used with uniformly spaced nodes.
Curve 2:
Natural cubic splines. This Interpolation method always produces a smooth curve (second derivative is always continuous) at the expense of sometimes producing huge fluctuations, when used on node intervals much smaller than their neighbouring node spacings.
Edit X, Edit Y Plugs: A pair of Float editing pins is linked to the currently active node, so that its x,y values can be displayed and sent to the module if needed, by connecting a couple of suitable modules.
Note: The old left hand side edit pins have now been removed, to prevent undue connection of Patch Memories which would result in conflicting double storage.

<->Active Node I/O: The index of the active node, as available at the Active Node plug, is not internally stored in any parameter. To maintain it throughout sessions, you must connect it to a Patch Memory Int module. This can be output, or alternatively supplied as a value to select a particular node when working with a fixed number of nodes (obviously).
Note: when Interpolation Type is set to None, nodes are free to slide beyond
any adjacent ones. For this reason, the Active Node index can change while sliding
a node horizontally.

->Editable: The editor can be set to read-only mode (all editing is fully disabled, this is useful for parameter display purposes)

->Lock X: The Horizontal position of all the nodes nodes can be locked, restricting the the user to editing their vertical positions.

->Lock Add/Rem Nodes: Addition and removal of nodes can be disabled, to restrict working to a fixed number of nodes.

->Lock First/Last Nodes: Editing for the first and last node can be disabled, this prevents users adding values that could cause loud clicks.

->Y Max/Y Min: Values supplied to these plugs set range for vertical positions and limited them within a minimum and a maximum range.

->Base Line: The vertical position of a convenient reference baseline can be specified (it is zero by default).
Notes on the Baseline:
1) Shape fill gradients will be drawn originating from the specified baseline.
2) Double clicking on a node which cannot be deleted (like the first and the last node, or all nodes when addition/removal is disabled) will cause the node to be snapped to the specified baseline.
3) When no default shape is specified in the Reset Value pin, a two-node straight line shape at the baseline will be used as the default.
For example, when the shape represents positive values, it makes sense to place the baseline at the bottom (-5), and when the shape represents a spectral filtering curve, it may be more logical to set the baseline at top (+5), again when it represents signed values, the baseline is more logically
placed in center (zero) position.

->Reset Value: Specify a shape in the legacy string format to use as default value for the Reset plug. If no shape is specified (empty plug string), a straight two-points shape (line) at the specified baseline will be used as default

->Mouse Down Has the value 1 (True) when the user clicks on the editor screen area

-> Node Size: Size of the Node handles in Pixels. The size range is from 4 to 20px.

->Node Thickness: The thickness in pixels of empty node handles, from 1 to 4 px

->Circular Nodes: When set to True draws circular node handles rather than square.

->Fill Nodes (I) : When set to true draws filled node handles rather than empty.

->Shape Thickness: Sets the thickness in pixels of the shape curve, from 1 to 4px.

->Border % Sets the percentage of border area, expressed as a percentage of every dimension, from 0 to 25.
Example: If the setting is 25, then the left and right borders will both use one 25% of the box width, and the top and bottom borders will both use 25% of the box height.

->Border Clip: When this plug is set to True it clips parts of the interpolated shape which may result in values larger than +5 or smaller than -5 (usually because of curve interpolation) from being drawn in the border area, and replaces them with a clipping line.
Note: Most shape-utilizing modules doe not clip values internally. But when they do, this is always clearly specified. Therefore, always set this pin
in a consistent way, since a clipping line in the editor can be misleading

->Grid Horiz Divs: This plug sets the number of horizontal (X) grid divisions.
from 0 to 40

->Grid Vert Divs: This plug sets the number of vertical (Y) grid divisions.
from 0 to 40

These Plugs are on the RHS
->Edit X: A float pin linked to the currently active node, to read or change its
horizontal value externally.

->Edit Y: A float pin linked to the currently active node, to read or change its
vertical value externally.

->Reset: When set to true the module reverts to the default shape specified in the Reset Value plug. If no default shape is specified (empty plug value), a straight two-nodes shape (line) at the specified baseline will be used as default for convenience.

->Flip X: When set to true the current shape is flipped horizontally.

->Flip Y: When set to true the current shape is flipped horizontally.

Internal (Properties panel) settings:
>Edit Units: You can specify whether to use Volts (“legacy”, default), or native Float units for the two Edit plugs.
Important: Please remember that the Volts range is [-5,+5] in both X and Y axis, while Float range is [0,1] X and [-1,+1] Y.

ARGB Colours: 32 bits color (i.e. including alpha channel) can be specified for every graphical element of the editor as a 32 bits Hex string (e.g 80FFFF00 is a 50% transparent yellow), allowing customization of the colours and transparencies. Note: When the alpha channel (first byte) is set to zero, the corresponding foreground element won’t be drawn at all. In case of the Background, setting an alpha channel smaller than FF will progressively reveal other GUI controls placed in the background in the Panel view.
The ARGB Colours that can be set are:
BG Top
BG Bottom
Grid
Base Line The defined horizontal base line/Axis
Vert Line The centre vertical axis
Shape – The line drawn defining the shape.
Fill Grad 1 Fill grad is easier to show-
Fill Grad 2
Nodes
Active Node

Example – In the image below:
Base Line is set to FFFFFF00 (100% Red, 100% Green)
Vert Line is set to FF00FFFF (100% Green, 100% Blue
Fill Grad 1 is set to FF00FF00 (100% Green)
Fill Grad 2 is set to FF0000FF (100% Blue)
Shape is set to FFFF0000 (100% Red)

Using the CTRL key supports precise movements
Note: With SE 1.4 the CTRL precision mode does not work in the Structure View.