

SHAPE EDITOR
------------

Fully configurable graphical editor for standard ED Shapes using the new efficient binary BLOB transmission format.

"Legacy" Shape format (string-based and using Volts values) is still supported for entering Shapes as strings by hand or thru the apposite conversion modules provided for compatibility but ITS USAGE FOR SHAPE TRANSMISSION IS NOW DISCOURAGED.

A compact and an ultra-compact version are also included, which occupy less space in the structure view, by having less and less pins exposed (most times you may not need to have all pins exposed for connection, if not in some rare occasions).

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 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/USAGE:


-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.

-Node values internally are represented in normalized float units: from 0 to and including one
 horizontally, from -1 to and including 1 vertically. However, for compatibility reasons, node
 positions are still displayed and accepted in Volts by all ED Shape modules: from -5 to 5 Volts
 horizontally, from -5 to 5 Volts vertically.

-The first and the last node are fixed at position -5 and +5 and cannot be moved horizontally

-"Legacy" string format consists of nodes between parentheses in Volt units, e.g (-5,0)(1,-1)(5,1).
 The first and the last node shall always be present, and their horizontal position shall always
 be -5 and 5 respectively, and they must all be sequential. Vertical positions must be in -5 to
 5 range. No other characters or spaces shall be present. Invalid strings will be rejected.
 (This format was inherited from the stock SynthEdit WaveShaper 3)

-Shape information is now stored and transmitted using a new efficient binary BLOB format.
 Every Shape Editor shall therefore be linked to the destination user module(s) thru a Patch Memory
 Blob module

-Shape nodes can be added or removed by a double-click. A double click anywhere in the edit field will
 create a new node at the corresponding mouse position. Double-clicking on a selected node will delete
 it (unless deletion is disabled, see later). The first and last node cannot be deleted: a double click
 on a node which can't be deleted will snap it to the specified baseline for convenience.

-Shape nodes can be activated with a mouse click and dragged around within their allowed limits:
 between the neighboring nodes, and vertically within -5 and 5 or within a smaller range, in case
 custom MinY/MaxY values are specified

-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 Menu Selection
 pin shall be connected to the corresponding Shape Editor pin, and which will be automatically
 configured to only list the supported mode(s).
 Users shall *never make any assumptions* about the list position of Interpolation Types and their
 integer values, since they might change in the future and/or more Types could be added upon need.

 None (0): this mode does not correspond to a physical interpolation and is module-specific. It pretty
           means that a module actually only needs node positions (e.g to render spectral peaks or sinc
           pulses ...) and not 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.

	   NOTE: when Interpolation Type is set to None, nodes can be slided freely beyond the
	   adjacent ones for convenience.

 Linear (10): plain linear interpolation (default)

 Curve 1 (20): equivalent to the former "Spline" method, uses modified cubic splines.
          Curve interpolation which will never fluctuate but can result non smooth in transitions
	  from intervals of very different width.
          Still produces a very smooth result (comparable to Curve 2) with uniformly spaced nodes

 Curve 2 (30): natural cubic splines. Produces an always smooth curve interpolation (second derivative
         is always continuous) at the expense of even huge fluctuations, close to intervals much
         smaller than their neighbouring ones

-A pair of Float editing pins is linked to the currently active node, so that its x,y value can be
 displayed and entered by hand if needed, by connecting a couple of Text Entry or other suitable
 modules. The left edit pins have now been removed, to prevent undue connection of Patch Memories
 with resulting conflicting double storage.

-The index of the active node, as available to the Active Node pin, is NOT internally stored in any
 parameter. To maintain it thru sessions, please connect it to a Patch Memory Int

-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
 and transparencies. When the alpha channel (first byte) is set to zero, the corresponding 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 background in the Panel view.

-The editor can be set to read-only mode (editing disabled, useful for displaying purposes)

-Addition/removal of nodes can be disabled, to force working with a fixed number of nodes

-Editing for the first and last node can be disabled

-Horizontal position of nodes can be locked, allowing the user to edit just their vertical positions

-Edit range for vertical positions can be limited within a minimum and a maximum

-Nodes can be displayed as either squares or circles, either filled or empty, and their size and
 thickness can be specified

-Border size can be specified as a percentage of the total box size

-Shape thickness, color and gradient fill colors can be specified freely

-The vertical position of a convenient reference baseline can be specifed freely (zero by default).
 Shape fill gradients will be drawn originating from the specified baseline.
 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.
 When no default shape is specified in the Reset Value pin, a two-nodes straight line shape at the
 baseline will be used.
 For example, when the shape represents positive values, it makes sense to place the baseline
 at the bottom (-5); when the shape represents a spectral filtering curve, it may be more logical
 to set the baseline at top (+5);  when it represents signed values, the baseline is more logically
 placed in center (zero)

