Patcher

Contents

Patcher#

namespace YSE

Public API of libYSE — sound playback, mixing, and 3D positional audio.

Entry points: YSE::System (lifecycle and audio device), YSE::Listener (3D origin), YSE::sound (a playable source), YSE::channel (mixing tree), YSE::reverb (positioned reverb zone), YSE::patcher (modular DSP graph), YSE::player (note sequencer). Sub-namespaces group domain-specific types: YSE::DSP for signal processing, YSE::MIDI for MIDI I/O, YSE::MUSIC for note / chord / motif primitives.

Note

Apart from their constructors, the oscillator and vcf classes must only be invoked from inside a DSP callback / process body.

class oscHandler#

Base class for receiving OSC-style messages from a patcher.

Subclass and override the Send overloads to forward patcher output to an external system (OSC client, game logic, telemetry, …). Register the instance with patcher::SetOscHandler.

Public Functions

inline virtual void Send(const std::string&)#: Called when the patcher emits a bare bang (address only).

inline virtual void Send(const std::string&, int)#: Called when the patcher emits an integer value.

inline virtual void Send(const std::string&, float)#: Called when the patcher emits a float value.

inline virtual void Send(const std::string&, const std::string&)#: Called when the patcher emits a string value.

inline virtual ~oscHandler()#

class patcher#

Modular DSP / event graph (Max/MSP-style patcher).

Programmatically build a node graph, connect inlets to outlets, and optionally save/load it as JSON. A patcher can be used directly via the PassBang / PassData entry points, or wrapped into a YSE::sound via YSE::sound::create(patcher&, ...) to use it as an audio source.

Object type strings ("~sine", ".+", "~lp" etc.) are defined in YSE::OBJ — see patcher/pObjectList.hpp.

See also

See also

Public Functions

patcher()#

~patcher()#

void create(int mainOutputs)#: Initialise the patcher with mainOutputs audio outputs.

YSE::pHandle *CreateObject(const std::string &type, const std::string &args = std::string())#

Add an object to the patcher.

Parameters:

type – Type identifier (see YSE::OBJ).
args – Optional creation arguments, formatted as the object expects.

Returns:

Handle to the new object — owned by the patcher.

void DeleteObject(YSE::pHandle *obj)#: Remove an object from the patcher.

void Clear()#: Remove every object from the patcher.

void Connect(YSE::pHandle *from, int outlet, YSE::pHandle *to, int inlet)#: Connect from’s outlet to to’s inlet.

void Disconnect(YSE::pHandle *from, int outlet, YSE::pHandle *to, int inlet)#: Remove the connection from from’s outlet to to’s inlet.

std::string DumpJSON()#: Serialise the current graph to JSON.

void ParseJSON(const std::string &content)#: Replace the current graph with the contents of a JSON dump.

unsigned int Objects()#: Number of objects in the patcher.

Note

Most useful after ParseJSON to walk the loaded graph.

YSE::pHandle *GetHandleFromList(unsigned int obj)#: Object at position obj in the list (0-indexed).

YSE::pHandle *GetHandleFromID(unsigned int obj)#: Object whose ID is obj.

bool PassBang(const std::string &to)#

Send a bang to the named receive object.

Returns false if no such receiver exists.

bool PassData(int value, const std::string &to)#: Send an integer to the named receive object.

bool PassData(float value, const std::string &to)#: Send a float to the named receive object.

bool PassData(const std::string &value, const std::string &to)#: Send a string to the named receive object.

void SetOscHandler(oscHandler *handle)#: Install an OSC handler for outgoing messages.

Public Static Functions

static bool IsValidObject(const char *type)#: Whether type is a known object type identifier.

Private Members

PATCHER::patcherImplementation *pimpl#

Friends

friend class YSE::sound

namespace YSE

Public API of libYSE — sound playback, mixing, and 3D positional audio.

Entry points: YSE::System (lifecycle and audio device), YSE::Listener (3D origin), YSE::sound (a playable source), YSE::channel (mixing tree), YSE::reverb (positioned reverb zone), YSE::patcher (modular DSP graph), YSE::player (note sequencer). Sub-namespaces group domain-specific types: YSE::DSP for signal processing, YSE::MIDI for MIDI I/O, YSE::MUSIC for note / chord / motif primitives.

Note

Apart from their constructors, the oscillator and vcf classes must only be invoked from inside a DSP callback / process body.

class pHandle#

Handle to a single object inside a patcher.

Returned by patcher::CreateObject and the various lookup methods. Use it to feed external data into the object’s inlets, inspect its outlets, read or write GUI metadata, and walk the loaded graph after patcher::ParseJSON.

The patcher owns the underlying object — do not delete the handle directly; call patcher::DeleteObject instead.

Public Functions

pHandle(PATCHER::pObject *obj)#

Construct a handle around a patcher object.

Engine-internal.

const char *Type() const#: Type identifier of the underlying object (see YSE::OBJ).

void SetBang(unsigned int inlet)#: Send a bang to inlet inlet.

void SetIntData(unsigned int inlet, int value)#: Send an integer to inlet inlet.

void SetFloatData(unsigned int inlet, float value)#: Send a float to inlet inlet.

void SetListData(unsigned int inlet, const std::string &value)#: Send a string or list to inlet inlet.

void SetParams(const std::string &args)#: Reconfigure the object using a new argument string.

std::string GetGuiProperty(const std::string &key)#: Read a GUI property by key (used by patcher editors).

