Overview
The pd::Instance class wraps libpd and provides a C++ interface for managing Pure Data instances. It handles DSP processing, MIDI events, message passing, patch loading, and communication between the GUI and the Pure Data audio engine.
Location: Source/Pd/Instance.h
Class Declaration
namespace pd {
class Instance : public AsyncUpdater {
// ...
};
}
Constructor and Initialization
Creates a new Pure Data instance. Each instance is isolated from others. void initialisePd(String& pdlua_version);
DSP Control
void prepareDSP(int nins, int nouts, double samplerate);
nins - Number of input channelsnouts - Number of output channelssamplerate - Sample rate in Hz
void startDSP();
void releaseDSP();
void performDSP(float const* inputs, float* outputs);
inputs - Interleaved input audio bufferoutputs - Interleaved output audio buffer
Buffer size is determined by getBlockSize().static int getBlockSize();
Sending MIDI to Pure Data
void sendNoteOn(int channel, int pitch, int velocity) const;
void sendControlChange(int channel, int controller, int value) const;
void sendProgramChange(int channel, int value) const;
void sendPitchBend(int channel, int value) const;
void sendAfterTouch(int channel, int value) const;
void sendPolyAfterTouch(int channel, int pitch, int value) const;
void sendMidiByte(int port, int byte) const;
void sendSysEx(int port, int byte) const;
void sendSysRealTime(int port, int byte) const;
Receiving MIDI from Pure Data
These are pure virtual methods that must be implemented by subclasses:
virtual void receiveNoteOn(int channel, int pitch, int velocity) = 0;
virtual void receiveControlChange(int channel, int controller, int value) = 0;
virtual void receiveProgramChange(int channel, int value) = 0;
virtual void receivePitchBend(int channel, int value) = 0;
virtual void receiveAftertouch(int channel, int value) = 0;
virtual void receivePolyAftertouch(int channel, int pitch, int value) = 0;
virtual void receiveMidiByte(int port, int byte) = 0;
[noteout], [ctlout], etc.).Sending Messages to Pure Data
void sendBang(char const* receiver) const;
instance->sendBang("trigger-event");
void sendFloat(char const* receiver, float value) const;
instance->sendFloat("frequency", 440.0f);
void sendSymbol(char const* receiver, char const* symbol) const;
instance->sendSymbol("mode", "lowpass");
void sendList(char const* receiver, SmallArray<pd::Atom> const& list) const;
SmallArray<pd::Atom> list = {1.0f, 2.0f, 3.0f};
instance->sendList("data-receiver", list);
void sendMessage(char const* receiver, char const* msg, SmallArray<pd::Atom> const& list) const;
SmallArray<pd::Atom> args = {100.0f, 200.0f};
instance->sendMessage("osc", "range", args);
void sendDirectMessage(void* object, SmallString const& msg, SmallArray<Atom>&& list);
void sendDirectMessage(void* object, SmallArray<pd::Atom>&& list);
void sendDirectMessage(void* object, SmallString const& msg);
void sendDirectMessage(void* object, float msg);
Patch Management
Patch::Ptr openPatch(File const& toOpen);
auto patch = instance->openPatch(File("/path/to/synth.pd"));
if (patch) {
DBG("Patch loaded successfully");
}
patches
SmallArray<pd::Patch::Ptr>
SmallArray<pd::Patch::Ptr, 16> patches;
Message Listeners
void registerMessageListener(void* object, MessageListener* messageListener);
void unregisterMessageListener(MessageListener* messageListener);
Thread Safety
void lockAudioThread();
void unlockAudioThread();
instance->lockAudioThread();
// Safe to modify Pure Data state here
instance->sendFloat("param", value);
instance->unlockAudioThread();
void enqueueFunctionAsync(std::function<void()> const& fn);
template<typename T>
void enqueueFunctionAsync(WeakReference& ref, std::function<void(T*)> const& fn);
instance->enqueueFunctionAsync([this]() {
// This runs on the message thread
updateGUI();
});
Symbol Generation
t_symbol* generateSymbol(String const& symbol) const;
t_symbol* generateSymbol(SmallString const& symbol) const;
t_symbol* generateSymbol(char const* symbol) const;
Console and Logging
void logMessage(String const& message);
void logError(String const& message);
void logWarning(String const& message);
std::deque<std::tuple<void*, String, int, int, int>>& getConsoleMessages() const;
std::deque<std::tuple<void*, String, int, int, int>>& getConsoleHistory() const;
Virtual Methods (Must Implement)
virtual void receiveSysMessage(SmallString const& selector, SmallArray<pd::Atom> const& list) = 0;
virtual void updateConsole(int numMessages, bool newWarning) = 0;
virtual void titleChanged() = 0;
Properties
Pointer to the underlying libpd instance.
Pure Data receiver for system messages.
Pure Data receiver for parameter messages.
Mutex for thread-safe audio operations.
Usage Example
// Create and initialize instance
class MyPdInstance : public pd::Instance {
public:
void receiveNoteOn(int ch, int pitch, int vel) override {
DBG("Note: " + String(pitch));
}
void receiveSysMessage(SmallString const& sel, SmallArray<pd::Atom> const& list) override {
// Handle system messages
}
void updateConsole(int num, bool warn) override { }
void titleChanged() override { }
// ... implement other virtual methods
};
MyPdInstance instance;
String pdluaVer;
instance.initialisePd(pdluaVer);
instance.prepareDSP(2, 2, 48000.0);
instance.startDSP();
// Load and use a patch
auto patch = instance.openPatch(File("synth.pd"));
instance.sendFloat("frequency", 440.0f);
instance.sendBang("trigger");
// In audio callback
instance.performDSP(inputs, outputs);
See Also
PluginProcessor - Inherits from pd::Instancepd::Patch - Patch managementpd::Atom - Pure Data atom wrapperMessageListener - Message listening interface
