include/Instrument.h

   1 /*
   2  * Instrument.h - declaration of class Instrument, which provides a
   3  *                standard interface for all instrument plugins
   4  *
   5  * Copyright (c) 2005-2009 Tobias Doerffel <tobydox/at/users.sourceforge.net>
   6  *
   7  * This file is part of Linux MultiMedia Studio - http://lmms.sourceforge.net
   8  *
   9  * This program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public
  20  * License along with this program (see COPYING); if not, write to the
  21  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22  * Boston, MA 02110-1301 USA.
  23  *
  24  */
  25
  26 #ifndef _INSTRUMENT_H
  27 #define _INSTRUMENT_H
  28
  29 #include <QtGui/QWidget>
  30
  31 #include "Plugin.h"
  32 #include "Mixer.h"
  33
  34
  35 // forward-declarations
  36 class InstrumentTrack;
  37 class InstrumentView;
  38 class midiEvent;
  39 class midiTime;
  40 class notePlayHandle;
  41 class track;
  42
  43
  44 /*! \brief Provides a standard interface for all instrument plugins.
  45  *
  46  * All instrument plugins have to derive from this class and implement the
  47  * according virtual methods (see below). An instrument is instantiated by an
  48  * InstrumentTrack.
  49  *
  50  * Instrument plugins can operate in two modes: process audio per note or
  51  * process audio per Mixer period (one continuous audio stream).
  52  * For the latter one, the instrument has to create an InstrumentPlayHandle
  53  * for itself and re-implement #play( sampleFrame * ). When processing audio
  54  * per note, overload the #playNote( notePlayHandle *, sampleFrame * ) and
  55  * #deleteNotePluginData( notePlayHandle * ).
  56  */
  57 class EXPORT Instrument : public Plugin
  58 {
  59 public:
  60         /*! \brief Constructs an Instrument object.
  61          *
  62          * The constructor for Instrument objects.
  63          * \param instrumentTrack The InstrumentTrack this Instrument belongs to.
  64          * \param descriptor A Plugin::Descriptor holding information about the
  65          * instrument plugin.
  66          */
  67         Instrument( InstrumentTrack * instrumentTrack,
  68                                         const Descriptor * descriptor );
  69         virtual ~Instrument();
  70
  71         /*! \brief Generates audio data for the next mixer period.
  72          *
  73          * If the instrument only generates one continuous audio stream (i.e. is
  74          * not capable of generating individual audio streams for each active
  75          * note), it has to overload this method, generate the audio data (should
  76          * use working buffer to improve cache hit rate and eliminate memory
  77          * de-/allocations) and finally call InstrumentTrack::processAudioBuffer()
  78          * and pass NULL for the last parameter.
  79          *
  80          * \param workingBuf A buffer the instrument should operate on (data in it
  81          * is not used after this function returns).
  82          */
  83         virtual void play( sampleFrame * workingBuffer );
  84
  85         /*! \brief Generates audio data for the given NotePlayHandle.
  86          *
  87          * When generating audio data per-note (recommended), the instrument has
  88          * to do this in an overloaded version of this method. It can allocate
  89          * note-specific data objects (sound generators, generator settings etc.)
  90          * in the given NotePlayHandle if NotePlayHandle::totalFramesPlayed()==0.
  91          * Store this data in NotePlayHandle::m_pluginData. See the
  92          * deleteNotePluginData() method below for information how to free the
  93          * allocated data.
  94          * Like play(), call Instrument::processAudioBuffer() after sound data
  95          * has been generated and pass the NotePlayHandle as last parameter.
  96          *
  97          * \param noteToPlay A NotePlayHandle handle for the note to play
  98          * \param workingBuf A buffer the instrument should operate on (data in it
  99          * is not used after this function returns).
 100          */
 101         virtual void playNote( notePlayHandle * noteToPlay,
 102                                         sampleFrame * workingBuf )
 103         {
 104                 Q_UNUSED(noteToPlay)
 105                 Q_UNUSED(workingBuf)
 106         }
 107
 108         /*! \brief Deletes data allocated for playing a certain note.
 109          *
 110          * In Instrument::playNote() an instrument usually allocates data for each
 111          * note to store current state and or generator objects. After a note has
 112          * finished playing, this method is called to free the data that was
 113          * allocated for playing this note. Plugin has to cast
 114          * NotePlayHandle::m_pluginData to according type and delete it.
 115          */
 116         virtual void deleteNotePluginData( notePlayHandle * noteToPlay );
 117
 118         /*! \brief Returns number of frames for notes with unspecified length.
 119          *
 120          * When playing a note with unspecified length (e.g. a step in the
 121          * BB-Editor), the sequencer core somehow has to determine for how long
 122          * to play this note. Plugins can overload this method in order to specify
 123          * the length of such notes (in frames). A sampler for example would return
 124          * the length of the loaded sample at the according pitch.
 125          * Per default this method returns 0 which means the InstrumentTrack will
 126          * look for the longest active envelope and use that value. Otherwise the
 127          * note will not be played.
 128          *
 129          * \param notePlayHandle A NotePlayHandle describing the concerned note.
 130          */
 131         virtual f_cnt_t beatLen( notePlayHandle * n ) const;
 132
 133
 134         /*! \brief Returns number of desired release frames for this instrument.
 135          *
 136          * Some instruments need a certain number of release frames even
 137          * if no envelope is active - such instruments can re-implement this
 138          * method for returning how many frames they at least like to have for
 139          * release.
 140          */
 141         virtual f_cnt_t desiredReleaseFrames() const
 142         {
 143                 return 0;
 144         }
 145
 146         /*! \brief Returns whether instrument is bendable.
 147          *
 148          * This is particularly important for instruments that do not supporting
 149          * pitch bending. If the overloaded function returns false, the pitch bend
 150          * knob will be hidden in InstrumentTrackWindow.
 151          */
 152         inline virtual bool isBendable() const
 153         {
 154                 return true;
 155         }
 156
 157         /*! \brief Returns true if instrument if instrument is MIDI based.
 158          *
 159          * Instruments should return true here if they react to MIDI events passed
 160          * to handleMidiEvent() rather than playNote() & Co.
 161          */
 162         inline virtual bool isMidiBased() const
 163         {
 164                 return false;
 165         }
 166
 167         /*! \brief Allows to handle given MidiEvent.
 168          *
 169          * Subclasses can re-implement this for receiving all incoming MIDI events.
 170          *
 171          * \param midiEvent The MIDI event just received
 172          * \param midiTime An optional offset for the MIDI event within current
 173          * mixer period (e.g. NoteOn at frame X).
 174          */
 175         inline virtual bool handleMidiEvent( const midiEvent &, const midiTime & )
 176         {
 177                 return false;
 178         }
 179
 180         virtual QString fullDisplayName() const;
 181
 182         /*! \brief Instantiates instrument plugin with given name.
 183          *
 184          * Tries to instantiate instrument plugin with given name from available
 185          * plugin files.
 186          *
 187          * \param pluginName The internal identifier for the plugin
 188          * \param instrumentTrack The InstrumentTrack the new instrument should
 189          * belong to.
 190          *
 191          * \return Pointer to instantiated instrument plugin or NULL on failure.
 192          */
 193         static Instrument * instantiate( const QString & pluginName,
 194                                                                         InstrumentTrack * instrumentTrack );
 195
 196         /*! \brief Returns whether this instance belongs to given track. */
 197         virtual bool isFromTrack( const track * _track ) const;
 198
 199         /*! \brief Returns whether the InstrumentTrack this instrument is attached
 200          * to is muted. */
 201         bool isMuted() const;
 202
 203
 204 protected:
 205         inline InstrumentTrack * instrumentTrack() const
 206         {
 207                 return m_instrumentTrack;
 208         }
 209
 210         /*! \brief Internal helper method to apply a release on given buffer.
 211          *
 212          * Instrument plugins may use this to apply a soft fade-out at the end of
 213          * a note. Please note that this is only done if the number of frames
 214          * returned by NotePlayHandle::framesLeft() is equal or below the number
 215          * of frames returned by Instrument::desiredReleaseFrames().
 216          */
 217         void applyRelease( sampleFrame * buf, const notePlayHandle * n );
 218
 219
 220 private:
 221         InstrumentTrack * m_instrumentTrack;
 222
 223 } ;
 224
 225 #endif