Patchwork 3.03 Help Contents
Patchwork 3.1

Help is available for the following general topics:

File Menu

Edit Menu

Devices Menu

Options Menu

Help Menu

Tutorial

Patchwork Compiler

Patchwork Devices

Device Editor

Customizing the Device Library

Csound Hints


File Menu Contents

New

Open...

Save

SaveAs

Exit

About Patchwork...


Edit Menu Contents

Wire Mode

Text Mode

Device Mode

Select Mode

Undo

Cut

Copy

Paste

Clear


Device Menu Contents

Show Devices

Edit

New Picture

Replace Picture

Import Device

Export Device

Remove Device

Change Device Library


Options Menu Contents

Show Loose Wires

Compile

Set Defaults

Edit Setup File

ZOOM


Help Menu Contents

Index

CSound

Using Help


File Menu - New

Closes any currently open Patchwork file and clears the work space.


File Menu - Open...
File Menu - Open

Closes any .PWC file currently open, then invokes the File Open dialog box, which displays a list of all the .PWC files in the current directory.  Type or select the name of the .PWC file you wish to edit, then OK.


File Menu - Save

Save the current file.  If the file is untitled, the File Save dialog box will be invoked.  All Patchwork flowchart files are saved with the .PWC extension by default.


File Menu - Save As...
File Menu - Save As

Invokes the File Save dialog box.  Enter a new name for the Patchwork file to be created.

Note:  Patchwork files are given the extension .PWC by default, so it is only necessary to type the filename (without a suffix).  Although other extensions can be used, of course, this is not recommended, because then they will not appear in Patchworks File Open dialog box.


File Menu - Exit

Exit the Patchwork program.  If you have not saved your current work, you will be asked if you wish to do so before exiting.

Note: If the Patchwork Device Library has been modified in any way (including the repositioning of devices in the Device Window), you will also be asked if you want to save the changes to the Device file.  Just Say No, unless you have added a new device or made some modifications to the existing devices that you really want to keep.


File Menu - About Patchwork...
File Menu - About Patchwork

Displays brief information about the Patchwork program, including the current version number

Historical Note:

The Patchwork symbolic compiler was developed at The University of Texas at Austin Computer Music Research Center by Keith Lent in 1988, under an ICEM Fellowship from Apple Computer Corporation. It was originally designed for use in programming The University of Texas Accelerando Box, a programmable, modular, MIDI-controlled DSP system based on the Motorola 56001. [Lent, Pinkston, and Silsbee.  1989. Accelerando: A Real-Time,General Purpose Computer Music System, Computer Music Journal, 13(4): 54-64]. The initial version of Patchwork was for the Macintosh, but it has subsequently been ported to MS Windows, NeXT Step, and X-Windows Motif on the Silicon Graphics Indigo, primarily for use with MIT's CSound.


Edit Menu - Wire Mode

Switches to Wire Mode, which is used to draw wires in the workspace.  The cursor will change to a soldering iron.

To draw a wire, click the left mouse button at any point in the workspace and drag to the point where you want the wire to end.  Wires can be joined end to end to make a single, multi-segment wire group.

Accelerator Key:  <F5>


Edit Menu - Text Mode

Switches to Text Mode, used to place text strings in the workspace.  The cursor will change to a T.

To enter text, click on any point in the workspace.  An edit box will appear.  Type in the desired text, then click OK.  The text will be inserted at the point chosen with the mouse.

An existing text object can be edited (when in Text Mode), by clicking on the green dot to the left of the text string.  The edit will pop up with the existing text in it.

To remove a text object in Text Mode, click the green dot to edit the text, then click Remove.

Text objects must be attached to either a device pin or the end of a wire segment. Attaching a text object to the end of a wire segment will effectively label that wire - overriding the default wire name that would otherwise be provided by Patchwork during compilation. Note: Unattached text objects are considered loose wires by Patchwork.  They are ignored during compilation, but will be highlighted if Show Loose Wires is selected in the Options menu.

Accelerator Key:  <F6>


Edit Menu - Device Mode

Switches to Device Mode, used to place copies of the currently selected device into the workspace.  The cursor will change to a device icon.

To place a device in the workspace, first choose a device in the Device Window (or select one in the workspace by clicking it when in Select Mode).

Click the left mouse button and hold.  The currently selected device will appear under the cursor.

Drag the device to the exact location desired, then release the left mouse button.

Once a device has been placed in the workspace, it can be repositioned in Select Mode by clicking and dragging.

Device Mode is automatically entered after selecting a device in the Device Window.

Accelerator Key:  <F7>


Edit Menu - Select Mode

Switches to Select Mode, used to select objects in the workspace for editing.  The cursor changes to the standard Windows Arrow.

Click on any wire segment object, text object, or device object to select.  Wires and text objects which are selected turn blue, a device will have a blue rectangle drawn around it.

To select a group of objects, click the left mouse button and drag a rectangle around them, then release.  A large blue rectangle will appear around the entire group and smaller blue rectangles around any devices selected within the group.

