matrix

See also matrix v.4 enhancements. The matrix help file has numerous usage examples.

Created by Panaiotis
© 2001-2008 by Panaiotis. All rights reserved.

General

#inlets * #outlets <= 29600 or so

The message from any data inlet can be sent to any combination of outlets. The outlet assignments of each inlet are independent of each other.

Matrix will always have one more inlet and outlet than requested. The leftmost inlet is a control inlet and is used exclusively to alter the configuration of the matrix. All other inlets are data inlets that pass information through assigned outlets. The data inlets may also be directed to interpret assignment command messages. The first (or last, depending on arg4) outlet sends internal configuration useful for coordinating matrix commands with the max matrixctrl and matrix~.

Configuring matrix routing

There are two modes that affect configuration. In the default mode, matrix is configured through the leftmost inlet only. The syntax for configuring is:

Msg1: [list], Msg2: [symbol list]

1. The first message is a list of numbers representing the inlets that the second message will configure.
2. The second message is a symbol followed by a list of outlets that are affected by the operation governed by the symbol.

In the second mode, matrix may be configured either through the leftmost "control" inlet, or from any data inlet. In this mode configuration through the control inlet is the same as above. Configuration through the data inlets only affects the outlet status for the inlet receiving configuration messages. The message is the same as Msg2 mentioned above.

Input in leftmost (configuration control) inlet

The leftmost inlet is a control inlet and can be used to simultaneously configure several inlets. Therefore, the left inlet must first receive a list of numbers (or an int for a single inlet assignment) that tells matrix which data inlets are to be configured by subsequent assignment commands sent through the left inlet. Once this list is received, it is in effect until a new list of inlets is received.

Input to data inlets

 Assignment Commands

matrix has (number of data inlets) X (number of outlets) on/off gates. The messages to configure the matrix routing turn these gates on or off according to the operation and, often, the current state of each gate.

Outlet assignments are made through the leftmost inlet. If matrix is sent an  message (or arg3 of matrix is 1), assignment commands may be sent through data inlets. When this is the case, assignment commands sent through data inlets only affect the assignments for that particular inlet. An  tells matrix to interpret assignment commands that are sent to the leftmost inlet only. The following discussion assumes that matrix was set to interpret assignment commands sent to any inlet.

Outlet assignments are made by sending an operator prepended to a list or descriptor.
Example: [= 2 5] opens outlets 2 and 5 and closes all others for associated inlets.
[ odd 2 26, t even ] are two messages that can be read as: for odd inlets between 2 and 26 (inclusive), toggle the open/close status of even numbered outlets.

The descriptors are as follows:

In the control inlet, these descriptors are used to describe the inlets that subsequent operators will apply to. If the descriptor is appended to an operator (as listed below) they refer to the outlet list for which the operator will be applied.

In most cases, when matrix is set to allow configuration through its data inlets, configuration messages sent to a data inlet do the same thing as the same message sent through the control inlet.

Often, a symbol sent without arguments is a shortcut way to do the operation with a list of all outlets.

