aboutsummaryrefslogtreecommitdiffstats
path: root/HelpSource/Classes
diff options
context:
space:
mode:
authorDavid Runge <dave@sleepmap.de>2020-12-30 01:16:39 +0100
committerDavid Runge <dave@sleepmap.de>2020-12-30 01:16:39 +0100
commit7f0d95d34b412322f0af17dc55db9dab4fd6d0cb (patch)
tree51292692b1e7818edd8233be710c6aad2724ea11 /HelpSource/Classes
parent57050ba42967df9fa159dbb257f58c27216c8db3 (diff)
downloadzzz-7f0d95d34b412322f0af17dc55db9dab4fd6d0cb.tar.gz
zzz-7f0d95d34b412322f0af17dc55db9dab4fd6d0cb.tar.bz2
zzz-7f0d95d34b412322f0af17dc55db9dab4fd6d0cb.tar.xz
zzz-7f0d95d34b412322f0af17dc55db9dab4fd6d0cb.zip
Add HelpSource for ZZZ, ZZZDevice and ZZZError
Add schelp files for ZZZ, ZZZDevice and ZZZError, explaining (mostly all) class and instance methods and giving code examples.
Diffstat (limited to 'HelpSource/Classes')
-rw-r--r--HelpSource/Classes/ZZZ.schelp179
-rw-r--r--HelpSource/Classes/ZZZDevice.schelp289
-rw-r--r--HelpSource/Classes/ZZZError.schelp22
3 files changed, 490 insertions, 0 deletions
diff --git a/HelpSource/Classes/ZZZ.schelp b/HelpSource/Classes/ZZZ.schelp
new file mode 100644
index 0000000..f62a95c
--- /dev/null
+++ b/HelpSource/Classes/ZZZ.schelp
@@ -0,0 +1,179 @@
+TITLE:: ZZZ
+summary:: Abstract superclass of all module specific Expert Sleepers classes
+categories:: External Control>Eurorack
+related:: Classes/ZZZDevice
+
+DESCRIPTION:: Users will normally not directly create instances of ZZZ, but
+only use it through its subclasses. It provides basic conversion methods, that
+can be used to drive DC coupled hardware of the Eurorack standard.
+Additionally it provides link::Classes/SynthDef##SynthDefs::, which will be
+added during instantiation, that can be used for clock and gate signals.
+
+CLASSMETHODS::
+
+subsection:: Initialization
+
+METHOD:: new
+Initialize a new instance.
+
+note::Do not call this method directly but instead derive a class from this one
+and use this method in the child's classes initialization method (see
+link::Classes/ZZZDevice:: for an example).::
+
+ARGUMENT:: channels
+An link::Classes/Array:: of link::Classes/Integer##Integers:: representing
+output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on a
+link::Classes/Server::.
+
+ARGUMENT:: server
+An instance of link::Classes/Server::.
+
+returns:: An instance of link::Classes/ZZZ::.
+
+METHOD:: initClass
+Uses link::Classes/StartUp#*add:: to add link::Classes/SynthDef##SynthDefs::
+used by child classes.
+
+list::
+## code::\ZZZGate::: A gate link::Classes/SynthDef:: utilizing link::Classes/DC::.
+## code::\ZZZClock::: A clock link::Classes/SynthDef:: (24 beats per quarter
+note) utilizing link::Classes/LFPulse::.
+## code::\ZZZClockKorg::: A clock link::Classes/SynthDef:: (48 beats per quarter
+note) utilizing link::Classes/LFPulse::.
+::
+
+subsection::Conversion
+
+METHOD:: ampmidi
+Calculates midi note for supplied amplitude.
+
+ARGUMENT:: amplitude
+Amplitude in the range from 0.0 to 1.0.
+
+returns:: MIDI note for corresponding amplitude, nil if amplitude is not within
+the allowed octave range.
+
+METHOD:: noteCpsRangeMax
+Cps for MIDI note C10.
+
+returns:: Returns cps for MIDI note C10.
+
+METHOD:: cvMaxADSR
+Maximum voltage for ADSR on Eurorack modules.
+
+returns:: Returns maximum voltage for ADSR.
+
+METHOD:: noteCpsRangeMin
+Cps for MIDI note C-2.
+
+returns:: Returns cps for MIDI note C-2.
+
+METHOD:: midiamp
+Calculates amplitude for supplied MIDI note.
+
+ARGUMENT:: midi
+MIDI note.
+
+returns:: Amplitude for corresponding midi note, nil if < 0 or > 127
+
+METHOD:: cvMinADSR
+Minimum voltage for ADSR on Eurorack modules.
+
+returns:: Returns minimum voltage for ADSR.
+
+METHOD:: cvMaxTriggerGateClock
+Maximum trigger/gate/clock control voltage for Eurorack modules.
+
+returns:: Returns maximum maximum trigger/gate/clock control voltage for Eurorack modules.
+
+METHOD:: cpsvoltage
+Calculates voltage for supplied cycles per second.
+
+ARGUMENT:: cps
+Cycles per seconds
+
+returns:: Returns voltage for corresponding cycles per second.
+
+METHOD:: noteVoltageRangeMin
+Maximum voltage for a note on Eurorack modules.
+
+returns:: Returns maximum voltage for notes.
+
+METHOD:: amplitudevoltage
+(describe method here)
+
+ARGUMENT:: amplitude
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cvMaxLFO
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: noteVoltageRangeMax
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: ampcps
+(describe method here)
+
+ARGUMENT:: amplitude
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cvMinTriggerGateClock
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: voltageamplitude
+(describe method here)
+
+ARGUMENT:: voltage
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cpsamp
+(describe method here)
+
+ARGUMENT:: cps
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cvMinLFO
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: voltagecps
+(describe method here)
+
+ARGUMENT:: voltage
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+
+INSTANCEMETHODS::
+
+METHOD:: channels
+Returns an link::Classes/Array:: of link::Classes/Integer##Integers::
+representing output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on a
+link::Classes/Server:: that was used in link::#*new:: to initialize an instance
+of this class (or any of its subclasses).
+
+returns:: An link::Classes/Array:: of link::Classes/Integer##Integers::.
+
+METHOD:: server
+Returns a link::Classes/Server:: instance that was used in link::#*new:: to
+initialize an instance of this class (or any of its subclasses).
+
+returns:: A link::Classes/Server:: instance.
diff --git a/HelpSource/Classes/ZZZDevice.schelp b/HelpSource/Classes/ZZZDevice.schelp
new file mode 100644
index 0000000..b23b2c3
--- /dev/null
+++ b/HelpSource/Classes/ZZZDevice.schelp
@@ -0,0 +1,289 @@
+TITLE:: ZZZDevice
+summary:: Interface Expert Sleepers devices
+categories:: External Control>Eurorack
+related:: Classes/ZZZ, Reference/ZZZ
+
+DESCRIPTION::
+This class provides an interface to Expert Sleepers' Eurorack modules.
+It offers convenience methods to create clocks and gates on the device's
+outputs, based on (shared) link::Classes/TempoBusClock##TempoBusClocks::.
+
+note:: ZZZDevice assumes that the (ADAT) channels used to interface with the Eurorack module are set to 0.0dB at +4dBu.::
+
+CLASSMETHODS::
+
+METHOD:: new
+Creates an instance of ZZZDevice on a link::Classes/Server:: using an
+link::Classes/Array:: of output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::).
+Throws link::Classes/ZZZError:: if the parameters ar not set or invalid.
+
+ARGUMENT:: channels
+An link::Classes/Array:: of link::Classes/Integer##Integers::, that represent
+output bus channels indeces (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on the
+link::Classes/Server:: instance.
+
+ARGUMENT:: server
+The link::Classes/Server:: instance to use.
+
+returns:: An instance of ZZZDevice interfacing the given hardware device.
+
+METHOD:: playTypes
+Return the understood playTypes that can be used. A code::playType:: relates to
+how scheduling takes place on a given link::Classes/TempoBusClock:: when adding
+or changing clocks on an output:
+
+list::
+## code::\beat::: When this code::playType:: is used the clock is added/ changed/ removed on the next beat.
+## code::\bar::: When this code::playType:: is used the clock is added/ changed/ removed on the next bar.
+::
+
+returns:: An link::Classes/Array:: of link::Classes/Symbol##Symbols::
+representing the understood code::playTypes::.
+
+METHOD:: clockTypes
+Return the understood types of clocks that can be used:
+
+list::
+## code::\zeroFive::: A clock signal ranging from code::0.0:: to code::5.0:: (24 beats per qarter note)
+## code::\minusFiveFive::: A clock signal ranging from code::-5.0:: to code::5.0:: (24 beats per qarter note)
+## code::\korgZeroFive::: A clock signal ranging from code::0.0:: to code::5.0:: (48 beats per quarter note)
+## code::\korgMinusFiveFive::: A clock signal ranging from code::-5.0:: to code::5.0:: (48 beats per quarter note)
+::
+
+returns:: An link::Classes/Array:: of link::Classes/Symbol##Symbols::
+representing the understood code::clockTypes::.
+
+
+INSTANCEMETHODS::
+
+subsection::Initialization
+
+METHOD:: init
+Initializes the link::Classes/Dictionary##Dictionaries:: required for
+link::#-clocks::, link::#-gates::, link::#-gateBusses::, link::#-outs::,
+link::#-tempos:: and link::#-tempoBusses::, as well as populates the
+link::#-outs:: link::Classes/Dictionary:: and initializes link::#-deviceGroup::
+when the link::Classes/Server:: is booted.
+
+note::This method is called when creating a new instance of ZZZDevice using link::#*new::.::
+
+subsection::Adding and Removing
+
+METHOD:: addTempo
+Adds a link::Classes/TempoBusClock:: to the link::#-tempos:: link::Classes/Dictionary::. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the slot to use for the link::Classes/TempoBusClock::.
+
+ARGUMENT:: tempo
+A link::Classes/Float:: (code::>=0.0::) setting the tempo.
+
+METHOD:: removeTempo
+Removes a link::Classes/TempoBusClock:: from the link::#-tempos:: link::Classes/Dictionary:: and any clock relying on it.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule removal of the tempo and clock link::Classes/Synth##Synth(s)::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+METHOD:: addClock
+Adds a clock link::Classes/Synth:: on a hardware output. Throws
+link::Classes/ZZZError:: on invalid input.
+
+note::Requires a tempo to be setup beforehand (see link::#-addTempo::).::
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the tempo slot to use for the clock (see link::#-addTempo:: on how to add a tempo).
+
+ARGUMENT:: type
+A link::Classes/Symbol:: describing the clock type to use (see link::#*clockTypes:: for the valid types and explanation).
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule playing the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+ARGUMENT:: replace
+A link::Classes/Boolean:: indicating whether to replace clock currently playing at code::output::.
+
+METHOD:: removeClock
+Removes a clock link::Classes/Synth:: playing on a hardware output.
+Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule removal of the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+METHOD:: addGate
+Adds a gate link::Classes/Synth:: on a hardware output. Throws link::Classes/ZZZError:: on invalid input.
+The gate's multiplication value can be controlled using the respective link::Classes/Bus:: exposed in link::#-gateBusses::.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: input
+A link::Classes/Float:: (code::>=0.0, <=1.0::) setting the initial multiplication value.
+
+METHOD:: removeGate
+Removes a gate link::Classes/Synth:: from a hardware output. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on ahardware device.
+
+subsection::Setting Data
+
+METHOD:: setClockTempo
+Sets the link::Classes/TempoBusClock:: used for a given clock on an code::output:: of an Expert Sleepers device. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on ahardware device.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule playing the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+ARGUMENT:: type
+A link::Classes/Symbol:: describing the clock type to use (see link::#*clockTypes:: for the valid types and explanation).
+
+METHOD:: setTempo
+Sets the tempo of a link::Classes/TempoBusClock:: (see link::#-addTempo:: on how to add a tempo).
+
+note::It may prove more pragmatic to write to the tempo's respective link::Classes/Bus:: in link::#-tempoBusses::.::
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: tempo
+A link::Classes/Float:: (code::>=0.0::) setting the tempo.
+
+subsection::Accessing Data
+
+METHOD:: clocks
+Returns a link::Classes/Dictionary:: of hardware output numbers and their
+respective clock link::Classes/Synth##Synths:: (see link::#-addClock:: on how to add a clock).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Synth:: associations.
+
+METHOD:: deviceGroup
+Returns the link::Classes/Group:: instance to which all link::Classes/Synth##Synths:: are added.
+This variable is setup during link::#-init::.
+
+returns:: A link::Classes/Group::.
+
+METHOD:: gateBusses
+Returns a link::Classes/Dictionary:: of hardware outputs and their respective
+link::Classes/Bus##Busses:: connected to the gate
+link::Classes/Synth##Synths:: (see link::#-addGate:: on how to setup a gate).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Bus:: associations.
+
+METHOD:: gates
+Returns a link::Classes/Dictionary:: of hardware output numbers and their
+respective gate link::Classes/Synth##Synths:: (see link::#-addGate:: on how to
+add a gate).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Synth:: associations.
+
+METHOD:: outs
+Returns a link::Classes/Dictionary:: representing the mapping between the outputs
+on the hardware (the numbering starts at code::1::) and the
+link::Classes/Server::'s output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) connected to the hardware.
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: associations.
+
+METHOD:: outputOnHardware
+Returns the output bus channel (an link::Classes/Integer:: within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) mapped to a given hardware
+output number.
+Throws link::Classes/ZZZError:: if the output parameter is invalid.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+returns:: An link::Classes/Integer:: representing an output bus channel.
+
+METHOD:: tempoBusses
+Returns a link::Classes/Dictionary:: of slots (starting from code::1::) and
+their respective link::Classes/Bus##Busses::, which are connected to
+link::Classes/TempoBusClock##TempoBusClocks:: and clock link::Classes/Synth##Synths::.
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Bus:: associations.
+
+METHOD:: tempos
+Returns a link::Classes/Dictionary:: of the currently available tempos (see
+link::#-addTempo:: on how to setup a tempo).
+
+returns:: A link::Classes/Dictionary:: of slots (link::Classes/Integer::) and link::Classes/TempoBusClock:: associations.
+
+subsection::Posting Information
+
+METHOD:: postAll
+Convenience wrapper around link::#-postClocks::, link::#-postGates::, link::#-postOuts:: and link::#-postTempos::.
+
+METHOD:: postClocks
+Posts information about the currently running clocks.
+
+METHOD:: postGates
+Posts information about the currently running gate link::Classes/Synth##Synth(s)::.
+
+METHOD:: postOuts
+Posts information about the mapping of hardware outputs to link::Classes/Server:: output bus channels.
+
+METHOD:: postTempos
+Posts information about the currently running link::Classes/TempoBusClock##TempoBusClocks::.
+
+EXAMPLES::
+
+code::
+// first Server output bus channel of ADAT connection to Expert Sleepers hardware device
+// this might be different depending on hardware or sclang startup configuration
+~firstChannel = 12;
+
+// initialize connection
+s.waitForBoot(
+ ~zzzdevice = ZZZDevice.new(server: s, channels: Array.series(8, start: ~firstChannel, step: 1));
+);
+
+// add a tempo
+~zzzdevice.addTempo(slot: 1, tempo: 120/60);
+
+// add a clock on the first hardware output using the above tempo
+~zzzdevice.addClock(output: 1, slot: 1);
+
+// add a gate on the second hardware output
+~zzzdevice.addGate(output: 6);
+
+// set the tempo
+~zzzdevice.setTempo(slot: 1, tempo: 180/60);
+
+// remove everything
+(
+ ~zzzdevice.removeTempo(slot: 1);
+ ~zzzdevice.removeGate(output: 6);
+)
+::
diff --git a/HelpSource/Classes/ZZZError.schelp b/HelpSource/Classes/ZZZError.schelp
new file mode 100644
index 0000000..49bf0d0
--- /dev/null
+++ b/HelpSource/Classes/ZZZError.schelp
@@ -0,0 +1,22 @@
+TITLE:: ZZZError
+summary:: Errors for ZZZ
+categories:: External Control>Eurorack
+related:: Classes/ZZZ, Classes/ZZZDevice, Classes/Error
+
+DESCRIPTION::
+An link::Classes/Error:: class for link::Classes/ZZZ:: and its subclasses.
+
+
+CLASSMETHODS::
+
+
+INSTANCEMETHODS::
+
+
+EXAMPLES::
+
+code::
+// throw a ZZZError
+ZZZError("Something went wrong!").throw;
+::
+