Selected objects can be cut, copied, or cleared from the workspace.

Individual objects can be dragged around the workspace freely, but not a group of objects.

Double clicking a device object in Select Mode will cause the Device Editor Window to pop up.

Accelerator Key:  <F8>


Edit Menu - Undo

If enabled in the Edit Menu, you may select Undo to restore the drawing to its condition prior to the last edit.  Almost everything can be undone.


Edit Menu - Cut

Used to copy, then remove the selected object or objects from the workspace.  The objects are placed in the Patchwork Clipboard (NOT the Windows Clipboard), and may subsequently be pasted into the workspace at any point.

Accelerator Key: <Ctrl+X> or <Shift+Del>


Edit Menu - Copy

Used to copy the selected object or objects in the workspace.  The objects are placed in the Patchwork Clipboard (NOT the Windows Clipboard), and may subsequently be pasted into the workspace at any point.

Accelerator Key: <Ctrl+C> or <Ctrl+Insert>


Edit Menu - Clear

Used to delete the selected object or objects from the workspace.  Objects are NOT placed in the Patchwork Clipboard and, hence, cannot be pasted.

Accelerator Key: <Del>


Edit Menu - Paste

If enabled, may be used to place the current contents of the Patchwork Clipboard (NOT the Windows Clipboard) into the workspace.

Select Paste.  (The cursor will change to a P.)

Click the left mouse button and hold. (A blue rectangle will appear under and to the right of the P cursor.)

Drag the rectangle to the desired position in the workspace, then release the left mouse button.

Accelerator Key - <Ctrl+V> or <Shift+Insert>


Devices Menu - Show Devices

Used to toggle the whether the Device Window is currently visible or hidden.

Accelerator Key - <F9>


Device Menu - Edit

Opens the Patchwork Device Editor dialog box.  The bitmap of the currently selected device will appear, with a brief description, the code identified with it, and its current text to wire point assignments.

Caution!  Do not alter anything in this window unless you know what you are doing. Please seeCustomizing the Device Library.)

The Device Editor can also be opened by double-clicking a device in the Devices Window or in the Workspace (if in Select Mode).


Devices Menu - New Picture

This menu item is only enabled if there currently is a Windows Bitmap format file in the Windows Clipboard.  Selecting this item will launch the Device Editor window and place the bitmap in the center of the Device Editor workspace.  See Adding and Replacing Devices for more information.


Devices Menu - Replace Picture

This menu item is only enabled if there currently is a Windows Bitmap format file in the Windows Clipboard.  Selecting this item will launch the Device Editor window and place the bitmap in the center of the Device Editor workspace, along with the comment, code, and wire names associated with the existing device whose picture you are replacing.  See Adding and Replacing Devices for more information.


Devices Menu - Import Device

Invokes a file open dialog box for the purpose of selecting a .pwd device file to import into the current device library. Patchwork .pwd files contain the icon bitmap, code, and all other information associated with a single Patchwork device.  They are created using the Export Device command. See Importing and Exporting Devices for more information.


Devices Menu - Export Device

Invokes a file save dialog box to enter the filename of a Patchwork device file.  The file will be given the default extension .pwd and it will contain a copy of the icon bitmap, code, and all other information associated with the currently selected device. Patcwork device files can subsequently be loaded using the Import Device command.. See Importing and Exporting Devices for more information.


Devices Menu - Remove Device

Caution! This will remove the selected device from the currently loaded device library.  (Use Delete or Cut to remove devices and other objects from a flowchart.) Note: Removing a device from the library will affect any existing flowcharts that contain that device. In general, it is better to use the Replace Picture.command. See Adding and Replacing Devices for more information.


Devices Menu - Change Device Library

Use this command to open a different device library.  If you are using Patchwork with more than one synthesis language or you are adding your own devices and/or are sharing a computer with other users, you may wish to use a different device library from time to time.  Note, however, that Patchwork flowchart files created with one library may not be usable with another library, especially if the devices used in the drawing have been changed.  A PWC file created with one class of Device Library (CSound, for example) absolutely cannot be used with another class of Device Library (MUSIC56000, for example), because the devices (icons, hotspots, etc.) are completely different.

Loading a new device library requires an empty workspace.  If you have unsaved work, you will be prompted to save it, including any changes you may have made to the devices, then a new file will be created and the new library loaded.


Options Menu - Show Loose Wires

If Show Loose Wires is checked, any wires which are not currently connected to either device pins or text objects will be circled in Red.


Options Menu - Compile

Compiles the flowchart currently in the workspace into source code.

The Compiler Results dialog box will be shown, which gives information concerning the results of the compilation.

The output of the compilation is an ASCII text file containing the source code corresponding to the flowchart.  The file will be given the default file name provided in the PATCHWRK.INI file, unless it has been changed for the current instance of the program.  (See Set Defaults.)

