diff --git a/flow/flow_doc.md b/flow/flow_doc.md index f9e0922..302a14d 100644 --- a/flow/flow_doc.md +++ b/flow/flow_doc.md @@ -1,6 +1,142 @@ + +## Proc Class Notation + +``` + : { + vars: { (:)* }, + presets: { (:)* }, + poly_limit_cnt: + } + + -> { type:, value:, doc:, flags:[ ] } + + -> { : } + + -> | NUMBER | STRING | CFG + + -> [ (value-literal)* ] + + +``` + +### Applying class presets during proc instantiaion + +The way class preset values get applied is a function of the type of the variable and the format of the value. +If a variable is not a _cfg_ type and the preset value is a list, or if the variable is a _cfg_ type +and the preset value is a list-of-containers then each each value in the list is assigned to successive +channels on the variable. This is shown as the __multi-chan__ algorithm in the table below. +In all other cases the the value is applied to the 'any' channel, which is applied to +all existing channels. + +| cfg | list | LoC | chan | algorithm | +| ----------- | ------- | --------------- | ---- | ---------------------------------------------- | +| no | no | no | any | single-chan | +| no | no | yes | n/a | Value can't be an l-of-c w/o also being a list.| +| no | yes | no | N | multi-chan | +| no | yes | yes | N | multi-chan | +| yes | no | no | any | single-chan | +| yes | no | yes | n/a | Value can't be an l-of-c w/o also being a list.| +| yes | yes | no | any | single-chan | +| yes | yes | yes | N | multi-chan | + +When the class preset is applied during proc instantiation all variables have +been instantiated with the base channel. This implies that the __single-chan__ +algorithm is only setting the value of the the existig base channel. +The __multi-chan__ algorithm however will instantiate any channels above the base channel +that do not already exist by duplicating the base channel and then assigning the preset value. + + +### Notes + +1. Legal `` values + +type | Description +---------|------------------------------------------------------------------------------------------------------------------- +string | +bool | `true` or `false` +int | `int32_t` +uint | `uint32_t`. The literal value must be suffixed with a 'u'. [See JSON Notes](#json-notes) +float | Single precision float. The literal value must be suffixed with an 'f'. [See JSON Notes](#json-notes) +double | Double precision float +cfg | JSON string +audio | +spectrum | +midi | +srate | (float) Sample rate type +sample | (float) Audio sample type +coeff | (float) Value that will be directly applied to a sample value (e.g added or multiplied) +ftime | (double) Fractional seconds +runtime | The type is left up to the processors custom 'create' function. These variables are not created automatically + | prior to calling the proc custom function. +all | +numeric | + + +See list in cwFlowTypes.cpp : typeLabelFlagsA[] + + +2. Attribute labels indicate properties of this variable. + +Attribute | Description +----------|-------------------------------------------------------------- +`src` | This variable must have a value or be connected to a source or + | the proc cannot be instantiated, and therefore the network cannot be instantiated. +`src_opt` | +`no_src` | This variable cannot be connected to a 'source' variable. Variables that are + | only used as output usually have this property. +`init` | This is an an initialization only variable. + | Changing the value during runtime will have no effect. +`mult` | This variable may be instantiated multiple times by the in-statement. + | Variables that do not have this property may only be instantiated + | once per proc-instance. +`out` | This is a subnet output variable. [See Subnet Implementation](#subnet-implementation) +`no_chan` | This variable cannot be 'channelized'. + +## Schema Notation + +1. The schemas all describe JSON like structures. For clarity the dictionary braces and +list brackets are shown. + +2. Variables are wrapped in `< >` markers. + +3. Entitities wrapped in `( )*` indicate that the wrapped structure may be repeated 0 or more times. +Entitities wrapped in `( )+` may be repeated 1 or more times. + +4. Variables with names ending in `label` indicate identifiers which are unique at least within +their local scope and possibly some greater scope. For example proc-class names must be +unique across all loaded proc-class modules. + +5. `` indicates arbitrary text. + +6. Entities are often optional. Rather than clutter the notation with additional +mark-up to indicate optional entitities this information is inclued in the notes +that accompany each schema. + + + + + +## JSON Notes + +The 'cfg' language is a JSON like with some added features: + +1. Comments can be inserted using C++ `\\` line comment and `\* *\` block comment syntax. + +2. Quotes are not necessary around strings that have no internal whitespace. + +3. Numeric literals without decimal places are interpretted as integers, numbers +with decimal places are interpretted as doubles. Unsigned and single precision float values +may be specified using suffix notation + +Type | Suffix | Example +---------|----------|-------------- +unsigned | u | 10u +float | f | 12.34f + + # Flow Documentation: _flow_ is an experimental audio processing framework which supports @@ -42,10 +178,17 @@ Use `$` prefix to a filename. Use proc_expand_filename() to prepend `proj_dir` t ### Network with sub-nets. + +## Proc Class Descriptions + +``` +``` + + ## Proc Instance Syntax: ``` -