LinuxSampler::InstrumentEditor Class Reference

Instrument Editor Interface (external plugin). More...

#include <InstrumentEditor.h>

Inheritance diagram for LinuxSampler::InstrumentEditor:
LinuxSampler::VirtualMidiDevice LinuxSampler::Thread

List of all members.

Public Types

enum  event_type_t { EVENT_TYPE_NOTEON = 1, EVENT_TYPE_NOTEOFF = 2 }

Public Member Functions

virtual int Main (void *pInstrument, String sTypeName, String sTypeVersion, void *pUserData=NULL)=0
 Entry point for the instrument editor's thread.
virtual bool IsTypeSupported (String sTypeName, String sTypeVersion)=0
 The instrument editor has to return true in case it supports the given instrument data structure type and version, it has to return false otherwise.
virtual String Name ()=0
 The instrument editor's name (i.e.
virtual String Version ()=0
 The instrument editor's version (i.e.
virtual String Description ()=0
 Arbitrary textual description of the instrument editor (i.e.
void NotifySamplesToBeRemoved (std::set< void * > Samples)
 Dispatch pending sample removal event.
void NotifySamplesRemoved ()
 Dispatch completed sample removal event.
void NotifyDataStructureToBeChanged (void *pStruct, String sStructType)
 Dispatch pending data structure modification event.
void NotifyDataStructureChanged (void *pStruct, String sStructType)
 Dispatch completed data structure modification event.
void NotifySampleReferenceChanged (void *pOldSample, void *pNewSample)
 Dispatch sample reference changed event.
void Launch (void *pInstrument, String sTypeName, String sTypeVersion, void *pUserData=NULL)
 Launch the instrument editor for the given instrument.
void AddListener (InstrumentEditorListener *pListener)
 Registers object that wants to be notified on events.
void RemoveListener (InstrumentEditorListener *pListener)
 Unregisters object that doesn't want to be notified anymore.
 InstrumentEditor ()
 Constructor.
virtual ~InstrumentEditor ()
 Destructor.
bool SendNoteOnToSampler (uint8_t Key, uint8_t Velocity)
 Sends a MIDI note on event to the sampler.
bool SendNoteOffToSampler (uint8_t Key, uint8_t Velocity)
 Sends a MIDI note off event to the sampler.
bool NotesChanged ()
 Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler during the last call to this method.
bool NoteChanged (uint8_t Key)
 Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler for Key during the last call to this method.
bool NoteIsActive (uint8_t Key)
 Can be called by the virtual MIDI device to check which key / note is currently active by the sampler, e.g.
uint8_t NoteOnVelocity (uint8_t Key)
 Returns the velocity of the last note on event.
uint8_t NoteOffVelocity (uint8_t Key)
 Returns the velocity of the last note off event.
void SendNoteOnToDevice (uint8_t Key, uint8_t Velocity)
 Informs the virtual MIDI device that a note on event occured (e.g.
void SendNoteOffToDevice (uint8_t Key, uint8_t Velocity)
 Informs the virtual MIDI device that a note off event occured (e.g.
bool GetMidiEventFromDevice (event_t &Event)
 Gets the next pending MIDI event from the virtual MIDI device by using a lockfree FIFO.

Protected Member Functions

virtual int Main ()
 This method needs to be implemented by the descendant and is the entry point for the new thread. FIXME: should be protected.
virtual int StartThread ()
virtual int StopThread ()
virtual int SignalStartThread ()
virtual int SignalStopThread ()
void TestCancel ()
virtual bool IsRunning ()
virtual int SetSchedulingPriority ()
virtual int LockMemory ()
virtual void EnableDestructor ()
virtual int Destructor ()

Static Protected Member Functions

static void * allocAlignedMem (size_t boundary, size_t size)
 Allocates an aligned block of memory.
static void freeAlignedMem (void *ptr)
 Frees an aligned block of memory allocated with allocAlignedMem().
static bool lockMemory (void *addr, size_t size)
 Locks a region of memory in physical RAM.
static bool unlockMemory (void *addr, size_t size)
 Unlocks a region of memory in physical RAM.

Protected Attributes

std::set
< InstrumentEditorListener * > 
listeners

Detailed Description

Instrument Editor Interface (external plugin).

LinuxSampler allows to spawn arbitrary instrument editor applications within the sampler's own process. That way instrument editors are able to modify already loaded instruments live or on-the-fly, that is without having to load it again neither on sampler nor on editor side, which is essential for editing large instruments.

Instrument editors have to implement this abstract base class, embedded into a DLL and placed into the respective sampler's library path. The sampler will load these external DLLs as plugins on startup. Whenever there's a request for editing an instrument, the sampler will try to launch a matching registered editor, by calling the respective plugin's Main() method.

Definition at line 50 of file InstrumentEditor.h.


Member Enumeration Documentation

Enumerator:
EVENT_TYPE_NOTEON 
EVENT_TYPE_NOTEOFF 

Definition at line 22 of file VirtualMidiDevice.h.


Constructor & Destructor Documentation

LinuxSampler::InstrumentEditor::InstrumentEditor (  ) 

Constructor.

virtual LinuxSampler::InstrumentEditor::~InstrumentEditor (  )  [virtual]

Destructor.


Member Function Documentation

void LinuxSampler::InstrumentEditor::AddListener ( InstrumentEditorListener pListener  ) 

Registers object that wants to be notified on events.

static void* LinuxSampler::Thread::allocAlignedMem ( size_t  boundary,
size_t  size 
) [inline, static, inherited]

Allocates an aligned block of memory.

Allocated memory blocks need to be freed using freeAlignedMem().

Parameters:
boundary - the alignement boundary, usually a power of 2 e.g. 4 but it can be an arbitrary number between 1 and 128
Parameters:
size - size in bytes to be allocated
Returns:
pointer to the allocated memory block

Definition at line 79 of file Thread.h.

Referenced by LinuxSampler::AudioChannel::AudioChannel().

virtual String LinuxSampler::InstrumentEditor::Description (  )  [pure virtual]

Arbitrary textual description of the instrument editor (i.e.

"Gigasampler and DLS format editor, GTK based").

virtual int LinuxSampler::Thread::Destructor (  )  [virtual, inherited]
virtual void LinuxSampler::Thread::EnableDestructor (  )  [virtual, inherited]
static void LinuxSampler::Thread::freeAlignedMem ( void *  ptr  )  [inline, static, inherited]

Frees an aligned block of memory allocated with allocAlignedMem().

Parameters:
ptr - pointer to the memory block

Definition at line 91 of file Thread.h.

bool LinuxSampler::VirtualMidiDevice::GetMidiEventFromDevice ( event_t Event  )  [inherited]

Gets the next pending MIDI event from the virtual MIDI device by using a lockfree FIFO.

Note: this method is usually only called by the sampler.

Parameters:
Event - destination for writing the next event to
Returns:
true on success, false if no event pending
virtual bool LinuxSampler::Thread::IsRunning (  )  [virtual, inherited]
virtual bool LinuxSampler::InstrumentEditor::IsTypeSupported ( String  sTypeName,
String  sTypeVersion 
) [pure virtual]

The instrument editor has to return true in case it supports the given instrument data structure type and version, it has to return false otherwise.

This method will be called by the sampler to determine which editor is capable to work with a certain instrument.

Parameters:
sTypeName - i.e. "libgig"
Parameters:
sTypeVersion - i.e. "3.0.1"
void LinuxSampler::InstrumentEditor::Launch ( void *  pInstrument,
String  sTypeName,
String  sTypeVersion,
void *  pUserData = NULL 
)

Launch the instrument editor for the given instrument.

The editor will be spawned in its own thread and this method will return as soon as the editor's thread actually started.

Parameters:
pUserData - (optional) arbitrary 3rd party data that might e.g. been passed by InstrumentManager::LaunchInstrumentEditor()
static bool LinuxSampler::Thread::lockMemory ( void *  addr,
size_t  size 
) [inline, static, inherited]

Locks a region of memory in physical RAM.

Parameters:
addr - address of the memory block
Parameters:
size - size of the memory block
Returns:
true if the locking succeded, otherwise false

Definition at line 104 of file Thread.h.

virtual int LinuxSampler::Thread::LockMemory (  )  [virtual, inherited]
virtual int LinuxSampler::InstrumentEditor::Main (  )  [protected, virtual]

This method needs to be implemented by the descendant and is the entry point for the new thread. FIXME: should be protected.

Implements LinuxSampler::Thread.

virtual int LinuxSampler::InstrumentEditor::Main ( void *  pInstrument,
String  sTypeName,
String  sTypeVersion,
void *  pUserData = NULL 
) [pure virtual]

Entry point for the instrument editor's thread.

As the instrument data structure is passed as typeless (void*) pointer, this is not type safe! The implementing instrument editor has to interpret the sTypeName and sTypeVersion arguments to determine if it's able to cast the instrument pointer to a known type and actually be able to work with it.

Parameters:
pInstrument - pointer to the respective instrument object
Parameters:
sTypeName - format of the instrument data structure (i.e. "libgig" )
Parameters:
sTypeVersion - version of the instrument data structure (i.e. "3.0.1" ).
Parameters:
pUserData - (optional) arbitrary 3rd party data that might been passed by Launch()
virtual String LinuxSampler::InstrumentEditor::Name (  )  [pure virtual]
bool LinuxSampler::VirtualMidiDevice::NoteChanged ( uint8_t  Key  )  [inherited]

Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler for Key during the last call to this method.

So this is a asynchronously, "polling" based communication mechanism, which works in conjunction with the NoteIsActive() method call.

bool LinuxSampler::VirtualMidiDevice::NoteIsActive ( uint8_t  Key  )  [inherited]

Can be called by the virtual MIDI device to check which key / note is currently active by the sampler, e.g.

to highlight the respective keys on a graphical virtual keyboard.

See also:
NotesChanged(), NoteChanged()
uint8_t LinuxSampler::VirtualMidiDevice::NoteOffVelocity ( uint8_t  Key  )  [inherited]

Returns the velocity of the last note off event.

No FIFO is used!

uint8_t LinuxSampler::VirtualMidiDevice::NoteOnVelocity ( uint8_t  Key  )  [inherited]

Returns the velocity of the last note on event.

No FIFO is used!

bool LinuxSampler::VirtualMidiDevice::NotesChanged (  )  [inherited]

Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler during the last call to this method.

So this is a asynchronously, "polling" based communication mechanism, which works in conjunction with the NoteIsActive() method call.

void LinuxSampler::InstrumentEditor::NotifyDataStructureChanged ( void *  pStruct,
String  sStructType 
)

Dispatch completed data structure modification event.

Inform the sampler that the by NotifyDataStructureToBeChanged() previously announced data structure has been completely modified.

Parameters:
pStruct - data structure that has been modified
Parameters:
sStructType - name of the data structure (i.e. its C++ struct or class name)
void LinuxSampler::InstrumentEditor::NotifyDataStructureToBeChanged ( void *  pStruct,
String  sStructType 
)

Dispatch pending data structure modification event.

SHOULD be called by the instrument editor before modifying data structures (except samples, which have their own dispatch methods) which could otherwise lead to undesired synchronisation issues and a crash. The respective data structure is passed as a typeless pointer pStruct , so the instrument editor additionally has to pass the name of the data structure (i.e. "gig::Region" ), so the sampler can cast the pointer to an appropriate type. The sampler will react by stopping usage of the respective data structure.

After calling this method, the instrument editor MUST call NotifyDataStructureChanged() , so the sampler can react by resuming usage of the respective data structure for playback.

Parameters:
pStruct - data structure going to be modified
Parameters:
sStructType - name of the data structure (i.e. its C++ struct or class name)
void LinuxSampler::InstrumentEditor::NotifySampleReferenceChanged ( void *  pOldSample,
void *  pNewSample 
)

Dispatch sample reference changed event.

SHOULD be called by the instrument editor after a certain data structure changed its reference / pointer to a sample, so the sampler can react by:

  • Caching the newly referenced sample if necessary.
    • Un-caching the old referenced sample if necessary.

Note: the instrument editor additionally MUST embed this call into the respective NotifyDataStructureToBeChanged() and NotifyDataStructureChanged() calls for announcing the data structure whose sample reference is actually to be changed, so the sampler can react by suspending usage. For example:

  NotifyDataStructureToBeChanged(pDimReg, "gig::DimensionRegion");
  gig::Sample* pOldSample = pDimReg->pSample;
  pDimReg->pSample = pNewSample;
  NotifySampleReferenceChanged(pOldSample, pNewSample);
  NotifyDataStructureChanged(pDimReg, "gig::DimensionRegion");
So calling this method alone is not safe!

Parameters:
pOldSample - previous sample reference
Parameters:
pNewSample - current sample reference
void LinuxSampler::InstrumentEditor::NotifySamplesRemoved (  ) 

Dispatch completed sample removal event.

Inform the sampler that the by NotifySamplesToBeRemoved() previously announced samples have been deleted.

void LinuxSampler::InstrumentEditor::NotifySamplesToBeRemoved ( std::set< void * >  Samples  ) 

Dispatch pending sample removal event.

SHOULD be called by the instrument editor before deleting samples, so the sampler can react by stopping usage of these samples to avoid a crash.

After calling this method, the instrument editor MUST call NotifySamplesRemoved() after it actually deleted the samples, so the sampler can react by i.e. resuming playback of sampler engines.

Parameters:
Samples - list of samples that will be deleted by the instrument editor
void LinuxSampler::InstrumentEditor::RemoveListener ( InstrumentEditorListener pListener  ) 

Unregisters object that doesn't want to be notified anymore.

void LinuxSampler::VirtualMidiDevice::SendNoteOffToDevice ( uint8_t  Key,
uint8_t  Velocity 
) [inherited]

Informs the virtual MIDI device that a note off event occured (e.g.

caused by a MIDI keyboard connected to the sampler). Communication acts asynchronously, that is this method call doesn't lock in any way and returns immediately. It is thus realtime safe.

Note: this method is usually only called by the sampler.

See also:
ActiveNotesChanged(), NoteIsActive()
bool LinuxSampler::VirtualMidiDevice::SendNoteOffToSampler ( uint8_t  Key,
uint8_t  Velocity 
) [inherited]

Sends a MIDI note off event to the sampler.

Returns:
true on success, false if internal FIFO full (or provided values invalid)
void LinuxSampler::VirtualMidiDevice::SendNoteOnToDevice ( uint8_t  Key,
uint8_t  Velocity 
) [inherited]

Informs the virtual MIDI device that a note on event occured (e.g.

caused by a MIDI keyboard connected to the sampler). Communication acts asynchronously, that is this method call doesn't lock in any way and returns immediately. It is thus realtime safe.

Note: this method is usually only called by the sampler.

See also:
ActiveNotesChanged(), NoteIsActive()
bool LinuxSampler::VirtualMidiDevice::SendNoteOnToSampler ( uint8_t  Key,
uint8_t  Velocity 
) [inherited]

Sends a MIDI note on event to the sampler.

Returns:
true on success, false if internal FIFO full (or provided values invalid)
virtual int LinuxSampler::Thread::SetSchedulingPriority (  )  [virtual, inherited]
virtual int LinuxSampler::Thread::SignalStartThread (  )  [virtual, inherited]
virtual int LinuxSampler::Thread::SignalStopThread (  )  [virtual, inherited]
virtual int LinuxSampler::Thread::StartThread (  )  [virtual, inherited]
virtual int LinuxSampler::Thread::StopThread (  )  [virtual, inherited]
void LinuxSampler::Thread::TestCancel (  )  [inline, inherited]

Definition at line 56 of file Thread.h.

static bool LinuxSampler::Thread::unlockMemory ( void *  addr,
size_t  size 
) [inline, static, inherited]

Unlocks a region of memory in physical RAM.

Parameters:
addr - address of the memory block
Parameters:
size - size of the memory block
Returns:
true if the unlocking succeded, otherwise false

Definition at line 119 of file Thread.h.

virtual String LinuxSampler::InstrumentEditor::Version (  )  [pure virtual]

The instrument editor's version (i.e.

"0.0.1" ).


Member Data Documentation

Definition at line 224 of file InstrumentEditor.h.


The documentation for this class was generated from the following file:
Generated on Sat Jan 28 08:43:18 2012 for linuxsampler by  doxygen 1.6.3