The compilation of a Patchwork flowchart proceeds from top to bottom and left to right. (See The Patchwork Compiler for further information.


Options Menu - Edit Setup File

Invokes a dialog box where the user can edit the PATCHWRK.INI file, which contains the default options used by Patchwork whenever an instance of the program is launched.  If an existing PATCHWRK.INI is located in the Windows Directory, it will be read and its contents displayed in the Dialog Box.  Otherwise, the standard default options will be displayed and a new PATCHWRK.INI file will be created when <OK> is pressed to exit the dialog.  To change options temporarily in the current instance of the program, use Options Menu - Set Defaults.


Set Defaults...
Options Menu - Set Defaults

Invokes a dialog box where the user can select the default options used by Patchwork during compilation.  When an instance of Patchwork is first launched, these options will correspond to the entries in PATCHWRK.INI.

The default wire prefix is used by Patchwork when converting unlabelled wires to variable names in the output source file.  (E.g., if the prefix is w, then the variable names will be w1, w2, etc.)  Note that when compiling for CSound, it is sometimes more useful to set the first character of the default prefix to k, a, or even i, depending on what the majority of wires need to be for a particular instrument design.  See Default Wire Names for more information.

The default output file name is used to set the name for the output text file created by Patchwork during compilation.  Using a name like CODE.ORC, for example, would produce the same output file name for every compilation, replacing any existing CODE.ORC file in the current directory.  Alternatively, specifying *.ORC as the default output file name, for example, will cause Patchwork to use the same filename as the currently opened PWC file.  (I.e., if the file FOO.PWC is currently being compiled, the output would be FOO.ORC.)


Options Menu - ZOOM

Toggles whether the workspace is viewed normally or in ZOOMed mode.  When ZOOMed, the devices are reduced in size, so that more of the entire flowchart can be viewed simultaneously.  The flowchart may be edited normally in this mode.


Help Menu - Help Index
Help Menu - Index

Launches Windows Help for Patchwork and displays the Index.


Help Menu - Help CSound
Help Menu - CSound

If a CSOUND.HLP file is located in a directory in the DOS PATH, this command will launch it.  Patchwork does not provide help for CSound, but there is a CSOUND.HLP available on the internet.


Help Menu - Help
Help Menu - Using Help

This launches the standard Help file about using Windows Help.


A Brief Tutorial on Using Patchwork

Patchwork is a symbolic compiler that can convert pictures into computer programs.  While it was originally intended for use with computer music languages, it was designed to be open-ended and not tied to any particular system or language.  However, this tutorial will assume that the user is working with the computer music language for which the MS Windows version of Patchwork is primarily being used, in practice - MIT's CSound.  It assumes a basic familiarity with that language.

Using Patchwork

These are the steps required to produce a CSound Orchestra using Patchwork:

1. Start up Windows and then run the file PW.EXE.

The program displays an empty main window (the work space) and a popup window containing the devices icons.

You can drag the windows around and resize them as desired.  Note that the devices popup does not need to remain inside the main window and can be hidden entirely (by pressing F9,  or deselecting Show Devices in the Devices menu).

2. Create a "flowchart" of a CSound Instrument using device icons selected from the Devices Window and "wired" together with the mouse.  Save the picture (select Save from the File menu). Give it any desired filename - Patchwork will automatically add the file extension .PWC.

3. Compile the flowchart into a source program using the Compile command in the Options menu.  This will create a text file in the current directory which contains the source program into which your flowchart was translated.  This is a simple ASCII file which you can edit in Notepad, if you like  - it's just a standard CSound orchestra file.  However, if you designed your flowchart properly, it should not really require further editing.

Testing your new Patchwork orchestra requires the same additional steps as would be required to test any other CSound orchestra:

4. Use a text editor to create a CSound score file for the orchestra.

5. Run CSound, using the orchestra and score you just created.


Creating an Instrument

Creating a CSound instrument using Patchwork involves making a flowchart of that instrument.  This is done by selecting devices in the Device Window, placing them at the desired locations in the workspace, connecting outputs to inputs using the Wire tool, and optionally entering text (either to give a specific name to a wire or to type in values or variable names) at any point in the flowchart.

In designing a CSound flowchart in Patchwork, all the same rules for instrument design and Orchestra construction established by CSound still apply.  For example:

A valid CSound instrument always begins with an instr statement and ends with an endin statement.

There are strict rules governing the use and naming of variables.  All user-created variable names must begin with one of three valid prefixes - i, k, or a - and optionally preceded by g for "global" variables.  Some variable names are reserved, e.g., sr, kr, ksmps, nchnls, and the p-variables.

See the CSound Manual for further details.  Note that if you have a file called csound.hlp in a directory included in the PATH statement of your AUTOEXEC.BAT file, you can view it directly from within Patchwork.  See Help CSound.)

Once the flowchart is complete, it must be compiled by Patchwork (see Options Menu - Compile), which involves scanning the workspace for devices, wires, and text, and producing an output .ORC file.


A Simple Tutorial Example

[Before beginning the tutorial, please select Set Defaults from the Options menu and make sure that the Wire Name Prefix is aw and that Output File Name is *.ORC.]

1.	Maximize the work space window, then locate the Instrument No's icon in the Devices Window. (It's at the top left of the window.)