-The number of both horizontal and vertical grid divisions can be specified freely

-Builtin shape flip function, horizontal and vertical

-Builtin reset function, sparing the usage of an external Trigger module

-CTRL key support for precise movements (NOTE: with SE 1.4, CTRL does not work in Structure View)





DETAILED PIN DESCRIPTION:



<Functional Left Pins>

Shape I/O (I/O) - BLOB line for transmitting/receiving shapes. Everytime the current shape is modified
                  an updated Shape is transmitted from the Shape I/O pin. Everytime a new shape is
                  received, the editor will be updated immediately accordingly

Interpolation Choice (I) - interpolation type for the displayed shape. Always connect the Choice pin of
                           a Patch Memory List to this pin, whose DSP List output shall be connected
                           to the final Shape-utilizing module, for the available modes to appear in
		           a List Entry module connected in parallel.
                           Whenever the Interpolation Type must be fixed and not user-selectable,
                           simply avoid to connect any List Entry to the Patch Memory List and select
                           the desired Interpolation Type from the Properties panel for the Patch
	                   Memory List
               
Active Node (I/O) - index of the currently active node, or -1 if no node is selected.
                    Its value can be cached thru sessions by connecting a Patch Memory Int.
		    NOTE: when Interpolation Type is set to None, nodes are free to slide beyond
		    the adjacent ones. For this reason, the Active Node index can change while sliding
		    a node horizontally.

Editable (I) - disable this pin to prevent editing (read-only mode)

Lock X (I) - enable this pin to prevent editing the horizontal node positions.
             This also prevents horizontal positions to be changed with the EditX pin

Lock Add/Rem Nodes (I) - enable this pin to prevent deletion or addition of new nodes

Lock First/Last Node (I) - enable this pin to prevent editing of the first and last node

YMin, YMax (I) - limits editing of vertical nodes position within a custom range (default -5,5).
                 This limit will also affect vertical node positions entered with the EditY pin
                 and the vertical position of new nodes added.
                 NOTE: set this value consistently; a double-click on a node, when deletion is
		 disabled, will snap it to the baseline value no matter which the Y constrains
		 set !

Base Line (I) - position of the vertical reference baseline.

Reset Value (I) - specify a shape in Legacy string format to use as default value for the Reset pin.
                  If no shape is specified (empty pin), a straight two-points shape (line) at
                  the specified baseline will be used as default

Edit Units (I) - specify whether to use Volts ("legacy", default) or native Float units for
                 the two Edit pins. Keep in mind that Volts range is [-5,+5] in both
                 dimensions, while Float range is [0,1] horizontally and [-1,+1] vertically

Mouse Down (O) - becomes active when the user clicks on the editor

Hint (I) - specify here the bubble help text as usual




<Functional Right Pins>

Edit X, Edit Y (I/O) - pair of float pins linked to the currently active node, to read or insert its
                       horizontal and vertical value externally

Reset (I) - sets the default shape specified in the Reset Value pin. If no default shape is
            specified (empty pin), a straight two-nodes shape (line) at the specified
            baseline will be used as default for convenience

Flip X, Flip Y (I) - flips the current shape horizontally or vertically




<Cosmetic pins>

Node Size (I) - size in pixels of node handles, from 4 to 20

Node Thickness (I) - thickness in pixels of empty node handles, from 1 to 4

Circular Nodes (I) - draw circular node handles vs. squared

Fill Nodes (I) - draw filled node handles vs. empty

Shape Thickness (I) - thickness in pixels of the shape curve, from 1 to 4

Border % (I) - percentage of border area, expressed as a percentage of every dimension, from
               0 to 25 (e.g setting 25, left and right borders will result each one 1/4 of
	       the box width, and top and bottom borders will result each one 1/4 of the box heignt)

Border Clip (I) - setting this pin prevents parts of the interpolated shape which may result
                  larger than +5 or smaller than -5 (mostly because of curve interpolation)
                  being drawn in the border area, and replaces them by a clipping line.
                  NOTE: most shape-utilizing modules are NOT clipping values internally, and
		  however when they do, this is clearly specified. Therefore, always set this pin
		  in a consistent way, since a clipping line in the editor can be misleading

Grid Horiz Divs, Grid Vert Divs (I) - set the number of horizontal and vertical grid divisions
                                      from 0 to 40

#? ARGB (I) - specify the Alpha, Red, Green, Blue color components of the respective graphic
              elements, as standard 32 bits hexadecimal ARGB strings (e.g 80FF00FF is a half-
              transparent magenta)

















