matrix 4.0 enhancements

data flow re-router | advanced features

New matrix v4.0 features:

Integrates with matrixctrl
Includes spray feature

new clear message

new LR message

Implementation of matrixctrl

matrixctrl connects almost directly with matrix. Almost, because it needs a [prepend mc] or [prepend mcx n] object between matrixctrl and matrix. This is necessary because matrix uses lists to tag the inlets for its own configuration.

The mc and mcx messages also provides a way to tell matrix which of two orientations you want matrixctrl to effect matrix.

matrix feeds back into matrixctrl (through a connection you make between matrix's control outlet and matrixctrl's left inlet), so any changes made through matrix's command set will update matrixctrl. In this way, you could use matrixctrl simply as a visual representation of the matrix configuration. This can also be handy if you want to control something other than matrix with matrixctrl, but use matrix's configuration commands.

One thing to keep in mind when using matrix with matrixctrl: matrixctrl uses index values to reference columns and rows; by default, matrix uses ordinal numbers to reference inlets and outlets (matrix was modeled after switch and gate). When these two objects are connected together this difference is seamless because matrix translates configuration data between the two objects. However, if you are using direct references to these objects concurrently, this factor must be considered. You can change matrix references to match matrixctrl by sending matrix an <ioref 0> messages.

Orientation

There are two orientations between matrixctrl and matrix.

Columns represent matrix inlets and rows as matrix outlets
Rows as inlets and columns as outlets.

The default orientation is columns as inlets.

[mctop] tells matrix to interpret matrixctrl columns as matrix inlets, and rows as outlets. Since it is the default configuration, it is not necessary to send it an initial [mctop] message before using the matrix configuration commands. [mcleft] tells matrix to interpret matrixctrl rows as matrix inlets, and columns as outlets. The initial set of commands begins by telling matrix that matrixctrl is oriented with rows as inlets and columns as outlets.

The exampe above is obsolete but still possible. The [prepend mctop/mcleft] object should use [prepend mc] instead. However, before configuring matrix or matrixctrl, send the matrix a [mcleft] message once as shown on the right ([mctop] may be used in the left example, but matrix defaults to this orientation).