2.	Click on it once to select it.  (A dotted line will surround an icon once it is selected.)

3.	Press F9 to hide the Devices Window, then move the cursor into the workspace near the top. (Note that the cursor icon is now shaped like a device. This means you're now in "Device Mode," used exclusively for placing device icons in the workspace.

4.	Click and hold the left mouse button and you will see the icon appear - it can now be dragged precisely into position.  Place it near the top of the workspace.

Note: Once you release the mouse button, the device will be fixed in place; it cannot be dragged further while in Device Mode, but can be moved easily later, using "Select Mode" (choose Select under the Edit Menu or press F8, then click the device and drag it wherever you like).

5.	Press F9 to show the Devices Window again and move the cursor into the window.  (Note that the cursor shape changes back to the traditional arrow as soon as you enter the Devices Window.)  Find and select the linear envelope icon, located a little below and to the right of the speaker icons. Although it isnt labelled as such, this is the icon for the CSound unit generator linen.

6.	Press F9 to hide the Devices again, and place the linen in the workspace about an inch below where you placed the Instrument No's device.

Note:  you don't have to hide the Devices Window every time you want to place a device in the workspace, but it may be convenient to do so - just use the F9 button to toggle the Device Window in and out of view.  Alternatively, you may size and position both the Devices Window and the Workspace Window in such a way that you can leave them both visible.  For the remainder of this tutorial, it will be assumed that if you need to temporarily hide the devices, you will know how to do so.

7.	Next, find the oscili, cpspch, out (the single speaker icon), and endin (End) devices and place them in the workspace approximately as follows:

Note: the cpspch device is located near the top of the Devices Window, somewhat to the right.

8.	The next step is to wire some pins together.  Switch to Wire Mode (Edit Menu - Wire Mode, or press F5).  Then click the bottom (output) pin of the linen device and drag a wire down to the leftmost top (amplitude input) pin of the oscili.  Release the mouse button and a black wire should now connect the two pins.

Note that beginning or ending a new wire near to a device pin (as well as a piece of text or the end of an existing wire) will cause the new wire to "snap" to the pin.

Some of the icons in the Patchwork CSound library have labels next to their pins which indicate their function.  However, the more common (or obvious) devices, such as oscillators and envelope generators do not have labelled pins.  If you are unsure about the definitions of a particular devices pins, just look at it in the Device Editor.  (Double-click the device in the Devices Window, or in the workspace if in Select Mode, or select the device and choose Edit in the Devices Menu.)

Once a wire has been placed in the workspace, it can only be moved or modified in Select Mode (click a wire to select it, then Cut or Delete it, or drag it to another location, or Ctrl-click either end and drag one end at a time).  However, it is also possible (in Wire Mode) to continue a wire by simply adding additional segments to it.  (Just click near the end of the wire you wish to continue, then start a new wire from that point.  Patchwork will combine all connected wires into a single group during compilation of the orchestra, but leaves them as separate segments in the flowchart.

9.	Now draw two additional wires, one from the bottom (output) pin of the cpspch unit to the top right (frequency input) pin of the oscili, the other from the bottom (output) pin of the oscili to the input pin of the out (speaker) device.  Your flowchart should now look like this:

10.	Next, we will enter some text.  Press F6 to switch to Text Mode.  Then place the black dot of the T cursor over the red dot in the center of the instrument no's device and click the left mouse button.  A text editing box will appear.  Enter the number 1, then click <OK> to close the box and enter the text.  Using the same technique, enter the following text at the indicated places in your flowchart:

Notes:

Once a text object is in the workspace, there are various ways to modify it:  If you need to change what you have typed, then (in Text Mode) click on the leading dot of the text object.  A text edit box will appear, with the text in it ready for editing. If you need to delete the text, click the <REMOVE> button in the edit box.  In Select Mode, text objects can be dragged around the workspace, just like devices or wire segments, or selected and then cut, copied, or deleted.

The text objects kenvlp and icps were placed on the bottom (output) pins of the linen and cpspch devices, respectively.  This gives a label to the wires which attach to these pins.  Any wires which do not have text labels attached to them will be named automatically by Patchwork during compilation.  All wire names created by Patchwork will consist of the Wire Prefix (see Options - Set Defaults) and a number.  In this case, all unlabelled wires will start with aw, which will be CSound audio rate variables.  The output of the linen would be more appropriate if it was a control rate, or k-variable, and the output of the cpspch device an i-variable, so these wires must be labelled.

Most of the text objects were placed precisely on the ends of device pins, e.g., p3 and p7 on the duration and decay pins of linen, and the number 1 on the function# pin of the oscili.  However, there are two exceptions in this example - the p5 and p6 slightly above and to the left linen.  These two text objects were placed "in air," as it were, in order to demonstrate a point and a feature of Patchwork -  The "point" is that text objects can be placed anywhere in the workspace, not just on device pins or input points.  However, they must eventually be attached either to a device or to a wire end, or they will result in errors during compilations.  We will attach them to their appropriate points in a moment, but first, try selecting "Show Loose Wires" in the Options menu, which should demonstrate the "feature:"

When "Show Loose Wires" is selected, Patchwork will circle any unattached text objects or wire ends which are not connected to something.  (It does not circle unconnected device pins, because some pins are optional - for example the phase initialization pin of oscili, which is unconnected in the example above - but it will list the number of such pins in the Compiler Results Dialog Box.)

11.	Next, switch back to Wire Mode and draw wires from p6 to the leftmost (rise input) pin and from p5 to the top left (amplitude input) pin of the linen. The completed flowchart should now look as follows:

12.	The flowchart is ready to compile, but first, choose Save from the File menu and give it the name TUTOR.  Patchwork will automatically append the file type .PWC.  Next select Compile from the Options menu.  The following compiler results dialog box should appear:

The compiler produces a report on various things, some of which can safely be ignored in most cases.  However, you should always examine the first two fields:  "Wire labelling conflicts" occur in cases where more than one text object has been attached to the same wire group.  Such conflicts will probably cause unpredictable results in CSound, so they must be corrected. Unconnected device pins are usually not a problem, but sometimes they are, if a particular argument is required by CSound. Here, the one unconnected pin is the phase initialization pin of oscili, which is optional, so the warning can be ignored.

13.	Click <OK> in the dialog box, and the compilation is complete.  A file called TUTOR.ORC now exists in the current directory, and it should contain the following code:

	instr	1
kenvlp	linen	p5,p6,p3,p7
icps	=	cpspch(p4)
aw1	oscili	kenvlp,icps,1
	out	aw1
	endin
Note that each icon in the flowchart was replaced by a single line of source code.  The instrument no's icon by the instr statement, the linear envelope generator icon by the linen statement, the cpspch icon by the assignment statement, etc.  All text objects attached or wired to device pins replaced the corresponding arguments in the CSound units.  The one unlabelled wire (from the output of the oscili to the input of the out device) was automatically given the name aw1 by Patchwork.  (Succeeding wire names would have been aw2, aw3, etc.)

This concludes the tutorial.  We have built a very simple instrument design, indeed, but it is ready to run (using an appropriate Score and CSound's default values for sample rate, control rate, number of channels, etc.)  See the CSound Manual for more information.

A set of example flowchart designs is included with the distribution of Patchwork 3.0.  These examples demonstrate some of the more advanced techniques of instrument design using Patchwork.


Patchwork Devices

Patchwork devices are fairly simple.  They consist of a line of source code, an optional descriptive comment, a picture (bitmap), and a table of text strings (tokens) associated with hot spots (also called wire points) in the picture.  Each wire point in the table is associated with a different token, and all the tokens are contained somewhere in the line of source code (in a valid Patchwork Device).  Typically, the tokens are the names of variables used in the operation which the line of code will execute. When a Patchwork flowchart drawing is compiled, each device picture which is encountered in the drawing causes the line of source code which corresponds to that device to be added to the output text file. Then, the names of any wires and text objects which are attached to the devices wire points are used to replace the corresponding tokens in the line of code.   (See Patchwork Compiler.)

Almost all the information about a Patchwork device is displayed in the Device Editor, when the device is selected for editing, so the best way to understand the underlying structure is to browse through the devices in the Patchwork Device Library with the editor.

Special Devices

There are three special devices in the CSound Patchwork library which are not processed by the compiler in the normal way.  One is simply a comment (the note: device), which is ignored altogether during complilation, but useful for entering remarks in a flowchart.  The other two devices have names which begin with the # character, and they are commands to the compiler.   The devices are:

#include filename

This instructs the compiler to insert the file filename at the current point in the output source file.  The file must be a standard ASCII text file, is assumed to be a valid set of source program statements, and will be inserted exactly as is, except for the standard formatting. This is very useful for inserting blocks of initialization code, which is more easily entered in a text editor than as part of a Patchwork flowchart. A set of standard orchestra header files (orch22-1.hdr, orch22-2.hdr, orch44-1.hdr, and orch44-2.hdr) is included with the tutorial examples.

#DefaultWirePrefix wirename

This overrides the Default Wire Prefix set in PATCHWRK.INI and/or with Options - Set Defaults.  (See Set Defaults.)  As soon as the compiler encounters this statement in a flowchart, it begins all subsequent automatic wire names with the new prefix.  This is sometimes useful when designing complex CSound instruments, where there may be extended sections of the program which primarily use i-variables or k-variables, while other sections need to use a-variables.  Note that any wire which begins above (prior to) a #DefaultWirePrefix statement will have whatever prefix was in effect at that time, even if it continues below (beyond) the statement.

The Generic Device

There is a generic device contained in the Patchwork CSound library which can be used to insert CSound operations for which Patchwork does not have a specific icon.  The name of the desired CSound unit should be entered for the opcode parameter.  There are 10 pins on the icon - 1 output and 9 inputs, any, all, or none of which can be utilized.  During compilation, the names of any wires or variables attached to the input pins will be inserted in the line of source code, separated by commas.  The left to right order will be preserved.  Any unused pins will produce null strings; any trailing commas will be removed.


Device Editor

The Patchwork Device Editor is used to view and edit Patchwork Devices.  At the top of the edit window are two lines for text entry.  The first text line is for a descriptive comment.  The second is for a single line of source code which typically contains an operation code and up to 18 parameter strings (tokens).  (See Patchwork Devices.)  Below the text lines is the "device box," which contains the device icon - a standard Windows Bitmap.  On either side of the device box is a column of text edit boxes for the parameter tokens.  The tokens are associated with "hot spots" on the device icon (usually the ends of device "pins") by wires which are be drawn from the dots next to the parameter tokens to the desired spots on the icon.

The Device Editor may be opened either by double clicking a device in the Device Window or in the workspace (when in Select Mode), or by choosing one of the following commands from the Devices Menu:  Edit, which opens the currently selected device box (same as double clicking it); New Picture, which retrieves a bitmap from the Windows Clipboard and places it in the device box to be associated with code and parameter tokens, and Replace picture, which also retrieves a bitmap from the Clipboard, but copies the code and other data from the currently selected device. See Adding and Replacing Devices.

The NEXT and PREVIOUS buttons may be used to browse through the list of available devices.

Note that if you have made changes to a device which you want to keep, you must click OK, rather than NEXT or PREVIOUS, which are equivalent to a CANCEL from the device currently being edited.

WARNING:  The Device Editor is a useful way to browse through the Patchwork Device Library, or see how a particular device may be used.  However, any changes that you make (and OK) in the editor will change the copy of the device library currently in use.  Unless you want to keep the changes permanently, be sure to just say no when you exit Patchwork and are asked if you want to save the changes to the Devices file.


Customizing the Device Library

It is possible to customize Patchwork device libraries by editing existing devices in the Device Editor, adding new devices, and removing or replacing old ones. However, it is important to understand the implications of changing your device library, because it may affect the appearance of pre-existing flowcharts.

In general, adding new devices, or using the Device Editor to modify the code and/or comments associated with an existing device, will not affect the appearance of any previously created flowcharts.  However, replacing an icon or changing the position of the "hotspots" on an existing one (accomplished in the Device Editor) will usually require at least minimal editing of any old flowcharts that contain that device.  Of course, removing a device from the library altogether will make it difficult to use any pre-existing flowcharts that contained that device, but this is normally not necessary. (See Removing Devices.)

Notes:

Each device has an internal device number assigned to it by Patchwork when it is added to the device library. When a flowchart is saved, the actual devices are not saved in the file, only their numbers in the current device library and their positions within the drawing. When the file is reopened for editing in Patchwork, the device numbers are used to retrieve the corresponding icon bitmaps from the current device library. Consequently, if a flowchart created with one device library is opened using another having different internal device numbers, the "wrong" devices will appear on the screen.

If you plan to customize your device library, it is a good idea to save a copy of the original library under a different name.  This way, it is always possible to load the old library temporarily if you need to recompile an old drawing. (See Change Device Library.)


Adding and Replacing Devices

To add a new device or replace the picture for an existing one, you must first create a new icon bitmap using a program such as Windows Paint.  Once the icon is drawn, copy it to the Windows Clipboard, then return to Patchwork.  (To make small modifications to an existing device icon, try making it visible in the workspace, then pressing the Print Screen key.  Then open Paint and paste.)

If you wish to replace a device picture, first select the device in the Devices Window, then choose "Replace Picture" from the Devices Menu. To create a new device, choose "New Picture" from the Devices Menu. In either case, you will be warned that you are about to change the Devices Bitmap.  Click OK to proceed.The Device Editor will be launched and the new picture will be centered in the device box.

Once in the Device Editor, you enter comments, code, and connect parameter tokens to "hot spots."  If you are creating a new device, all the text boxes will be blank, and you will need to fill them in with the appropriate text.  If you are replacing a device picture, the comment, code line, and parameter tokens will be copied in - only the picture will be different.

The parameter tokens may be placed in any desired token box in either column - the order and position is insignificant. However, each parameter token contained in the code line should be unique (see below) and should appear only once in the token boxes.  To connect a parameter token to a hot spot, click the red dot next to the token and drag a wire to the hot spot.  Once a wire has been attached to some point in the bitmap, the dot next to the token will turn black and a red dot will appear at the other end of the wire.  At this point, you may make fine adjustments in the position of the hot spot by clicking close by the red dot, at the location to which you want to move it.  (It is much easier to do than to explain - just try it.  It takes some practice.)

IMPORTANT:  when Patchwork compiles a device, it replaces ALL occurrences of each token in the command line.  Hence, the tokens must be chosen with some care, so that they are unique and are not substrings of some other token (or of the operation code).  For example, a line of code such as the following would be very problematic:

out	farout	wayout,insideout,outsidein
When the token "out" is replaced by the compiler, say by the wirename "FOO," the resulting code will be:

FOO	farFOO	wayFOO,insideFOO,FOOsidein
The problem would be resolved simply by changing "out" to something like "out1," i.e.:

out1	farout	wayout,insideout,outsidein

The line above would work fine.

Notes:

To use devices not currently included in the Patchwork library without having to create the icons yourself, see the Patchwork Generic Device.

Caution: Replacing existing devices will affect the appearance of any flowcharts created using the original version of the device.  Such flowcharts may need minor editing.  (See Customizing the Device Library.)


Importing and Exporting Devices

If you have added one or more of your own custom devices to your library and wish to keep them when installing an updated "official" Patchwork library, do the following:

1) Save a copy of your original library under a different name, e.g., DEVICES.OLD.

2) Export the devices that you wish to keep from the old library one by one.  First select the device in the Devices Window.  Then choose Export Device from the Devices Menu.  Enter a name (the file type should normally by .pwd) and save the file.

3) Install the new device library. (E.g., replace the old DEVICES.CS file with the new one.)

