Update for v1

Building.md

@@ -2,20 +2,20 @@
 
 ## Setting up your development environment
 
-Before building Rack, you must install build dependencies provided by your system's package manager.
+Before building Rack or Rack plugins, you must install build dependencies provided by your system's package manager.
 Rack's own dependencies (GLEW, glfw, etc) do not need to be installed on your system, since specific versions are compiled locally during the build process.
 However, you need proper tools to build Rack and these dependencies.
 
 ### Mac
 
-Install [Homebrew](https://brew.sh/), and install the build dependencies.
+Install [Homebrew](https://brew.sh/), and install build dependencies.
 ```bash
 brew install git wget cmake autoconf automake libtool jq
 ```
 
 ### Windows
 
-If you have an anti-virus program running, disable it.
+If you have an anti-virus program running, disable it or it may interfere with the build process.
 
 Install [MSYS2](http://www.msys2.org/) and launch the MinGW 64-bit shell from the Start menu, *not the default MSYS shell*.
 ```bash
@@ -23,24 +23,26 @@ pacman -Syu
 ```
 Then restart the shell.
 ```bash
-pacman -Su git wget make tar unzip zip mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake autoconf automake mingw-w64-x86_64-libtool mingw-w64-x86_64-jq
+pacman -Su git wget make tar unzip zip mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-cmake autoconf automake mingw-w64-x86_64-libtool mingw-w64-x86_64-jq
 ```
 
 ### Linux
 
-On Ubuntu 16.04:
+On Ubuntu 18.04+:
 ```bash
-sudo apt install git curl cmake libx11-dev libglu1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev zlib1g-dev libasound2-dev libgtk2.0-dev libjack-jackd2-dev jq
+sudo apt install git gdb curl cmake libx11-dev libglu1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev zlib1g-dev libasound2-dev libgtk2.0-dev libjack-jackd2-dev jq
 ```
 
 On Arch Linux:
 ```bash
-pacman -S git wget gcc make cmake tar unzip zip curl jq
+pacman -S git wget gcc gdb make cmake tar unzip zip curl jq
 ```
 
 ## Building Rack
 
-*If the build fails for you, please report the issue with a detailed error message to help the portability of Rack.*
+You do not need to build Rack to build plugins if you use the Rack SDK.
+
+*If the build fails for you, please [report the issue](FAQ.html#i-found-a-bug) to help the portability of Rack.*
 
 Clone this repository with `git clone https://github.com/VCVRack/Rack.git` and `cd Rack`.
 Make sure there are no spaces in your absolute path, since this breaks the Makefile-based build system.
@@ -66,11 +68,12 @@ Run Rack.
 
 ## Building Rack plugins
 
-Be sure to check out and build the version of Rack you wish to build your plugins against.
+Plugins can be built in two ways:
+- [Build Rack from source](#building-rack) and build plugins in the `plugins/` directory.
+- Download a build of Rack and the Rack SDK, and build plugins anywhere you like.
 
-It is recommended to download plugins to Rack's `plugins/` directory, e.g.
+Download or clone the plugin source code, e.g.
 
-	cd plugins
 	git clone https://github.com/VCVRack/Fundamental.git
 
 Clone the git repo's submodules.
@@ -82,3 +85,12 @@ Build the plugin.
 
 	make dep
 	make
+
+If using the Rack SDK, specify its location with
+
+	RACK_DIR=<Rack SDK dir> make dep
+	RACK_DIR=<Rack SDK dir> make
+
+To build, package, and install plugins to your Rack user directory in one step, run
+
+	make install

Core.md

@@ -24,7 +24,6 @@ The **INPUT** section sends up to 8 Rack signals to a hardware audio device for
 - [ASIO](https://en.wikipedia.org/wiki/Audio_Stream_Input/Output) on Windows
 - [ALSA](http://alsa-project.org/main/index.php/Main_Page) on Linux
 - [JACK](http://www.jackaudio.org/) on Linux
-- [VCV Bridge](Bridge.html)
 
 After a driver is selected, a particular **device** can be chosen for the driver.
 If the device has more than 8 inputs or outputs, you can select the desired range of outputs, offset by a factor of 8.
@@ -48,7 +47,6 @@ Each MIDI interface module (described below) supports the following drivers.
 - Windows MIDI on Windows
 - ALSA on Linux
 - JACK on Linux
-- [VCV Bridge](Bridge.html)
 - Gamepad
 - Computer keyboard
 
@@ -71,7 +69,7 @@ The **CV** output generates a 1V/oct pitch signal of the last held MIDI note.
 **VEL** generates a CV signal from 0V to 10V of the velocity, **AFT** generates aftertouch CV (channel pressure, not polyphonic aftertouch), **PW** generates pitch wheel CV from -5V to 5V, and **MW** generates mod wheel CV.
 **RTRG** generates a 1 ms trigger when a new note is pressed.
 **CLK1** and **CLK2** generate triggers specified by the division set by right-clicking on the panel and selecting the *CLK 1 rate* or *CLK 2 rate*.
-**STRT**, **STOP**, and **CONT** generate triggers when the MIDI hardware or DAW host (for VCV Bridge) sends a start, stop, or continue event.
+**STRT**, **STOP**, and **CONT** generate triggers when the MIDI device sends a start, stop, or continue event.
 
 
 ### MIDI-4

FAQ.md

@@ -23,8 +23,8 @@ See **Performance** above.
 
 ## I found a bug.
 
-Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check whether someone else has posted a similar issue.
-If you believe the problem has never been reported before, [open an issue](https://github.com/VCVRack/Rack/issues/new/choose) on GitHub with a detailed report containing the following information.
+Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check if someone else has posted a similar issue.
+If you believe the problem has never been reported before, [create a GitHub account](https://github.com/) (it's free) and [open an issue](https://github.com/VCVRack/Rack/issues/new/choose) with a detailed report containing the following information.
 
 - Your operating system and version
 - The Rack version
@@ -34,13 +34,13 @@ If you believe the problem has never been reported before, [open an issue](https
 
 ## I have a feature request.
 
-Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check whether someone else has posted a similar feature request.
-If you believe the feature has never been posted before, [open an issue](https://github.com/VCVRack/Rack/issues/new/choose) on GitHub with a detailed report containing the following information.
+Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check if someone else has posted a similar feature request.
+If you believe the feature has never been requested before, [create a GitHub account](https://github.com/) (it's free) and [open an issue](https://github.com/VCVRack/Rack/issues/new/choose) with a detailed report containing the following information.
 
 - Your proposal, with consideration for how it fits into Rack's existing features
 - A possible workflow or diagram (if your request involves multiple steps or UI states, e.g. dragging multiple modules simultaneously).
 
-Your feature request may be addressed during the next period of new feature design of Rack.
+Your feature request may be addressed during the next iteration of feature design of Rack.
 If your request is judged to be not sufficiently useful to other users, it may be closed.
 
 ## How do I load a default patch when selecting File > New?

Installing.md

@@ -7,8 +7,8 @@ However, if you are experiencing performance issues, make sure you have the foll
 - Operating system: MacOS 10.7+, Windows 7+, or Linux (Ubuntu 16.04+, etc)
 - CPU: Intel/AMD 64-bit processor from \~2011 or later
 - Graphics: Dedicated Nvidia/AMD graphics card from \~2013 or later. Integrated (non-dedicated) graphics such as Intel HD/Iris are not recommended and cause significantly increased CPU usage.
-- RAM: 1GB+
-- Disk space: 1GB+
+- RAM: 1GB
+- Disk space: 1GB
 
 ## Installing Rack
 
@@ -72,5 +72,6 @@ Or with the command-line, `cd` into the `Rack` directory and run `./Rack`.
 To launch Rack from the command line, `cd` into Rack's directory, and run `./Rack`.
 
 - `-d`: Enables development mode
-- `-g <path>`: Sets Rack's global directory
-- `-l <path>`: Sets Rack's local directory
+- `-g <dir>`: Sets Rack's global directory
+- `-l <dir>`: Sets Rack's local directory
+- `<patch filename>`: Loads a patch file

Migrate1.md

@@ -3,7 +3,7 @@
 This is a step-by-step guide for migrating plugins using the Rack v0.6 API to Rack v1.
 There are three phases of porting.
 - **Phase 1**: Quickly produces a valid Rack v1 plugin.
-- **Phase 2**: Modernizes your plugin by replacing deprecated v0.6 function calls with new v1 functions.
+- **Phase 2**: Modernizes the code by replacing deprecated v0.6 function calls with new v1 functions.
 - **Phase 3**: Takes advantage of new Rack v1 features such as parameter labels and polyphony.
 
 ## Prerequisites
@@ -27,7 +27,7 @@ pacman -S mingw-w64-x86_64-jq python3
 
 ### Linux
 
-On Ubuntu 18.04:
+On Ubuntu 18.04+:
 ```bash
 sudo apt install jq python3
 ```
@@ -97,6 +97,7 @@ perl -i -pe 's/Port::create/createPort/g' src/*
 perl -i -pe 's/Port::OUTPUT/PortWidget::OUTPUT/g' src/*
 perl -i -pe 's/Port::INPUT/PortWidget::INPUT/g' src/*
 perl -i -pe 's/Widget::create/createWidget/g' src/*
+perl -i -pe 's/MenuEntry::create\(\)/new MenuEntry/g' src/*
 perl -i -pe 's/MenuLabel::create/createMenuLabel/g' src/*
 perl -i -pe 's/MenuItem::create/createMenuItem/g' src/*
 ```
@@ -119,6 +120,7 @@ The event API has been overhauled in v1.
 If you use `on*()` event handler methods in your custom widgets, see [event.hpp](https://github.com/VCVRack/Rack/blob/v1/include/event.hpp) and [widget/Widget.hpp](https://github.com/VCVRack/Rack/blob/v1/include/widget/Widget.hpp) for new methods and event classes.
 
 Once completed, your plugin may compile, although many deprecation warnings may appear.
+If there are too many warnings to see the errors, you may temporarily add `FLAGS += -w` to your `Makefile`.
 
 ### 1.9
 
@@ -187,6 +189,7 @@ perl -i -pe 's/\bassetPlugin\b/asset::plugin/g' src/*
 perl -i -pe 's/\brandomUniform\b/random::uniform/g' src/*
 perl -i -pe 's/\brandomNormal\b/random::normal/g' src/*
 perl -i -pe 's/\brandomu32\b/random::u32/g' src/*
+perl -i -pe 's/\bstringf\b/string::f/g' src/*
 ```
 
 ### 2.7
@@ -204,7 +207,7 @@ perl -i -pe 's/(outputs\[.*?\])\.active/$1.isConnected()/g' src/*
 
 Add the `dsp::` namespace to dsp classes.
 ```bash
-perl -i -pe 's/\b(quadraticBipolar|cubic|quarticBipolar|quintic|sqrtBipolar|exponentialBipolar|BooleanTrigger|SchmittTrigger|PulseGenerator|RealFFT|ComplexFFT|RCFilter|PeakFilter|SlewLimiter|ExponentialSlewLimiter|ExponentialFilter|RealTimeConvolver|MinBlepGenerator|stepEuler|stepRK2|stepRK4|SampleRateConverter|Decimator|Upsampler|RingBuffer|DoubleRingBuffer|AppleRingBuffer|VuMeter|hann|hannWindow|blackman|blackmanWindow|blackmanNuttall|blackmanNuttallWindow|blackmanHarris|blackmanHarrisWindow)\b/dsp::$1/g' src/*
+perl -i -pe 's/\b(quadraticBipolar|cubic|quarticBipolar|quintic|sqrtBipolar|exponentialBipolar|BooleanTrigger|SchmittTrigger|PulseGenerator|RealFFT|ComplexFFT|RCFilter|PeakFilter|SlewLimiter|ExponentialSlewLimiter|ExponentialFilter|RealTimeConvolver|MinBlepGenerator|stepEuler|stepRK2|stepRK4|SampleRateConverter|Decimator|Upsampler|RingBuffer|DoubleRingBuffer|AppleRingBuffer|VuMeter|hann|hannWindow|blackman|blackmanWindow|blackmanNuttall|blackmanNuttallWindow|blackmanHarris|blackmanHarrisWindow|Frame|VUMeter)\b/dsp::$1/g' src/*
 ```
 
 ### 2.9
@@ -235,7 +238,7 @@ in the `MyModule` constructor, and change the original line to
 
 You can automate this process by running
 ```bash
-perl -nle 'print "configParam($1);" while /createParam.*?module, (.*?)\)/g' src/*
+perl -nle 'print "configParam($1, \"\");" while /createParam.*?module, (.*?)\)/g' src/*
 ```
 and copying the respective groups of lines into each module's `Module` constructor.
 Then remove the arguments with
@@ -249,6 +252,6 @@ Now make sure your plugin compiles.
 
 You are now ready to add optional Rack v1 features to your plugin.
 
-You may add parameters labels, units, and nonlinear scaling to be displayed when users right-click on a parameter or enable *View > Parameter tooltips*. See [Module::configParam()](https://github.com/VCVRack/Rack/blob/v1-gpl/include/engine/Module.hpp#L94-L95).
+You may add parameters labels, units, and nonlinear scaling to be displayed when users right-click on a parameter or enable *View > Parameter tooltips*. See [Module::configParam()](https://github.com/VCVRack/Rack/blob/v1/include/engine/Module.hpp#L94-L95).
 
-If you with to add support for polyphonic cables, see [How polyphonic cables will work in Rack v1](https://community.vcvrack.com/t/how-polyphonic-cables-will-work-in-rack-v1/1464) and [engine/Port.hpp](https://github.com/VCVRack/Rack/blob/v1-gpl/include/engine/Port.hpp).
+If you with to add support for polyphonic cables, see [How polyphonic cables will work in Rack v1](https://community.vcvrack.com/t/how-polyphonic-cables-will-work-in-rack-v1/1464), [Making your monophonic module polyphonic](https://community.vcvrack.com/t/how-polyphonic-cables-will-work-in-rack-v1/1464/39), and [engine/Port.hpp](https://github.com/VCVRack/Rack/blob/v1/include/engine/Port.hpp).

PluginLicensing.md

@@ -1,19 +1,15 @@
 # Plugin Licensing
 
-**This document is a draft. It is currently not in effect, so everything here is bogus now, but it may eventually become the guide for plugin licensing in the future.**
-
-VCV Rack is open-source software, but you should still familiarize yourself with the [VCV Rack licenses](https://github.com/VCVRack/Rack/blob/v1-gpl/LICENSE.md) before releasing your plugin, to avoid misuse of intellectual property. If in doubt, send any licensing questions to contact@vcvrack.com.
-
+VCV Rack is open-source/free software, but you should still familiarize yourself with the [VCV Rack licenses](https://github.com/VCVRack/Rack/blob/v1/LICENSE.md) before releasing your plugin, to avoid misuse of intellectual property. If in doubt, send your licensing questions to contact@vcvrack.com.
 
 ### I want to release my plugin under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) (GPLv3).
 
 Since Rack is licensed under GPLv3, you may license your plugin under GPLv3 as well.
 You may do anything with your plugin that the GPLv3 allows, including selling it without a commercial license (below) as long as you release the source code under GPLv3.
 
-### I want to release my plugin non-commercially under non-GPLv3 terms.
+### I want to release my plugin under a different open-source license or freeware.
 
-This is the most common choice among plugin developers.
-Rack offers a [VCV Rack Non-Commercial Plugin License Exception](https://github.com/VCVRack/Rack/blob/v1-gpl/LICENSE.md) which allows you to license your plugin under any terms you want, as long as it is offered free of charge.
+Rack offers a [VCV Rack Non-Commercial Plugin License Exception](https://github.com/VCVRack/Rack/blob/v1/LICENSE.md) which allows you to license your plugin under any terms you want, as long as it is offered free of charge.
 You may choose:
 - **Open-source**. [BSD 3-clause](https://opensource.org/licenses/BSD-3-Clause), [MIT](https://opensource.org/licenses/MIT), and [CC0](https://creativecommons.org/publicdomain/zero/1.0/) are popular licenses.
 - **Closed-source freeware**.
@@ -34,7 +30,7 @@ You can expedite the licensing processing by sending concepts and design mockups
 You may also wish to sell your plugin on the [VCV Store](https://vcvrack.com/plugins.html).
 Some benefits of distributing your plugin on the VCV Store:
 - Most Rack users are already familiar with the VCV Store checkout system.
-- Plugin updates are automatically synchronized to users' Rack installations.
+- Plugin updates are automatically synchronized to users' computers.
 - VCV offers advanced technical support with the Rack SDK and DSP library.
 - You may supply VCV with either binary packages for Mac/Windows/Linux, or a source package which we will build for you.
 - Access to dashboard for managing customers' purchases and viewing real-time statistics.

VoltageStandards.md

@@ -17,7 +17,7 @@ No voltage should be generated beyond this range, since it would be mostly impos
 Additionally, protection diodes on the ±12V rails usually drop the range to about ±11.7V.
 
 However, if you do not want to model analog output saturation for simplicity or performance reasons, that is perfectly fine.
-It is much better to allow voltages outside this range rather than use hard clipping with `clampf(out, -1.f, 1.f)` because in the best case they will be attenuated by a module downstream, and in the worst case, they will be hard clipped by the Audio module from Core.
+It is much better to allow voltages outside this range rather than use hard clipping with `clamp(out, -1.f, 1.f)` because in the best case they will be attenuated by a module downstream, and in the worst case, they will be hard clipped by the Audio module from Core.
 
 If your module is capable of applying >1x gain to an input, it is a good idea to saturate the output.
 
@@ -27,10 +27,10 @@ In Eurorack, many modules are triggered by reaching a particular rising slope th
 However, because of the [Gibbs phenomenon](https://en.wikipedia.org/wiki/Gibbs_phenomenon), a digital emulation will falsely retrigger many times if the trigger source is bandlimited (e.g. by using a virtual VCO square wave as a trigger input or a hardware trigger through an audio interface.)
 
 Therefore, trigger inputs in Rack should be triggered by a [Schmitt trigger](https://en.wikipedia.org/wiki/Schmitt_trigger) with a low threshold of about **0.1V** and a high threshold of around **1 to 2V**.
-Rack plugins can implement this using `SchmittTrigger` from `digital.hpp` with `schmittTrigger.process(rescale(x, 0.1f, 2.f, 0.f, 1.f))`
+Rack plugins can implement this using `dsp::SchmittTrigger` with `schmittTrigger.process(rescale(x, 0.1f, 2.f, 0.f, 1.f))`
 
 Trigger sources should produce **10V** with a duration of **1ms**.
-An easy way to hold a trigger for this duration is to use `PulseGenerator` from `digital.hpp` with `pulseGenerator.trigger(1e-3f)`.
+An easy way to hold a trigger for this duration is to use `dsp::PulseGenerator` with `pulseGenerator.trigger(1e-3f)`.
 
 Gates should produce **10V** when active.
 
@@ -42,6 +42,7 @@ For example, a pulse sent through a utility module and then to a sequencer's CLO
 This will cause the sequencer to reset to step 1, and one sample later, advance to step 2, which is undesirable behavior.
 
 Therefore, modules with a CLOCK and RESET input, or similar variants, should ignore CLOCK triggers up to **1ms** after receiving a RESET trigger.
+You can use `dsp::Timer` for keeping track of time.
 
 ## Pitch and Frequencies
 
@@ -53,4 +54,22 @@ Low-frequency oscillators and clock generators should use 120 BPM (\\(f_0\\) = 2
 
 ## NaNs and Infinity
 
-If your module might produce [NaNs](https://en.wikipedia.org/wiki/NaN) or infinite values with finite input, e.g. an unstable IIR filter or reverb, it should check and return 0 if this happens: `isfinite(out) ? out : 0.f`.
+If your module might produce [NaNs](https://en.wikipedia.org/wiki/NaN) or infinite output values when given only finite input, e.g. an unstable IIR filter or reverb, it should check and return 0 if this happens: `std::isfinite(out) ? out : 0.f`.
+
+## Polyphony
+
+If your module has polyphonic outputs, then it can be considered a "polyphonic module", so add the "Polyphonic" tag to the module's manifest.
+It is recommended to support up to 16 channels, which is the maximum that Rack allows.
+
+Typically each voice in your module can be abstracted into an "engine".
+The number of active engines \\(N\\) should be defined by the number of channels of the "main" input (e.g. 1V/oct input for VCOs, audio input for filters, gate input for envelope generators, etc).
+All other secondary inputs with \\(M\\) channels should follow these rules:
+- If monophonic (\\(M = 1\\)), its voltage should be copied to all engines.
+- If polyphonic with enough channels (\\(M \geq N\\)), each channel voltage should be used in its respective engine.
+- If polyphonic but not enough channels (\\(1 < M < N\\)), 0V should be copied to out-of-bounds engines.
+
+All of this behavior is provided by `Port::getPolyVoltage(c)`.
+
+Monophonic modules should handle polyphonic inputs gracefully:
+- For inputs intended to be used solely for audio, sum the voltages of all channels (e.g. with `Port::getVoltageSum()`)
+- For inputs intended to be used for CV or hybrid audio/CV, use the first channel's voltage (e.g. with `Port::getVoltage()`)

index.rst

@@ -2,7 +2,7 @@
 VCV Rack Manual
 ===========================================
 
-The VCV Rack manual is under active development.
+VCV Rack is an open-source virtual modular synthesizer.
 
 Edit this manual at https://github.com/VCVRack/manual.
 
@@ -17,7 +17,6 @@ Rack
    FAQ.md
    Toolbar.md
    Core.md
-   Bridge.md
 
 .. toctree::
    :maxdepth: 1