FoaMatrixChain
Extension
ExtensionDescription
A utility to chain multiple FoaXformerMatrix transforms. While it can be used as a standalone utility, it was primarily designed for internal use by FoaXformDisplay.
Transform Chain Structure
An FoaMatrixChain generates a node structure of transforms in both series and parallel. Parallel chains can tap "outputs" from nodes in other chains. The final output (retrieved with -curXformMatrix) is always the last transform node of the last chain. However the resultant matrix at each node in the chain is also stored.
An FoaMatrixChain may actually be composed of multiple "chains" of transforms in parallel. By default, each node in the chain reads in the matrix from the previous transform, or the last transform of the previous chain in the case of a new parallel chain. The first node in a chain can optionally read in any previous node in the tree, and some transforms can also read a previous node into its input. For example in the add transform takes a previous node as an argument to be added to its input matrix. This structure will become apparent when using the interface provided with FoaXformDisplay.
Many of the instance methods have arguments asking whichChain followed by an index. This refers to which parallel chain (a zero-based index), followed by the index of the node (transform) within that chain. For example if you have three parallel chains, and you want to specify the second node position in the last parallel chain, then whichChan: 2, index: 1.
Class Methods
.new
Arguments:
| verbose |
A Boolean specifying whether the transform chain is posted whenever a transform is changed, added or removed. |
Instance Methods
.addTransform
Insert a transform into the chain.
Arguments:
| xformName |
A Symbol corresponding to the transform's name, as listed by key in |
| whichChain |
A chain index, zero-based. |
| index |
A index in the chain specified by whichChain. |
| ... params |
Initial parameters to supply the transform, in the order they are listed in the controls, which can be viewed with, for example, |
.removeTransform
Remove a transform from the chain.
Arguments:
| whichChain |
Which chain index. |
| index |
Index of the transform in the specified chain. |
.replaceTransform
Similar to addTransform, but rather than inserting, it replaces the transform at the specified chain/index location.
.setParam
Set a parameter of one of the transforms in the chain(s).
Arguments:
| whichChain |
A chain index, zero-based. |
| index |
A index in the chain specified by whichChain. |
| ctlDex |
The index of the parameter in the |
| value |
The new value for the transform parameter. |
.addChain
Add a parallel processing chain. The default head of the chain will be the tail of the preceeding chain.
Arguments:
| index |
Index at which to insert the new chain. |
.removeChain
Remove one of the parallel processing chains at index. Note that any transform inputs reading from nodes in this chain will be reset to 'A0', the orginal unaffected input soundfield.
.chainXForms
Perform the calculation of "chaining" all the transforms together. This should be called after any alteration to the transform chain, which will in turn update the -curXformMatrix variable.
.curXformMatrix
Get the resultant transform from the chain.
.chains
Returns:
A 2D Array of FoaMatrixChainLinks whose state can be queried to return it's transform name, control parameter values, and resultant matrix up to that point in the chain, by .name, .controlStates, and .mtx, repsectively.
.reset
Reset the processing chain, starting over from an unaffected input soundfield.
.clear
Same as reset.
.verbose
A Boolean specifying whether the transform chain is posted whenever a transform is changed, added or removed.
.postChain
Post the current processing chains, with the transform names and parameters formatted to view easily.
.getLinkByKey
Get a transform "link" in the chain by its alpha-numeric key.
Arguments:
| key |
An alpha-numeric key, e.g. |
Returns:
A FoaMatrixChainLink whose state can be queried to return it's transform name, control parameter values, and resultant matrix up to that point in the chain, by .name, .controlStates, and .mtx, repsectively.
.xFormDict
Returns:
A Dictionary containing specifications for all of the valid transforms and their controls.