4) Import the custom device files one by one.  Choose Import Device from the Devices Menu and open the desire device file (normally a .pwd file).  The device will be added in the first unused "slot" in the library - normally at the end of the device list.  The icon will appear in the bottom left hand corner of the Devices Window. Adjust its position as desired.

5) When you exit Patchwork, say "yes" when asked if you wish to save the changes to the Device file.

Note:  You will need to edit any old flowcharts that contain the custom devices if you wish to use them with the new library.  This is because the internal device numbers of the custom devices will have changed. (See Customizing the Device Library.) Consequently, the old flowcharts will now have "wrong" devices in certain places.  Simply select any such device, drag it out of the way of any wires and labels, and delete it from the drawing. Then select the correct device from the library and place it in the original location.  The wires and text labels should not need adjusting.  Hint: It may be easier to simply load the old device library temporarily if you need to recompile an old flowchart.


Removing Devices

In rare cases, it may be desireable to remove a device from the library.  Simply selected the device you wish to remove in the Devices Window and choose Remove Device from the Devices Menu.  Patchworks internal number corresponding to the device will be marked as unused, so it will be assigned to the next device added to the library.  Obviously, any flowcharts that utilized the old device will need to be edited before they can be recompiled.


Patchwork Compiler

Compiling a Patchwork flowchart is the process of converting it into an output ASCII text file which contains the program source code that corresponds to the flowchart currently in the workspace.