[configOnChg 1] tells matrix to send configuration streams out the control outlet whenever its configuration is changed by one of its own commands, thereby updating matrixctrl. (In this case [configOnChg] without the arg has the same effect

[1, = 2 4 8] is two messages. The first tells matrix that subsequent configuration commands will affect inlet 1. The second tells matrix to open outlets 2, 4, and 8 only for that inlet.

[2, 3 5 7] tells matrix to open only outlets 3, 5, and 7 for inlet 2.

The simplest way to set up matrix with matrixctrl is to:

create the two objects
create a [prepend mc] object.
connect the objects according to the example above.
send matrix a [configOnChg] message.

You may use either matrixctrl or matrix's built-in command messages to configure matrix. Matrixctrl will reflect any changes made to matrix if you use matrix's commands.

Matrixctrl as a window into matrix

matrixctrl does not need to be the full size of matrix. By using the mcoffset and mcdim message you can move matrixctrl around the matrix.

There are several new messages related to the integration of matrix with matrixctrl:

	configOnChg arg1 [list]	This message takes one argument: 0 or 1. `[configOnChg 1]` tells matrix to output configuration changes when it receives one of its own configuration messages. If this is off (0), matrix will not update matrixctrl unless you send matrix a `getconfig` message. Turning it off is useful if you need to use matrix's configuration commands in rapid succession and are concerned with CPU efficiency. When using multiple matrixctrls the list refers to the addittional controllers.
	getconfig	This tells matrix to output its current configuration. If you reconfigure matrix or matrixctrl while `configOnChg` is disabled, and need to update matrixctrl, send matrix `getconfig`.
	(if mctop orientation) mc [arg1 arg2 arg3 ...]	`mctop` takes the three arguments output by the left outlet of matrixctrl and tells matrix to interpret them as: arg1: on/off (0 or 1) arg2: column (h) = inlet arg3: row (v) = outlet ... additional matrixctrl style arguments in groups of three as: on/off, h, v NB: This is the default orientation.
	(if mcleft orientation) mcleft arg1 arg2 arg3	mc takes the three arguments output by the left outlet of matrixctrl and tells matrix to interpret them as: arg1: on/off (0 or 1) arg2: row (v) = inlet arg3: column (h) = outlet ... additional matrixctrl style arguments in groups of three as: on/off, v, h If you are using this orientation, you must send matrix an mcleft message (with or without arguments) before doing any configuration of matrix. This tells matrix that this orientation is in effect. You can also click matrixctrl to open and close a cell. Once matrix receives any mcleft message it will know the orientation. It will need this before you configure matrix with its own commands if you expect matrix to update matrixctrl correctly.
	mcdim arg1 arg2 arg3 arg4	If matrixctrl does not cover the entire matrix, use `mcoffset` or `mcdim` to tell matrix what part of the matrix this matrixctrl covers. arg1 is the inlet size of matrixctrl arg2 is the outlet size of matrixctrl arg3 is the inlet offset. arg4 is the outlet offset. `mcdim` is used if you have a large matrix that you want to control with a small matrixctrl. You can use matrixctrl as a moveable window inside the matrix. The first two arguments represent the size of matrixctrl. When initiated, matrix assumes that matrixctrl is the same size as matrix. If this is not the case (which is why you are now using mcdim), then matrix needs to be told the dimensions of matrixctrl. The dimensions are in accordance with matrix, not matrixctrl. The first argument (arg1 of mcdim) is the number of matrix inlets matrixctrl covers; the second (arg2), the outlets.
		The second two arguments tell matrix where the first virtual matrixctrl cell is within matrix (top-left for `mctop`, bottom-left for `mcleft` orientation). The arguments correspond to matrixctrl's index values, not matrix ordinal values. Thus, the default offset is 0, 0. The first argument is the inlet and the second the outlet. This is the case no matter how matrixctrl is oriented.
	mcoffset arg1 arg2 arg3 arg4	You can also use `mcoffset` instead of `mcdim` to tell matrix what part of the matrix this matrixctrl covers. arg1 is the inlet offset. arg2 is the outlet offset arg3 is the inlet size of matrixctrl arg4 is the outlet size of matrixctrl `mcoffset` is used if you have a large matrix that you want to control with a small matrixctrl. You can use matrixctrl as a moveable window inside the matrix. The first two arguments tell matrix where the first virtual matrixctrl cell is within matrix (top-left for `mctop`, bottom-left for `mcleft` orientation). The arguments correspond to matrixctrl's index values, not matrix ordinal values. Thus, the default position is 0, 0. The first argument is the inlet and the second the outlet. This is the case no matter how matrixctrl is oriented.
		The second two arguments represent the size of matrixctrl. When initiated, matrix assumes that matrixctrl is the same size as matrix. If this is not the case (which is why you are now using mcoffset), then matrix needs to be told the dimensions of matrixctrl. The dimensions are in accordance with matrix, not matrixctrl. The first argument (arg3 of mcoffset) is the number of matrix inlets matrixctrl covers; the second (arg4), the outlets.
	clear	If you want to clear the entire matrix, send `[clear]` or `[all, -]` to matrix. This will clear both the entire matrix and matrixctrl. Matrix ignores `clear` when sent though data inlets, except that it is sent to any open outlets associated with the inlet. (NB: in conjunction with matrixctrl, `clear` works faster than `[all, -]` because matrix sends matrixctrl a clear message instead of a list of closed nodes.)
		When matrixctrl is smaller than matrix you need to be wary of the use of `clear`. Both matrix and matrixctrl accept this message. If you send matrixctrl a `clear` message and it is smaller than matrix, matrix will only be cleared in the range of the current position of matrixctrl. In other words, the window that is represented by matrixctrl is cleared. The rest of the matrix is left alone.

Multiple matrixctrls for a single matrix

Matrix can be connected to as many as 17 matrixctrls that configure matrix. In this way, you can use several smaller matrixctrls in a visual configuration that may be different than a straightforward matrix. Or, you can have several patchers access the same matrix.

All 17 matrixctrls are independent, yet a change in one will be reflected in any other matrixctrl that overlaps. That is, matrixctrls may overlap regions of matrix nodes. It is possible, for example, to have two patchers that have a matrixctrl that will cover the entire matrix. Updating one matrixctrl will be reflected in the other.

It is also possible to have several non-overlapping matrixctls, or a master control with several smaller controllers that represent portions of the matrix.

To use multiple matrixctrls you need to use modified commands, and also route matrix configuration output to each matrixctrl.

	`configOnChg arg1 [arg2...]`	Matrixctrls are referenced 0-16. Ctrl 0 is the default and if `configOnChg` has only one argument (0 or 1 representing on or off) matrix assumes that ctrl 0 is being addressed. If `configOnChg` has more than one argument, the remaining arguments represent a list of matrixctrls to turn on or off. Example: `[configOnChg 1 0 2 5]` turns on ctrl 0, 2, and 5. All others are unaffected. `[configOnChg 0 2 5]` turns off ctrl 2 and 5. It is important to turn off (or leave off) any matrixctrls that are not being used. Any ctrl that is on will cause matrix to send configuration data out its control outlet whenever a configuration is made. For the most part, matrix is very efficient about this, but it is more efficient if unnecessary controllers are off.
	`getconfig arg1`	`getconfig` takes one argument: the controller for which you want matrix to output its current configuration. This is generally not needed.
	`mctopx arg1 [arg2 arg3 arg4...]`	`mctopx` takes at least four arguments. The first argument is the controller that is initiating a configuration change, the rest are the values output by matrixctrl. `mctopx` may also take a matrixctrl style list for configuring multiple nodes with one list. arg1: matrixctrl (1-16). Use `mctop` (no 'x') for the default (0). arg2: 0 or 1 (on or off) arg3: column (h) = inlet arg4: row (v) = outlet ... in threes: on/off, h, v
	`mcleftx arg1 arg2 arg3`	`mcleftx` takes four arguments. The first argument is the control that is initiating a configuration change, the rest are the values output by matrixctrl. `mcleftx` may also take a matrixctrl style list for configuring multiple nodes with one list. arg1: matrixctrl (1-16). Use `mcleft` (no 'x') for the default (0). arg2: 0 or 1 (on or off arg3: row (v) = inlet arg4: column (h) = outlet ... in threes: on/off, h, v
	`mcoffsetx arg1 arg2 arg3 arg4 arg5`	If a matrixctrl does not cover the entire matrix, use `mcoffsetx` to tell matrix what part of the matrix this matrixctrl covers. arg1: matrixctrl (1-16). Use `mcoffset` (no 'x') for the default (0). arg2 is the inlet offset. arg3 is the outlet offset arg4 is the inlet size of matrixctrl arg5: is the outlet size of matrixctrl `mcoffsetx` is used if you have a large matrix that you want to control with a small matrixctrl. You can use matrixctrl as a moveable window inside the matrix. The second two arguments tell matrix where the first virtual matrixctrl cell is within matrix (top-left for `mctop`, bottom-left for `mcleft` orientation). The arguments correspond to matrix ordinal values, not matrixctrl's index values. Thus, the default position is 1, 1. The first argument is the inlet and the second the outlet. This is the case no matter how matrixctrl is oriented.
		The last two arguments represent the size of matrixctrl. When initiated, matrix assumes that matrixctrl is the same size as matrix. If this is not the case (which is why you are now using mcoffset), then it needs to be told the dimensions of matrixctrl. The dimensions are in accordance with matrix, not matrixctrl. The first argument (arg4 of mcoffsetx) is the number of inlets matrixctrl covers; the second (arg5), the outlets. See mcoffset for diagram.

Routing matrix configuration data to the proper matrixctrl in a multi-control configuration.

Finally, you must route configuration data from matrix to the correct matrixctrl. This is done using a Max route object. A simple list is output for controller zero, matrix prepends to all others, the symbol 'mcN' where 'N' is the controller (1-16) that matrix is trying to update.

Distribute functions: spray and unpack

If you have a list (numbers or symbols) that you want to distribute to the matrix outlets, one element per outlet, set one or more inlets to spray or unpack. Matrix will treat the inlet as if you were using spray instead of matrix. There are four messages that determine how lists are interpreted by matrix.

	`spray arg`	`spray` turns the inlet (or listed inlets if sent through control the inlet) into a `spray` inlet. With no argument, this message turns it on. The argument is either: 0: off 1: on (same as no argument) If the first item of the list is an int or float (floats are rounded, not truncated), it is used to indicate the first outlet for the 2nd item. Spray always references the first outlet as 0. If the first agument is a symbol, it is distributed like unpack. Matrix outlets are numbered starting from 1 or 0. The first element of the spray list (if numeric), indicates how far to shift the spray elements, not which outlet it will be sent through. The amount of shift is influenced by the distfilt attribute (see below).
	`distoff`	`distoff` takes no arguments and is the same as `spray 0 or unpack 0`.
	`unpack arg`	`unpack` turns the inlet (or listed inlets if sent through control the inlet) into a `distribution` inlet. With no argument, this message turns it on. The argument is either: 0: off 1: on (same as no argument)
	`distfilt arg`	`distfilt` takes one argument. The argument determines how spray and unpack elements are distributed when some of the outlets are closed. The default (0) is that each consecutive element is sent out consecutive open outlets. Thus, if a matrix inlet has [1 3 5] open and the spray list has three elements, each consecutive list element will be sent out the three outlets; the first to [1], he second to [3] and the third to [5]. If the argument is 1, then each list element is linked to its corresponding outlet. If an outlet is closed, then the corresponding element is not sent out. Thus if the same three element list were sent with this option on, the first element would be sent out [1], the second would not be sent, and the third element would be sent to outlet [3]. Argument: 0: distribute consecutive elements to all available outlets (same as no argument). The i/o spray reference behaves as if the closed matrix outlets don't exist. 1: link spray elements to matrix outlets. Don't send spray elements associated with closed outlets. Outlet open/closed staus act like a filter bank for unpack and spray elements. Spray i/o reference includes all outlets with the leftmost (whether open or closed) as outlet 0.

There are three factors that will determine which outlets the list elements will be sent out: spray/unpack and diistfilt options, and the first element of the spray list. Sometimes the resulting output is not intuitive so care must be given when choosing options.

If matrix is set to accept configuation from data inlets, you can temporarily distibute a list through an otherwise non-distribution inlet by prepending the list with either [spray] or [unpack] as in spray 2 distribute these elements].

LR function

Max convention uses right to left as the standard order from which an object sends messages through its outlets. Therefore by default, matrix sends data coming from inlets, to its outlets in reverse numerical order (right to left). There may be times when this order is unsuitable to your application. Therefore, matrix output may be reversed to left-to-right output order. In addition, this behavior is controlled on an inlet-by-inlet basis.

LR arg

LR determines outlet order.

0: Max default right to left output (same as no argument)
1: on (left to right output)

Prepend and Append

Matrix can prepend and append ints floats and sybols to incoming data. The x-pend value is associated with particular inlets and/or outlets. As a result, incoming data can have as many as four elements attached to it as it leaves the matrix.

X-Pends are single element entities (an int, a float, or a symbol). Each inlet can have one pre- and one ap-pend element associated with it. Each outlet can have one pre- and one ap-pend element associated with it. The order of attachment is:
Out_prepend, In_prepend, data, In_append, Out_append

The messages that configure prepends and appends are in the next table

	`i_prepend a1`	prepend a1 to current inlets
	`i_append a1`	append a1 to current inlets
	`o_prepend a1 @outs [descr]`	prepend a1 to descr outlets
	`o_append a1 @outs [descr]`	append a1 to descr outlets

	`il_prepend [list]`	prepend list of ints, floats, or symbols to current inlets
	`il_append [list]`	append list of ints, floats, or symbols to current inlets
	`ol_prepend [list] @outs [descr]`	prepend list of ints, floats, or symbols to descr outlets
	`ol_append [list] @outs [descr]`	append list of ints, floats, or symbols to descr outlets

	`is_prepend [i,s]r1 r2`	prepend series of ints, or symbols to current inlets. 'i' is the first value of the series that will then be applied to the range of inlets described by r1 (first inlet) and r2 (last) 's' is a symbol. The series uses the last characher of the series as the basis for the series. The ascii code of the last character is serially incremented.
	`is_append [i,s]r1 r2`	append version of is_prepend
	`os_prepend [i,s] r1 r2`	outlet prepend version
	`os_append [i,s] r1 r2`	outlet append version