PATCHES

A patch is a unit of programmation. It is the place where you interconnect objects in order to build musical algorithms.

A patch is created in the workspace window by the command New Patch in the File menu. A new patch icon then is placed on the workspace. That way, you can organize the numerous patches of your project into folders, subfolders etc.

Dbl-clicking on that patch icon opens the patch editor window.

In order to build your visual program, you have to drag objects on the patch window and interconnect them. Objects draggable to a patch window are :

• a class, dragged from a package. Once in a package window, a class becomes a factory.
• a function, dragged from a package.
• a global variable from the globals special folder
• a maquette from the workspace or from another patch.
• another patch, which becomes then a subpatch and behaves like a function if inputs and outputs are added to it. Note that a patch icon may be dragged into its own patch window, thus allowing recursivity.
• any draggable object coming from another patch (note that option-drag will copy the object while simple drag will move the object much like in the finder).
• any object dragged from the mac finder and for which a protocol has been implemented in OpenMusic. Such a protocol exists now for a MidifFile and an AIFF SoundFile.

Nota : functions and classes are also available through the global menus "Functions" and "Classes".

Inputs and outputs can be added to a patch, if it is to be dragged as a subpatch into other patches. Use the two buttons at the top of the patch window :

An input can be edited by dbl-click :

Note that an object can be dragged into the defval (default value) of the input.

When dropped into another patch window, a patch appears as an icon with inlets and outlets it is called a subpatch or an abstraction).

When a Class object added into a patch window, it becomes a 'factory' that generates a new instance of the class every time it is evaluated. If an editor has been implemented for that class, then you can alternatively construct or edit an instance by double-clicking on the factory icon, which will open the editor window.

A function or a factory can be entered by command-click-dragging a rectangle into the patch window then typing the name of the function (e.g. append, om+) or the name of the class (e.g. chord, voice) in the rectangle. Any known function can be entered that way, that is any OM function but also any Lisp function in the underlying Lisp kernel.

When entering an object by command-drag, typing the special name comment lets you enter a comment string. The special name patch lets you create an internal subpatch into your patch (an internal subpatch will always be attached to your patch).

command-click on a function icon issues a balloon help describing the function. If the description is too long, only the beginning will be showed in the balloon. In that case, typing 'd' on the selected function icon will show a full explanation window.

command-click on the input of a function will show a balloon help describing the input.

Command-click on an output will give information on this output. This is specially valuable in the case of factories, where the outputs represent object slots.

Option-click on an output is used to evaluate a patch or any object in a patch. Shift-option-click evaluates an object and renders the new object created by the evaluation visible (as an icon) in the patch window. This new object is called a variable.

'b' key pressed on a selected object in a patch displays a small button on the top left corner of that object. Clicking on that button puts the object in one of three states :

• locked. The object is locked on the last value it has computed (or that has been edited for editable objects). Evaluation will always yield that value.
• evaluate-once. The object is evaluated once then locked on that value until a new evaluation has been required by a user's mouse click. Thus, in a loop, the object is evaluated once.
• lambda. The value computed is not the result of executing the object (e.g. a function, a patch) but rather the object itself as a function. This special value can then be passed to another object (e.g. mapcar, samplefun) that requires a function as its input.
• reference. the value computed is the internal OM reference pointed to by the icon. In the case of a patch icon, the patch object itself (this can be connected to a maquette icon input in order to introduce dynamically patches into maquettes). Same thing for introducing dynamically a maquette into another maquette. For a factory icon, the class object it depends on. For a function icon, the CLOS generic function object. This is an advanced feature.

   

To go back to neutral state, press 'b' again.