When a flowchart is compiled, it is read from top to bottom. Whenever a standard device is found in the drawing, a single new line of code is added to the output text file. The code is added in the exact order in which the device was found in the picture. (Note: if two devices are found at exactly the same height, the one on the right will be compiled first.) The wires which connect the device pins become variables in the source code lines which are the input and output parameters of the instructions.  See Patchwork Devices. The variables which correspond to any device pins that don't have wires or text strings attached to them in the flowchart are simply deleted from the line or source (converted to "null strings").

Notes:

the top to bottom order in which devices are compiled requires that the flowcharts "flow" from top to bottom, not left to right, as is common in some circuit diagrams.

Patchwork makes no distinction between "output" pins and "input" pins, so a device whose output will be used as input by another device must be higher up in the flowchart.  For example, these two flowcharts will not produce the same results:


Default Wire Names

One of the main advantages to using Patchwork to compile your synthesis algorithms, as opposed to typing in the code by hand in a text editor, is that you no longer have to specifically name every input and output in the program, which takes time and is a frequent cause of errors.  In a Patchwork flowchart, any wires not labelled specifically by the user are automatically labelled during compilation.  The wires are given the names aw1, aw2...awN (numbered in the same order that they were entered in the drawing), unless you have specified another default wire prefix, either in the PATCHWRK.INI file or using Options - Set Defaults. (See Options Menu - Set Defaults.)  IMPORTANT:  For CSound, this means that the variable names created for all unlabelled wires will be a (audio rate) variables.  There can only be one default wire prefix in effect at any time during compilation, so it is necessary to label any wires that need to produce variables of a different type than the default.