In the description below, the affected outlets are for the active inlets list if the message is sent to the control inlet, or the inlet that the message is sent through. Lists may be floats, which are truncated to ints.

	= [desc]	Open these outlets, close all others for this (or these) inlet(s)only. The descriptor can be any of the above (even, odd, mod, range or list]. In a data inlet with s=1 (allow config through data inlet), the descriptor without the '=' symbol acts the same as if the '=' were provided. In the control inlet, the '=' must be included to apply them to outlets. Otherwise, the descriptors indicate inlets.
		in data2 inlet: routes data sent through data inlet 2 to outlets 2 and 4 only.
	=	When no outlet list is appended to the "=" symbol, matrix opens only the outlet(s) corresponding to this (or these) inlets. An [all] [=] or [all, =] message in the leftmost inlet will open in1/out1, in2/out2, .... This is a shortcut to: [1, = 1], [2, = 2], [3, =3]... [2 3 6] [=] will subsequently configure inlets 2, 3, and 6 as: in2/out2, in3/out3, in6/out6.
		In data4 open only outlet 4 for inlet 4.
	+ [desc]	open these outlets. Leave the condition of other outlets alone.
	+	without arg list, open all outlets.
	– [desc]	close these outlets. Leave the condition of other outlets alone.
	–	Without arg list, close all outlets.
	t [desc]	toggle the on/off state of these outlets. Leave the condition of other outlets alone.
	t	without arg list, toggle the on/off state of all outlets.
	all	in left inlet selects all inlets for subsequent assignment command messages sent to left inlet. Example: [all] [+] configures all inlets to send to all outlets. [all] [-] closes everything.
		In data inlets: same as + with no arg list: opens all outlets for data inlet.
	< [descr]	rotate to the left the on/off state of these outlets. Arg list number order is significant. If the status of 5 outlets for a particular inlet is (0=closed, 1=open): 0 1 1 0 1 and  is sent, the result will be: 0 0 1 1 1 The status of 2 will be given to 3 (2 was open, so open 3). 3 will be given to 4 (3 was open so open 4). 4 will be given to 2 (4 was closed so close 2). The status of 1 and 5 are not altered. If the message  is sent, the result will be (notice, same numbers, different order): 0 1 0 1 1
	<	left rotate status of all outlets.
	>	Same as < except rotate right.
	<< arg [descr] << arg >> >> arg [descr] >> arg >>	Same as the rotate above except that the arg is a shift amount. [>> 2 odd] rotates all odd node values two positions. The operation behaves as if the outlets not described don't exist.
	<- -> <<- ->>	These take the same args as the rotate group. Instead of rotation, they simply shift without rotating.
	i> <i i<< i>> i-> i<- i->> i<<-	Same as the outlet rotate and shift but these apply to inlet configuartions
	rev [list]	reverse the order of the status of these outlets. Arg list number order is significant.
		If the status of 5 outlets for a particular inlet is: 0 1 1 0 0 and  is sent, the result will be: 0 0 0 1 1 The status of 3 and 5 are swapped and the status of 2 and 4 are swapped.
	rev	without arg list: Reverse the status of all outlets.
		In control inlet: tells matrix to pass all messages sent through the data inlets without any interpretation. This is the default behavior of matrix.
		In control inlet: assignment commands will be interpreted when sent through data inlets. When this is the case, assignment commands sent through data inlets only affect the assignments for that particular inlet.
	s	S in data inlets when  has been issued or arg3 is "1" (see below): S is a symbol. The 's' prepended to a symbol tells matrix to send the symbol (without the prepended 's') to outlet(s) assigned to the particular inlet. This is one way of sending the above listed assignment symbols through a data inlet while matrix is interpreting such symbols. Example: if matrix is set to allow configuration through inlets and you want to send the message [t 5 6] through data3, then you would need to actually send the message [s t 5 6]. The first 's' is stripped from the original and tells matrix not to interpret the 't' as a toggle configuration command. A safer way to do this is to momentarily shut off inlet configuration by sending an message to the control inlet. Then send the [t 5 6] through data3. You can send an message to the control inlet to continue allowing configuration through data inlets. In general, configuring matrix through data inlets works best if you are sending ints, floats, and lists, and no symbols that matrix will interpret as a configuration command.

Arguments

Integer arguments are interpreted in the following order. None of them are obligatory. Matrix defaults to a 2 x 2 matrix.

Output

Anything:

Messages received by data inlets are passed out the specified outlets according to the configuration of the matrix as discussed above. All types of data are passed through. Symbols are a special case when matrix is set to allow inlet configuration through the data inlets (see discussion above). All output is in standard right to left order. Assignment reversal, rotation, etc. do not affect the right to left output order. They only affect the internal matrix configuration.

Examples

	will assign each inlet to its respective outlet. Each  or  message will rotate all assignments one position left or right.
	message shifted the assignments. NB: the example does not include the control outlet because it was made before that feature was implemented.

See also

gate, reroute, switch, router