Skip to content

Commit

Permalink
Add inline documentation to Node subclasses
Browse files Browse the repository at this point in the history
  • Loading branch information
ideoforms committed Nov 7, 2023
1 parent 9a5df46 commit 53181d0
Show file tree
Hide file tree
Showing 90 changed files with 885 additions and 137 deletions.
390 changes: 388 additions & 2 deletions auxiliary/libs/signalflow-stubs/signalflow.pyi

Large diffs are not rendered by default.

26 changes: 22 additions & 4 deletions auxiliary/scripts/generate-node-python-bindings.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
source_files = list(sorted(source_files, key=lambda path: (os.path.dirname(path), path)))


def generate_class_bindings(class_name, parameter_sets, superclass="Node"):
def generate_class_bindings(class_name, parameter_sets, superclass="Node", class_docs=None):
"""
py::class_<Sine, Node, NodeRefTemplate<Sine>>(m, "Sine")
.def(py::init<NodeRef>(), "frequency"_a = NodeRef(440.0))
Expand All @@ -50,9 +50,11 @@ def generate_class_bindings(class_name, parameter_sets, superclass="Node"):
"""
if class_name in omitted_classes:
return ""
if class_docs is None:
class_docs = class_name

output = 'py::class_<{class_name}, {superclass}, NodeRefTemplate<{class_name}>>(m, "{class_name}")\n'.format(
class_name=class_name, superclass=superclass)
output = 'py::class_<{class_name}, {superclass}, NodeRefTemplate<{class_name}>>(m, "{class_name}", "{class_docs}")\n'.format(
class_name=class_name, class_docs=class_docs, superclass=superclass)
for parameter_set in parameter_sets:
parameter_type_list = ", ".join([parameter["type"] for parameter in parameter_set])
output += ' .def(py::init<{parameter_type_list}>()'.format(parameter_type_list=parameter_type_list);
Expand Down Expand Up @@ -117,6 +119,22 @@ def generate_all_bindings():
else:
continue


def extract_docs(doxygen):
lines = doxygen.split("\n")
output = ""
for line in lines:
# start or end of comment
if re.search(r"^\s*/\*", line) or re.search("\*/\s*$", line):
continue
line = re.sub("^\s*\*\s*", "", line)
output = output + line + " "
return output.strip()

class_docs = class_name
if "doxygen" in value:
class_docs = extract_docs(value["doxygen"])

