poly~

Polyphony/DSP manager for patchers

Description

The poly~ object is similar to the patcher object: it lets you encapsulate a patcher inside an object box. However, as the name suggests, where the patcher object only has one copy of the encapsulated patcher, the poly~ object allows one or more instances (copies) of a patcher to be loaded. You specify the patcher filename and the number of instances you want as arguments to poly~. The maximum number of instances is 1023.

The poly~ object directs signals and events (messages) received in its inlets to in and in~ objects inside patcher instances. The patcher can also contain out and out~ objects to send signals or events to the outlets of the poly~ object. Messages to the poly~ object control audio processing in its loaded patcher instances and let you control the routing of events.

Arguments

Name Type Opt Description
patcher-name symbol Obligatory. The first argument must be the name of a patcher.

Note: Unlike the patcher object, a subpatch window is not automatically opened for editing when a patcher argument is supplied for the poly~ object; the patcher containing the object must already exist and be found in the Max/MSP search path.
number-of-patcher-instances int opt After the patcher name argument, the number of instances of the loaded patcher (which correspond to the number of available "voices") is specified. The default value is 1, and the maximum number of instances is 1023. The number of available voices may be dynamically changed by using the voices message.
'local' and flag (0 or 1) symbol opt The word local, followed by a zero or one, toggles local scheduling for the poly~ object's loaded patcher. Local scheduling means that the poly~ object maintains its own scheduler that runs during its audio processing rather than using the global Max scheduler. This allows finer resolution for events generated by multiple patcher instances. However, no scheduling occurs if audio processing is turned off, either globally or locally for the poly~ object or one or more of its instances. The default is off (local 0). Local scheduling cannot be changed by sending messages to the poly~ object. Scheduler locality is permanent for any patcher which is loaded.
'up' and up-sampling-factor symbol opt The word up, followed by a number which is a power of 2, specifies that upsampling by the designated power of two is to be done on the currently loaded patcher. The message up 2 specifies upsampling by a factor of 2 (e.g., 88200 Hz at a sampling rate of 44100 Hz). Although both up and down are permissible arguments to the poly~ object, the down message takes precedence over up.
'down' and down-sampling factor symbol opt The word down, followed by a number which is a power of 2, specifies that downsampling by the designated power of two is to be done on the currently loaded patcher. The message down 2 specifies downsampling by a factor of 2 (e.g., 22050 Hz at a sampling rate of 44100 Hz). Although both up and down are permissible arguments to the poly~ object, the down message takes precedence over up.
'args' and list-of-argument-values symbol opt The word args can be used to initialize any pound-sign arguments (e.g., #1) in the loaded patcher. If used, the args argument must be the last argument word used; everything which appears after the word args will be treated as an argument value.

Messages

bang Performs functions which are specific to the user-designed poly~ patcher itself.
int input [int]
Performs functions which are specific to the user-designed poly~ patcher itself.
float input [float]
Performs functions which are specific to the user-designed poly~ patcher itself.
list message [list]
In any inlet: If you want to send a message to a poly~ instance that starts with one of the words used to control the poly~ object itself, prepend the message with the word list. For example, the message list target 2 sent to the left inlet of poly~ will output target 2 out the outlet of all in 1 objects, rather than changing the current target instance to the second patcher.
anything message [list]
The number of inlets and outlets for poly~ is determined by the patcher that is loaded. The inlets for the patcher loaded by a poly~ object accept both signal and event connections.

The signals are routed inside of the loaded patcher by using the in~ objects for signals or the in object for events. The number of total inlets in a poly~ object is determined by the highest number of an in~ or in object in the loaded patcher (e.g., if there is an in~ with argument 3 and an in with argument 4, the poly~ object will have four inlets. All the inlets accept signal connections even though there may not be an in~ object corresponding to each inlet.

Signal inputs are fed to all instances.
(drag) When a patch is dragged from the Max 5 File Browser to a poly~ object, the file will be loaded.
allnotesoff In left inlet: The word allnotesoff can be used to turn off all playing notes by sending a message to each instance with a playing note. The message consists of the MIDI pitch most recently received via the note or midinote message followed by a 0 (meaning zero velocity or note-off).
busymap message-outlet-number [int]
In left inlet: The word busymap, followed by a number which specifies a message outlet number, will report voice busy states out the specified message outlet of the poly~ object.
(mouse) Double-clicking on poly~ opens a display window where you can view the contents.
down 'down' and down-sampling factor [int]
The word down, followed by a number which is a power of 2, specifies that downsampling by the designated power of two is to be done on the currently loaded patcher. The message down 2 specifies downsampling by a factor of 2 (e.g., 22050 Hz at a sampling rate of 44100 Hz). Although both up and down are permissible messages to the poly~ object, the down message takes precedence over up.
exclude voice number [int]
0/1 [int]
In left inlet: The word exclude, followed by a voice number and a one, prevents a poly~ instance from being sent messages via note allocation when the poly~ receives a note or midinote message. By default, all voices are enabled for note allocation. The word exclude, followed by a voice number and a zero re-enables the instance to receive messages when the poly~ receives a note or midinote message.
mute instance-index [int]
on/off-flag (0 or 1) [int]
In left inlet: The word mute, followed by a number and a zero or one, will turn signal processing off for the specified instance of a patcher loaded by the poly~ object and send a bang message to the thispoly~ object for the specified instance. When the second number is a 1 processing in the patcher instance is turned off (muted). When the second number is a 0, the processing in the patcher instance is turned on. The message mute 0 1 mutes all instances, and mute 0 0 turns on signal processing for all instances of the patcher.
open instance-index [int]
In left inlet: The word open, followed by a number, opens the specified instance of the patcher. You can view the activity of any instance of the patcher up to the number of voices (set by the voices message or by an argument to the poly~ object). You can use this message to view an individual instance of the patcher at work. With no arguments, the open message opens the instance that is currently the target (see the target message).
note voice-allocated-data [list]
In left inlet: The word note, followed by a message, will send the data to the first in object of the first instance of the patcher that has not marked itself "busy" by sending a 1 to a thispoly~ object inside the patcher instance.
midinote pitch and velocity (for voice-allocation) [list]
In left inlet: The first number after the word midinote is the note number, followed by the velocity. If the velocity of the received MIDI note is not 0, the poly~ object routes the pitch velocity to the first available instance. If the velocity is 0 (i.e. note-off), the pitch velocity will be sent to the poly~ instance that generated the note. The determination of which instance of the loaded patcher the midinote message will be sent to is managed by sending a 0 (non-busy) or 1 (busy) to a thispoly~ object located in the loaded patcher.
mutemap message-outlet-number [int]
In left inlet: The word mutemap, followed by a number which specifies a message outlet number, will report voice mutes out the specified message outlet of the poly~ object.
up 'up' and up-sampling-factor [int]
The word up, followed by a number which is a power of 2, specifies that upsampling by the designated power of two is to be done on the currently loaded patcher. The message up 2 specifies upsampling by a factor of 2 (e.g., 88200 Hz at a sampling rate of 44100 Hz). Although both up and down are permissible messages to the poly~ object, the down message takes precedence over up.
threadcount number of threads [int]
The word threadcount, followed by a number, sets the number of threads used to divide poly~ instances' audio processing. The default is the number of processor cores available in your computer. Typically, the number of threads should be set to the number of processor cores in your computer for best performance. This can also be accomplished by sending the message threadcount 0. If a poly~ object has sixteen instances and the threadcount is 4, four of the poly~ instances will process audio in each of four threads.
wclose instance-index [int]
In left inlet: The word wclose, followed by a number, will close the window which contains the instance of the loaded patcher identified by the numbered index. It is the complement to the open message. When used without the number argument, wclose will close the patcher window with the highest numbered index.

Attributes

Name Type g/s Description
args atom Specifies the arguments for the poly~ object's loaded patch. The patch must be reloaded by setting the patchername attribute in order for new arguments to take effect after initial load.
parallel int Toggles parallel processing. When this attribute is set to enable parallel processing, the poly~ object enables the use of multiple threads to run audio processing for all patcher instances. Otherwise, poly~ runs all patcher instances in the audio processing thread. The DSP chain must be restarted whenever the parallel attribute is changed. This attribute is disabled it when Max is hosted by the Live application.

Note: At this time, you cannot specify a single subpatcher on a different core. When enabled, this attribute splits up the number of voices between the number of processors available. It is primarily intended for patches that use a significant amount of CPU within multiple voices of the same poly~ object, and the multithreading overhead is primarily useful for larger signal vector sizes (at least 32 or greater). Other situations will not benefit. Using the default threadcount (which is equal to the number of physical cores) is best."
patchername symbol Specifies the filename of a patcher file loaded into the poly~ object.
steal int Toggles voice stealing. If voice stealing is set, the poly~ object sends the data from the note or midinote messages to instances that are still marked "busy"; this can result in clicks depending on how the instances handle the interruption. The default is 0 (voice stealing off).
target int Specifies the poly~ instance that will receive subsequent messages (other than messages specifically used by the poly~ object itself) arriving at the poly~ object's inlets - for example, The message target 2 routes messages to the second instance. The message target 0 sends input to all instances, and using any negative number value with the target message will disable input to all instances.
voices int Sets the number of instances (copies) of the loaded patcher. Instances of the patcher are loaded or deleted as needed. The maximum number of instances is 1023.
vs int Specifies the signal vector size for the poly~ object's loaded patch. The signal vector size will be set on the next compilation of the DSP chain. The vs message does not force a recompilation of the DSP chain. vs 0 specifies no fixed vector size. The default is the current signal vector size.

Information for box attributes common to all objects

Output

anything: The number of outlets of a poly~ object is determined by the sum of the highest argument numbers of the out and out~ objects in the loaded patcher. For instance, if there is an out 3 object and an out~ 2 object, the poly~ object will have five outlets. The signal outputs corresponding to the out~ objects are leftmost in the poly~ object, followed by the event outlets corresponding to the out objects.

Signals sent to the inlet of out~ objects in each patcher instance are mixed if there is more than one instance and appear at the corresponding outlets of the poly~ object.

Examples

The poly~ object manages multiple instances of a subpatch

See Also

Name Description
in Message input for a patcher loaded by poly~ or pfft~
in~ Signal input for a patcher loaded by poly~
out Message output for a patcher loaded by poly~ or pfft~
out~ Signal output for a patcher loaded by poly~
patcher Create a subpatch within a patch
thispoly~ Control poly~ voice allocation and muting
MSP Tutorial 20: MIDI Sampler Control MSP Tutorial 20: MIDI Sampler Control
MSP Tutorial 21: Using the poly~ Object MSP Tutorial 21: Using the poly~ Object