DSSI support libraries: DSSIPlugin Class Reference

List of all members.


Public Member Functions
Instantiation class
virtual	~DSSIPlugin ()
	A virtual destructor is needed since we have virtual member functions.
virtual void	activate ()
	Override this function if you need to do something on activation.
virtual void	deactivate ()
	Override this function if you need to do something on deactivation.
Control class
virtual char *	configure (const char key, const char value)
	Override this function if you use configuration keys.
virtual int	get_midi_controller_for_port (unsigned long port)
	If you want to map MIDI controllers to your control ports you will need to override this function.
virtual const DSSI_Program_Descriptor *	get_program (unsigned long index)
	Override this function if your plugin supports programs.
virtual bool	shm_attached (void *shm, size_t size)
	Override this function if your plugin uses shared memory.
virtual void	shm_detach_request (void *shm)
	This function is called when the GUI no longer wants to use the shared memory segment pointed to by `shm`.
Audio class
virtual void	run (unsigned long sample_count)
	This function is only used if you have not set the DSSI_RECEIVES_MIDI flag for your plugin, or if the host for some reason decides to use it instead of run_synth().
virtual void	run_synth (unsigned long sample_count, snd_seq_event_t *events, unsigned long event_count)
	This function does the actual work.
virtual void	select_program (unsigned long bank, unsigned long program)
	This function allows the host to select the synth program.
virtual void	connect_port (unsigned long port, LADSPA_Data *data_location)
	This function copies the pointer `data_location` to the port array.
Protected Member Functions
void	shm_detach (void *shm)
	This function detaches a shared memory segment previously given as an argument to shm_attached().
Protected Attributes
std::vector< LADSPA_Data * >	m_ports
	This vector holds the pointers to the port buffers for this plugin instance.
Friends
template<class T>
size_t	register_dssi (const std::string &label, LADSPA_Properties properties, const std::string &name, const std::string &maker, const std::string &copyright, const DSSIPortList &ports, DSSIFeatureMask features)
	This is the function you should use to register your DSSI plugin class.

Detailed Description

It has default implementations for all functions, so you only have to implement the functions that you need (for example run_synth()). Any subclass must have a constructor that takes a single unsigned long as parameter, otherwise it will not work with the template function register_dssi().

The virtual member functions are divided into three groups; instantiation, control, and audio. These functions should obey the rules described in the DSSI RFC. Two functions, shm_attached() and shm_detach_request(), are not described in the RFC - they are a part of the memory handling mechanism that allows you to create shared memory segments in the UI and pass them to the plugin so you can do things like waveform displays and VU-meters in the UI. These functions should obey the same rules as the other control functions.

#include <cstring>
#include "dssiplugin.hpp"

class MyPlugin : public DSSIPlugin {
public:
  MyPlugin(unsigned long) { }
  void run(unsigned long sample_count) {
    std::memcpy(m_ports[1], m_ports[0], sizeof(LADSPA_Data) * sample_count);
  }
};
    
void initialise() __attribute__((constructor));
void initialise() {
  DSSIPortList ports;
  ports.add_port(LADSPA_PORT_INPUT | LADSPA_PORT_AUDIO, "Input");
  ports.add_port(LADSPA_PORT_OUTPUT | LADSPA_PORT_AUDIO, "Output");
  register_dssi<MyPlugin>("my_plugin", 0, "My plugin", "Lars Luthman",
                          "GPL", ports, DSSI_NO_FEATURES);
}

If the above code is compiled and linked with -ldssi_plugin into a shared module, it should be a fully functional (but not very useful) DSSI plugin.

The line void initialise() __attribute__((constructor)); tells GCC that the function initialise() should be executed when the plugin is loaded. You should use this method instead of naming the function _init(), which is deprecated. For other compilers you may have to do something different.

static struct Init {
  Init() {
    DSSIPortList ports;
    ports.add_port(LADSPA_PORT_INPUT | LADSPA_PORT_AUDIO, "Input");
    ports.add_port(LADSPA_PORT_OUTPUT | LADSPA_PORT_AUDIO, "Output");
    register_dssi<MyPlugin>("my_plugin", 0, "My plugin", "Lars Luthman",
                            "GPL", ports, DSSI_NO_FEATURES);
  }
} init;

Constructor & Destructor Documentation

DSSIPlugin::~DSSIPlugin ( ) [virtual]

A virtual destructor is needed since we have virtual member functions.

Member Function Documentation

virtual void DSSIPlugin::activate ( ) [inline, virtual]

Override this function if you need to do something on activation.