void SetGuiProperty(const std::string &key, const std::string &value)#: Write a GUI property.

int GetInputs()#: Number of inlets on this object.

int GetOutputs()#: Number of outlets on this object.

bool IsDSPInput(unsigned int inlet)#: Whether inlet inlet accepts an audio signal.

YSE::OUT_TYPE OutputDataType(unsigned int pin)#: Data type produced by outlet pin.

std::string GetName()#: Display name of this object (set in the patcher source).

std::string GetParams()#: Original creation argument string.

unsigned int GetID()#: Unique patcher-assigned ID.

unsigned int GetConnections(unsigned int outlet)#: Number of connections leaving outlet outlet.

unsigned int GetConnectionTarget(unsigned int outlet, unsigned int connection)#: ID of the target object of one connection from outlet outlet.

unsigned int GetConnectionTargetInlet(unsigned int outlet, unsigned int connection)#: Inlet on the target that this connection reaches.

std::string GetGuiValue()#: Current GUI display value for objects that have one (sliders, toggles, …).

Private Members

PATCHER::pObject *object#

Defines

DEFOBJ(name, tag)#

namespace YSE

Public API of libYSE — sound playback, mixing, and 3D positional audio.

Entry points: YSE::System (lifecycle and audio device), YSE::Listener (3D origin), YSE::sound (a playable source), YSE::channel (mixing tree), YSE::reverb (positioned reverb zone), YSE::patcher (modular DSP graph), YSE::player (note sequencer). Sub-namespaces group domain-specific types: YSE::DSP for signal processing, YSE::MIDI for MIDI I/O, YSE::MUSIC for note / chord / motif primitives.

Note

Apart from their constructors, the oscillator and vcf classes must only be invoked from inside a DSP callback / process body.

struct OBJ#

Compile-time string identifiers for patcher object types.

Pass any of these constants to patcher::CreateObject instead of the raw string literal. The ~ prefix marks DSP / audio-rate objects, . marks control-rate objects.

DSP generators: D_SINE, D_SAW, D_NOISE.
DSP math: D_ADD, D_MULTIPLY, D_CLIP.
DSP filters: D_LOWPASS, D_HIGHPASS, D_BANDPASS, D_VCF.
I/O: D_DAC, D_ADC, D_LINE, D_OUT.
Control: G_INT, G_FLOAT, G_SLIDER, G_METRO, G_RANDOM.
Messaging: G_SEND, G_RECEIVE, G_ROUTE, G_GATE, G_SWITCH.
MIDI: M_OUT, M_NOTEON, M_NOTEOFF, M_CONTROL.
Conversion: MIDITOFREQUENCY, FREQUENCYTOMIDI.

Public Static Attributes

static constexpr char const *PATCHER = "patcher"#

static constexpr char const *D_DAC = "~dac"#

static constexpr char const *D_ADC = "~adc"#

static constexpr char const *G_RECEIVE = ".r"#

static constexpr char const *G_SEND = ".s"#

static constexpr char const *D_OUT = "~out"#

static constexpr char const *D_LINE = "~line"#

static constexpr char const *D_SINE = "~sine"#

static constexpr char const *D_SAW = "~saw"#

static constexpr char const *D_NOISE = "~noise"#

static constexpr char const *G_INT = ".i"#

static constexpr char const *G_FLOAT = ".f"#

static constexpr char const *G_SLIDER = ".slider"#

static constexpr char const *G_BUTTON = ".b"#

static constexpr char const *G_TOGGLE = ".t"#

static constexpr char const *G_MESSAGE = ".m"#

static constexpr char const *G_LIST = ".l"#

static constexpr char const *G_TEXT = ".text"#

static constexpr char const *G_COUNTER = ".counter"#

static constexpr char const *G_SWITCH = ".switch"#

static constexpr char const *G_GATE = ".gate"#

static constexpr char const *G_ROUTE = ".route"#

static constexpr char const *G_ADD = ".+"#

static constexpr char const *G_SUBSTRACT = ".-"#

static constexpr char const *G_MULTIPLY = ".*"#

static constexpr char const *G_DIVIDE = "./"#

static constexpr char const *G_RANDOM = ".random"#

static constexpr char const *G_METRO = ".metro"#

static constexpr char const *D_ADD = "~+"#

static constexpr char const *D_SUBSTRACT = "~-"#

static constexpr char const *D_MULTIPLY = "~*"#

static constexpr char const *D_DIVIDE = "~/"#

static constexpr char const *D_CLIP = "~clip"#

static constexpr char const *MIDITOFREQUENCY = ".mtof"#

static constexpr char const *FREQUENCYTOMIDI = ".ftom"#

static constexpr char const *D_LOWPASS = "~lp"#

static constexpr char const *D_HIGHPASS = "~hp"#

static constexpr char const *D_BANDPASS = "~bp"#

static constexpr char const *D_VCF = "~vcf"#

static constexpr char const *M_OUT = ".midiout"#

static constexpr char const *M_NOTEON = ".noteon"#

static constexpr char const *M_NOTEOFF = ".noteoff"#

static constexpr char const *M_CONTROL = ".controlchange"#

static constexpr char const *M_POLYPRESS = ".polypressure"#

static constexpr char const *M_CHANPRESS = ".channelpressure"#

static constexpr char const *M_PROGCHANGE = ".programchange"#

Object reference

Patcher object reference