constructor_parameter_sets = []
for method in value["methods"]["public"]:
if method["constructor"]:
Expand All @@ -143,7 +161,7 @@ def generate_all_bindings():
known_parent_classes = ["Node", "StochasticNode"]
if parent_class not in known_parent_classes:
parent_class = "Node"
output += generate_class_bindings(class_name, constructor_parameter_sets, parent_class)
output += generate_class_bindings(class_name, constructor_parameter_sets, parent_class, class_docs=class_docs)
output = output.strip()
output += "\n\n"
if class_name in macos_only_classes:
Expand Down
5 changes: 5 additions & 0 deletions source/include/signalflow/node/buffer/beat-cutter.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Cuts a buffer into segment_count segments, and stutters/jumps with
* the given probabilities.
*---------------------------------------------------------------------------------*/
class BeatCutter : public Node
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/buffer/buffer-looper.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Read and write from a buffer concurrently, with controllable overdub.
*---------------------------------------------------------------------------------*/
class BufferLooper : public Node
{
public:
Expand Down
5 changes: 5 additions & 0 deletions source/include/signalflow/node/buffer/buffer-player.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Plays the contents of the given buffer. start_time/end_time are in seconds.
* When a clock signal is receives, rewinds to the start_time.
*---------------------------------------------------------------------------------*/
class BufferPlayer : public Node
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/buffer/buffer-recorder.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Records the input to a buffer. feedback controls overdub.
*---------------------------------------------------------------------------------*/
class BufferRecorder : public Node
{
public:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Counterpart to FeedbackBufferWriter.
*---------------------------------------------------------------------------------*/
class FeedbackBufferReader : public Node
{
public:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Counterpart to FeedbackBufferReader.
*---------------------------------------------------------------------------------*/
class FeedbackBufferWriter : public Node
{
public:
Expand Down
5 changes: 5 additions & 0 deletions source/include/signalflow/node/buffer/granulator.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@ class Grain
float pan;
};

/**--------------------------------------------------------------------------------*
* Granulator. Generates a grain from the given buffer each time a clock signal
* is received, with the given duration/rate/pan parameters. The input buffer
* can be mono or stereo.
*---------------------------------------------------------------------------------*/
class Granulator : public Node
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/buffer/segment-player.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Trigger segments of a buffer at the given onset positions.
*---------------------------------------------------------------------------------*/
class SegmentPlayer : public Node
{
public:
Expand Down
10 changes: 10 additions & 0 deletions source/include/signalflow/node/control/mouse.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,30 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Outputs the normalised cursor X position, from 0 to 1.
*---------------------------------------------------------------------------------*/
class MouseX : public Node
{
public:
MouseX();
virtual void process(Buffer &out, int num_frames);
};

/**--------------------------------------------------------------------------------*
* Outputs the normalised cursor Y position, from 0 to 1.
*---------------------------------------------------------------------------------*/
class MouseY : public Node
{
public:
MouseY();
virtual void process(Buffer &out, int num_frames);
};

/**--------------------------------------------------------------------------------*
* Outputs 1 if the left mouse button is down, 0 otherwise.
*---------------------------------------------------------------------------------*/
class MouseDown : public Node
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/envelope/adsr.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Attack-decay-sustain-release envelope.
* Sustain portion is held until gate is zero.
*---------------------------------------------------------------------------------*/
class ADSREnvelope : public Node
{
public:
Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/envelope/asr.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Attack-sustain-release envelope.
*---------------------------------------------------------------------------------*/
class ASREnvelope : public Node
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/envelope/detect-silence.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Detects blocks of silence below the threshold value. Used as an auto-free
* node to terminate a Patch after processing is complete.
*---------------------------------------------------------------------------------*/
class DetectSilence : public UnaryOpNode
{
public:
Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/envelope/envelope.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Generic envelope constructor, given an array of levels, times and curves.
*---------------------------------------------------------------------------------*/
class Envelope : public Node
{
public:
Expand Down
6 changes: 6 additions & 0 deletions source/include/signalflow/node/envelope/line.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@

namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Line segment with the given start/end values and duration.
* If loop is true, repeats indefinitely.
* Retriggers on a clock signal.
*---------------------------------------------------------------------------------*/
class Line : public Node
{
public:
Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/envelope/rect.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Rectangular envelope with the given sustain duration.
*---------------------------------------------------------------------------------*/
class RectangularEnvelope : public Node
{
public:
Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/operators/channel-array.h
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Takes an array of inputs and spreads them across multiple channels of output.
*---------------------------------------------------------------------------------*/
class ChannelArray : public Node
{

Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/operators/channel-crossfade.h
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Given a multichannel input, crossfades between channels based on the given
* position within the virtual array, producing a single-channel output.
*---------------------------------------------------------------------------------*/
class ChannelCrossfade : public UnaryOpNode
{

Expand Down
6 changes: 6 additions & 0 deletions source/include/signalflow/node/operators/channel-mixer.h
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Downmix a multichannel input to a lower-channel output. If num_channels is
* greater than one, spreads the input channels across the field.
* If amplitude_compensation is enabled, scale down the amplitude based on the
* ratio of input to output channels.
*---------------------------------------------------------------------------------*/
class ChannelMixer : public UnaryOpNode
{

Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/operators/channel-select.h
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Select a subset of channels from a multichannel input, starting at offset,
* up to a maximum of maximum, with the given step.
*---------------------------------------------------------------------------------*/
class ChannelSelect : public UnaryOpNode
{

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Map a frequency to a MIDI note (where 440Hz = A4 = 69), with floating-point
* output.
*---------------------------------------------------------------------------------*/
class FrequencyToMidiNote : public UnaryOpNode
{

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Map a MIDI note to a frequency (where 440Hz = A4 = 69), supporting floating-point
* input.
*---------------------------------------------------------------------------------*/
class MidiNoteToFrequency : public UnaryOpNode
{

Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/operators/round-to-scale.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Given a frequency input, generates a frequency output that is rounded to the nearest MIDI note.
* (TODO: Not very well named)
*---------------------------------------------------------------------------------*/
class RoundToScale : public UnaryOpNode
{

Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/operators/round.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Round the input to the nearest integer value.
*---------------------------------------------------------------------------------*/
class Round : public UnaryOpNode
{

Expand Down
8 changes: 8 additions & 0 deletions source/include/signalflow/node/operators/scale.h
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Scales the input from a linear range (between a and b)
* to an exponential range (between c and d).
*---------------------------------------------------------------------------------*/
class ScaleLinExp : public UnaryOpNode
{

Expand All @@ -17,6 +21,10 @@ class ScaleLinExp : public UnaryOpNode
NodeRef a, b, c, d;
};

/**--------------------------------------------------------------------------------*
* Scales the input from a linear range (between a and b)
* to a linear range (between c and d).
*---------------------------------------------------------------------------------*/
class ScaleLinLin : public UnaryOpNode
{

Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/oscillators/constant.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

namespace signalflow
{
/**--------------------------------------------------------------------------------*
* Produces a constant value.
*---------------------------------------------------------------------------------*/
class Constant : public Node
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/oscillators/impulse.h
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@
namespace signalflow
{

/**--------------------------------------------------------------------------------*
* Produces a value of 1 at the given frequency, with output of 0 at all other times.
* If frequency is 0, produces a single impulse.
*---------------------------------------------------------------------------------*/
class Impulse : public Node
{
public:
Expand Down
3 changes: 3 additions & 0 deletions source/include/signalflow/node/oscillators/saw-lfo.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

namespace signalflow
{
/**--------------------------------------------------------------------------------*
* Produces a sawtooth LFO, with output ranging from min to max.
*---------------------------------------------------------------------------------*/
class SawLFO : public LFO
{
public:
Expand Down
4 changes: 4 additions & 0 deletions source/include/signalflow/node/oscillators/saw.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

namespace signalflow
{
/**--------------------------------------------------------------------------------*
* Produces a (non-band-limited) sawtooth wave, with the given frequency and
* phase offset. When a reset or trigger is received, resets the phase to zero.
*---------------------------------------------------------------------------------*/
class SawOscillator : public Node
{
public:
Expand Down
Loading

0 comments on commit 53181d0

Please sign in to comment.