It may be convenient to change the default prefix temporarily for a particular compilation.  For example, if you are designing an instrument that uses more k-variables than a-variables, choose Set Defaults in the Options Menu and change the Default Wire Name to kw (or simply k). Then, label any wires that need to be i or a type variables specifically.  Note, however, that if you need to recompile the instrument at some future time, you will have to remember to change the default prefix again, since Patchwork will revert to the prefix in the PATCHWRK.INI file the next time it is launched.  Opening or creating a new file does not change the current defaults.

In addition, in Patchwork's CSound Device Library, there is a special device called #SetWirePrefix (see Special Devices) which can be used to change the default wire prefix at any point in a drawing.  This device can optionally be inserted at the top of an instrument design, in which case the default wire prefix will never be used when that .PWC file is compiled.  This will avoid unexpected results.  Moreover, in complex instruments, which may have blocks of devices used for control and other blocks of devices used for signal generation and processing, the #SetWirePrefix device can be used at various points in the flowchart, to temporarily produce k-variables, a-variables, or even i-variables, as needed.


Compiler Output Files

The output of a Patchwork Compilation is text file, which contains the source program statements corresponding to the devices, wires, and text strings found in the workspace.  This is a standard ASCII file which can be edited in any text editor or word processor, or simply used directly in a CSound run.

