Home › The Simple Audio Plug-in Specification › Version 2.0 proposal (with code listings)

Plug-in Host Interface

jwatte's picture
January 14, 2009 - 14:11 — jwatte

Plug-ins are broken into two parts: The part of being a "plug-in" (a DLL or .so that is hosted in a host process), and the part of being an "effect" (an object that can process audio or MIDI data). A single plug-in can provide multiple effects. This allows for code re-use, allows you to wrap some other API into a single plug-in for SAPS. It also allows you to manage a plug-in (such as search paths, etc) logically separately from effects in a host application.

The plug-in interface that a Host sees is described below.

/* The interface that a host provides to a plug-in/effect set */
class ItfHost : public ItfAddressable
{
  public:
    /* Allocate a block for the host. The "safe" size is writable without further memory allocations. */
    /* If you pass 0, then the block is infinitely extendable, but doing so will cause memory allocation, */
    /* and thus should not be done during real-time processing. In general, NewBlock() should not be */
    /* called from the real-time thread. */
    virtual ItfWriteBlock *NewBlock(size64 safeSize) = 0;
    /* The host can create a new window that hosts this effect. That window may be a top-level frame */
    /* window, or it may be a sub-window within a bigger host conglomeration. The "slave" will receive window events. */
    /* In general, OpenWindow() should not be called from the real-time thread. */
    virtual ItfWindow *OpenWindow(WindowConfig const &spec, ItfWindowSlave *slave) = 0;
    /* Send an event to some address. This is a real-time message if atTime is not NULL. */
    virtual bool SendEvent(Address const &addr, size32 type, ItfBlock *block, TimePos const *atTime = NULL) = 0;
    /* Convenience function to not have to allocate an ItfBlock. This is a real-time message if atTime is not NULL. */
    virtual bool SendEvent(Address const &addr, size32 type, void const *data, size64 size, TimePos const *atTime = NULL) = 0;
    /* Allocate an address. This should not be called from the real-time thread. */
    virtual void AllocateAddress(Address *oAddr, ItfEventTarget *target) = 0;
    /* Deallocate an address. This should not be called from the real-time thread.  */
    virtual void DeallocateAddress(Address const &addr) = 0;
 
    virtual void *Extension(wchar_t const *name) = 0;
};
 
/* ItfPlugin is the interface that a plug-in (DLL) provides to the host application */
class ItfPlugin
{
  public:
    /* The plug-in returns some information about itself. */
    virtual PluginInfo const *PluginInfo() = 0;
    /* The plug-in can create some number of effects with some parameters. */
    virtual size32            CountEffects() = 0;
    /* For each effect, describe its name, icon, and capabilities. */
    virtual EffectInfo const *EffectInfo(size32 index) = 0;
    /* Create an instance of a given effect. */
    virtual ItfEffect        *MakeEffect(size32   index) = 0;
 
    virtual void             *Extension(wchar_t const *name) = 0;
};