updated readme

3 files changed, 94 insertions, 17 deletions

diff --git a/Plugin.cmake b/Plugin.cmake
index 83586f6..b027b24 100644
--- a/Plugin.cmake
+++ b/Plugin.cmake
@@ -1,4 +1,4 @@
-set(PLUGIN_NAME adlmidi)
+set(PLUGIN_NAME opl)
 set(INCLUDES "include" ${CSOUND_INCLUDE_DIRS})
 set(LIBS "")
 
diff --git a/README.md b/README.md
index c2772c3..0b83a0e 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,24 @@
-# csound-opl3 : OPL3 emulation for Csound
+# csound-opl3 : OPL3 (YMF262) FM synthesis emulation for Csound
 
 ## Overview
-Description here
+csound-opl3 is a Csound plugin which provides an interface to emulated OPL3 FM synthesis as popularised by Yamaha chips, utilised by various
+computer sound cards from the late 1980s onwards. The YMF262 chip in particular was popularised by inclusion on the Sound Blaster 16 card, and 
+Yamaha's specific FM implementation had a significant impact on home computer synthesis, in particular through usage in games.
+
+The YMF262 chip applies an implementation of synthesis similar to some of Yamaha's other well known FM synthesisers such as the DX7 and TX81z although
+provides a cut-down 4 oscillator approach.
+Due to the popularity of the chip for computer games, it has been widely emulated in software and notably included in [DOSBox](https://www.dosbox.com/), 
+which has in turn been used (along with other emulations) by [ADLMIDI](https://bisqwit.iki.fi/source/adlmidi.html), further extrapolated to 
+[libADLMIDI](https://github.com/Wohlstand/libADLMIDI) and finally utilised to create this set of plugin opcodes for Csound.
+
+Complete control over all four oscillators (operators, in Yamaha terminology) is provided, along with the ability to use preset banks (instrument sets)
+which are compiled into ADLMIDI/libADLMIDI - many are custom banks extracted from various games and other software from the 1990s.
+
 
 ## Requirements
 * Cmake >= 2.8.12
 * Csound with development headers
-* libADLMIDI (https://github.com/Wohlstand/libADLMIDI)
+* [libADLMIDI](https://github.com/Wohlstand/libADLMIDI)
 
 
 
@@ -22,17 +34,28 @@ Cmake should find Csound and any other required libraries using the modules in t
 
 
 ## Notes
-Multiple types of OPL3 emulation are provided as in libADLMIDI. These are:
-* DOSBox : fast and quite accurate
-* Nuked : Very accurate, very CPU intensive
+Multiple types of OPL3 emulation are provided as in libADLMIDI. These are explained further on the [libADLMIDI](https://github.com/Wohlstand/libADLMIDI)
+and [ADLMIDI](https://bisqwit.iki.fi/source/adlmidi.html) pages.
+
+
+Instrument parameter ranges are representative of the original OPL3 chip which used 8-bit registers, hence ranges such as 0 - 15 and 0 - 3. 
+The parameters are all unsigned integers, so for example with attack, there are actually only 16 possible attack times. Any floating point numbers passed will just
+be converted accordingly. This is also the case for control change messages which are unsigned 8-bit integers.
+
+The only exception to this is the pitch bend opcode, oplpitchbend, which takes a value corresponding to a midi note (ie 1 = 1 semitone) and can be negative.
+
+
+There are two modes of selecting sounds to be used:
+
+* Preset banks and patches (compiled into libADLMIDI) using the oplsetbank, oplpatchchange and oplbanknames opcodes.
+* Parametric instrument editing of all parameters using the oplinstrument and oploperator opcodes.
 
-All parameter ranges are representative of the original OPL3 chip which used 8-bit registers, hence ranges such as 0 - 15 and 0 - 3. 
-The parameters are all integers, so for example with attack, there are actually only 16 possible attack times. Any floating point numbers passed will just
-be converted accordingly.
+Once the oplinstrument opcode is used for a particular opl instance, it will switch the channel from using preset banks to parametric editing.
 
 
 ## Examples
-Some examples are provided in the examples directory.
+Some examples are provided in the examples directory, including a FLTK gui for editing instruments. 
+There is also a [demonstration video](http://plugins.csound.1bpm.net/files/vid/opl-demo1.mp4) of the FLTK editor.
 
 
 ## Opcode reference
@@ -56,17 +79,26 @@ Play a note using the synthesiser specified by ioplhandle.
 * ivelocity : midi note velocity (0 - 127)
 
 
-### iop1, iop2, iop3, iop4 oplinstrument ioplhandle, kfeedback ETC
+### iop1, iop2, iop3, iop4 oplinstrument ioplhandle, kmode12, kmode34, kfbk12, kfbk34, k4op, kpseudo4op, kdeepvib, kdeeptrem
 Modify the current instrument parameters and obtain handles to all four operators (oscillators) for further manipulation with the oploperator opcode.
 
 * iop1, iop2, iop3, iop4 : handles for the individual operators to be used by the oploperator opcode.
 
+* ioplhandle : handle created by the opl opcode
+* kmode12 : op 1 and 2 mode (0 = FM, 1 = AM)
+* kmode34 : op 3 and 4 mode (0 = FM, 1 = AM)
+* kfbk12 : op 1 and 2 feedback (0 - 7)
+* kfbk34 : op 3 and 4 feedback (0 - 7)
+* k4op : use all 4 operators (0 = no, 1 = yes)
+* kpseudo4op : use all 4 operators with pseudo emulation (0 = no, 1 = yes)
+* kdeepvib : global deep vibrato (0 = off, 1 = on)
+* kdeeptrem : global deep tremolo (0 = off, 1 = on)
+
 
 ### oploperator iop, klevel, kscale, kattack, kdecay, ksustain, krelease, kwave, kfreqmul, ktrem, kvib, ksus, kenv
 Alter individual operator parameters. Out of range parameters will wrap around.
 
 * iop : handle for the specific operator as provided by the oplinstrument opcode
-
 * klevel : gain level (0 - 63)
 * kscale : key scale (0 - 3)
 * kattack : attack time (0 - 15)
@@ -83,9 +115,56 @@ Alter individual operator parameters. Out of range parameters will wrap around.
 
 
 ### oplpanic ioplhandle
-Terminate all current notes for the given opl instance.
+Terminate all current notes and reset the opl instance.
+
+* ioplhandle : handle created by the opl opcode
+
+
+### Sbanks[] oplbanknames ioplhandle
+Obtain all of the bank names compiled into libADLMIDI. The indexes returned can be
+used by the oplsetbank opcode accordingly.
+
+* Sbanks[] : array of bank names
 
 * ioplhandle : handle created by the opl opcode
 
 
+### oplsetbank ioplhandle, ibank
+Set the current bank (sound set) for the given opl instance. Any playing notes will be 
+stopped and the instance will be reset (may cause a click if audio is playing).
 
+* ioplhandle : handle created by the opl opcode
+* ibank : the bank index (corresponds to the output of oplbanknames
+
+
+### oplpatchchange ioplhandle, kchannel, kpatch
+Set the patch for the specified channel.
+
+* ioplhandle : handle created by the opl opcode
+* kchannel : channel index (0 - 15)
+* kpatch : patch index (0 - 127)
+
+
+### oplpitchbend ioplhandle, kchannel, kbend
+Set the pitch bend value for the specified channel.
+
+* ioplhandle : handle created by the opl opcode
+* kchannel : channel index (0 - 15)
+* kbend : bend amount in semitones (may be positive or negative)
+
+
+### oplaftertouch ioplhandle, kchannel, kaftertouch
+Set the aftertouch value for the specified channel.
+
+* ioplhandle : handle created by the opl opcode
+* kchannel : channel index (0 - 15)
+* kaftertouch : aftertouch amount (0 - 127)
+
+
+## oplcontrolchange ioplhandle, kchannel, kcontrol, kvalue
+Set a control change value for a specified channel.
+
+* ioplhandle : handle created by the opl opcode
+* kchannel : channel index (0 - 15)
+* kcontrol : MIDI CC number (0 - 127)
+* kvalue : value (0 - 127)
diff --git a/src/opcodes.cpp b/src/opcodes.cpp
index 7b38c80..a6fd7e9 100644
--- a/src/opcodes.cpp
+++ b/src/opcodes.cpp
@@ -554,6 +554,4 @@ void csnd::on_load(csnd::Csound *csound) {
     csnd::plugin<oplnote>(csound, "oplnote", csnd::thread::i);
     csnd::plugin<oplpanic>(csound, "oplpanic", csnd::thread::i);
     csnd::plugin<oplbanknames>(csound, "oplbanknames", csnd::thread::i);
-}
-
-
+}
\ No newline at end of file