Default Output Filename

When Patchwork 3.0 is first installed, the default output filename is set to CODE.ORC.  This means that the compiler output from all flowcharts will produce the same file, overwriting any existing CODE.ORC file.  At times, this is convenient for testing instrument designs, especially if you need to look at the output frequently, because you can set up a Program Icon in the Windows Program Manager which launches Notepad and automatically opens CODE.ORC for editing.  At other times, however, it may be more convenient to create a different output file for each .PWC file you are editing.  In this case, set the default output filename to *.ORC, in which case the filename will always be the same as the filename of the .PWC file.

To temporarily change the default output file name, choose Set Defaults from the Options menu.  (See Options Menu - Set Defaults.)

To change the default output file name in PATCHWRK.INI, choose Edit Setup File from the Options menu.  (See Options Menu - Edit Setup File.)


Csound Hints
Miscellaneous Csound Hints

Choosing Devices

It is generally easiest and fastest to find devices in the Devices Window if the window is sized as large as possible and quickly toggled in and out of view using the <F9> key.

You don't always have to use the Devices Window to select the next type of device for insertion into the workspace.  If you have already used a particular device in a drawing, you can easily re-use it by pressing <F8> to enter Select Mode, clicking the desired device, and then pressing <F7> to enter Device Mode. The last device selected in the flowchart using Select Mode will always be the current device when you return to Device Mode.

Using Include Files

Use include files for orchestra header statements (e.g., sr and kr declarations, etc.) and for blocks of initialization code (e.g., iamp = p4, ipitch = cpspch(p5), etc.). It is much faster to type such statements in a text editor than to enter them as graphical icons one at a time in Patchwork. Also, such files can be reused easily in future instruments of a similar type.  (See Special Devices.)

Use Notepad to edit your include files and keep it open while creating your flowchart in Patchwork, possibly sized to fit on the screen beside or beneath your drawing.

Reusable Code Modules

If there are kinds of code modules that you tend to use in many instruments, such as one for vibrato or panning, etc., consider creating a separate .pwc file containing just those functions - widely spaced so that they are easy to copy.  Then, whenever you are creating a new instrument that requires a particular module, you can open the module file, copy the desired function, reopen the instrument file and paste to the desired location.

Variable Naming

One of the greatest advantages to using Patchwork to create a Csound orchestra, as opposed to doing it manually in a text editor, is the fact that you don't have to think up and type in all the variable names yourself. Not only can this save significant time, but it also helps to avoid errors caused by mistyping or simply forgetting what you called the output of one unit that you later want to use as an input to another. Ideally, we would never have to name any variables in a Patchwork drawing - we would simply draw wires.  Unfortunately, however, CSound utilizes three different kinds of variables, which are distinguished by strict naming conventions (i, k, and a-variables). Sometimes a particular type of variable is required; at other times, the type is optional, and may depend on subjective considerations. The user must decide. At present, Patchwork does not know which type of variable name is appropriate for a given wire, and only one default wire name prefix can be in effect at a time.  However, Patchwork does provide a special device called #DefaultWirePrefix which can be used to change the default at any point in a flowchart.  Suggestions:

Use a or aw as your default wire prefix (the one in your setup file), rather than k or kw. By in large, it is possible to use a-variables for any signal (something which is changing) without causing audible side-effects. (k-variables can cause audible side effects, like "zipper" noise on fast transients, graininess, etc.). So, unless you really need to maximize computational efficiency - i.e., you're creating an instrument that must run in real time and/or you have a very slow computer, stay away from k. Stick with a-variables as the default and specifically label any wires which are exceptions.

When designed large, complicated instruments, try to organize your flowcharts so that your initialization section (where you'll need to use i-wires) comes first. Use the special device #DefaultWirePrefix at the top of your drawing and set the prefix to i or iw. After the initialization block, use another #DefaultWirePrefix device to change to k-wires or a-wires, as needed.

There is a general rule in Csound that an operation's output variable can't be "slower" than any of its input variables - e.g., given an input of type a, the output can't be of type k, although there are exceptions. Consequently, if you use a labelled wire as an input to an operation, and that label is of a different type from the current default wire prefix, you may have to label the output wire, as well.  In some cases, you can save typing (and storage space) by forcing Patchwork to re-use an input wire for an operation's output.  Example:

By "shorting" the output pin with one of the input pins, we create a single wire group.  The Csound code produced by this example is:

kval	=	(kval) + (1)
kval	=	(kval) * (100)

Caution: In general, and especially when using this technique, make sure that the logical flow of outputs to inputs is downward.  For example, the following arrangement of the same devices would not produce the same results:

In this case, the output Csound code would be:

kval	=	(kval) * (100)
kval	=	(kval) + (1)

The order of the statements is reversed because the multiply device is higher than the add device, and hence is compiled first.