virtual char* DSSIPlugin::configure	(	const char *	key,
		const char *	value
	)	`[inline, virtual]`

Override this function if you use configuration keys.

virtual void DSSIPlugin::connect_port	(	unsigned long	port,
		LADSPA_Data *	data_location
	)	`[inline, virtual]`

This function copies the pointer data_location to the port array.

You shouldn't override this unless you know what you are doing.

virtual void DSSIPlugin::deactivate ( ) [inline, virtual]

Override this function if you need to do something on deactivation.

virtual int DSSIPlugin::get_midi_controller_for_port ( unsigned long port ) [inline, virtual]

If you want to map MIDI controllers to your control ports you will need to override this function.

If the flag DSSI_RECEIVES_MIDI is not set it will never be called.

virtual const DSSI_Program_Descriptor* DSSIPlugin::get_program ( unsigned long index ) [inline, virtual]

Override this function if your plugin supports programs.

It should return a pointer to a DSSI_Program_Descriptor for the given index, or NULL if there is no program with that index. If the flag DSSI_HAS_PROGRAMS is not set, this function will never be called.

virtual void DSSIPlugin::run ( unsigned long sample_count ) [inline, virtual]

This function is only used if you have not set the DSSI_RECEIVES_MIDI flag for your plugin, or if the host for some reason decides to use it instead of run_synth().

The default implementation simply calls run_synth() with no MIDI events - only override it if you are writing a plugin that doesn't use MIDI.

virtual void DSSIPlugin::run_synth	(	unsigned long	sample_count,
		snd_seq_event_t *	events,
		unsigned long	event_count
	)	`[inline, virtual]`

This function does the actual work.

You most likely want to override it (unless your plugin does not handle MIDI events, in which case you should override run() instead). If the flag DSSI_RECEIVES_MIDI is not set, this function will never be called.

virtual void DSSIPlugin::select_program	(	unsigned long	bank,
		unsigned long	program
	)	`[inline, virtual]`

This function allows the host to select the synth program.

Override it only if your plugin supports programs. If the flag DSSI_HAS_PROGRAMS is not set, this function will never be called.

virtual bool DSSIPlugin::shm_attached	(	void *	shm,
		size_t	size
	)	`[inline, virtual]`

Override this function if your plugin uses shared memory.

It is called when the plugin has received a request from the GUI to attach to a shared memory segment. shm is a pointer to the shared segment. If you want to keep the shared segment you should return NULL from this function. If you return a non-null value the memory segment will be detached and the return value will be treated as an error message returned from configure(). This function is never called unless the DSSI_USES_SHM flag is set.

void DSSIPlugin::shm_detach ( void * shm ) [protected]

This function detaches a shared memory segment previously given as an argument to shm_attached().

Do not override it unless you really know what you are doing.

virtual void DSSIPlugin::shm_detach_request ( void * shm ) [inline, virtual]

This function is called when the GUI no longer wants to use the shared memory segment pointed to by shm.

The default implementation calls shm_detach() to detach the segment immediately. If you are using the segment in audio class functions this may not be what you want, since an audio class function running concurrently with this function may be using the segment right now. In that case you need to mark the segment for detachment somehow and call shm_detach() later when you are sure that the segment is not being used. Any shared segments that haven't been detached when this plugin object is destroyed will then be detached automatically in the destructor.

Friends And Related Function Documentation

template<class T>
size_t register_dssi	(	const std::string &	label,
		LADSPA_Properties	properties,
		const std::string &	name,
		const std::string &	maker,
		const std::string &	copyright,
		const DSSIPortList &	ports,
		DSSIFeatureMask	features
	)	`[friend]`

This is the function you should use to register your DSSI plugin class.

It should be called when the library is loaded, so you can write an initialisation function with the constructor attribute and put it there. Since this is a template function but the template type isn't one of the parameters, you need to give it explicitly like this:

    register_dssi<MyPluginClass>("my_plugin", 0, "My Plugin", "Me", "GPL", my_ports);

Parameters:

	label	The LADSPA label for this plugin
	properties	The LADSPA properties for this plugin
	name	The LADSPA name for this plugin
	maker	Your name!
	copyright	The copyright for this plugin (for example "GPL")
	ports	The port list for this DSSI plugin.
	features	The enabled features for this plugin.

Member Data Documentation

std::vector<LADSPA_Data*> DSSIPlugin::m_ports [protected]

This vector holds the pointers to the port buffers for this plugin instance.

It is protected because the subclasses need to access it.

DSSIPlugin Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation