/[svn]/linuxsampler/trunk/src/engines/InstrumentManager.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/engines/InstrumentManager.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1850 - (show annotations) (download) (as text)
Sun Mar 1 16:33:22 2009 UTC (15 years, 1 month ago) by persson
File MIME type: text/x-c++hdr
File size: 8973 byte(s)
* fixed crash when a linuxsampler plugin is unloading

1 /***************************************************************************
2 * *
3 * LinuxSampler - modular, streaming capable sampler *
4 * *
5 * Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6 * Copyright (C) 2005 - 2009 Christian Schoenebeck *
7 * *
8 * This library is free software; you can redistribute it and/or modify *
9 * it under the terms of the GNU General Public License as published by *
10 * the Free Software Foundation; either version 2 of the License, or *
11 * (at your option) any later version. *
12 * *
13 * This library is distributed in the hope that it will be useful, *
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16 * GNU General Public License for more details. *
17 * *
18 * You should have received a copy of the GNU General Public License *
19 * along with this library; if not, write to the Free Software *
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
21 * MA 02111-1307 USA *
22 ***************************************************************************/
23
24 #ifndef __LS_INSTRUMENTMANAGER_H__
25 #define __LS_INSTRUMENTMANAGER_H__
26
27 #include "../common/global.h"
28 #include "../common/Exception.h"
29
30 #include <vector>
31
32 namespace LinuxSampler {
33
34 // just symbol prototyping
35 class EngineChannel;
36
37 /**
38 * Will be thrown by InstrumentManager implementations on errors.
39 */
40 class InstrumentManagerException : public Exception {
41 public:
42 InstrumentManagerException(String msg) : Exception(msg) {}
43 };
44
45 /** @brief Abstract interface class for InstrumentManagers.
46 *
47 * Sampler engines should provide an InstrumentManager for allowing
48 * detailed information retrieval and setting of its managed instruments
49 * through this general API.
50 */
51 class InstrumentManager {
52 public:
53 /**
54 * Defines life-time of an instrument.
55 */
56 enum mode_t {
57 ON_DEMAND = 0, ///< Instrument will be loaded when needed, freed once not needed anymore.
58 ON_DEMAND_HOLD = 1, ///< Instrument will be loaded when needed and kept even if not needed anymore.
59 PERSISTENT = 2 ///< Instrument will immediately be loaded and kept all the time.
60 };
61
62 /**
63 * Reflects unique ID of an instrument.
64 */
65 struct instrument_id_t {
66 String FileName; ///< File name of the instrument.
67 uint Index; ///< Index of the instrument within the file.
68
69 // TODO: we should extend operator<() so it will be able to detect that file x and file y are actually the same files, e.g. because one of them is a symlink / share the same inode
70 bool operator<(const instrument_id_t& o) const {
71 return (Index < o.Index || (Index == o.Index && FileName < o.FileName));
72 }
73
74 bool operator==(const instrument_id_t& o) const {
75 return (Index == o.Index && FileName == o.FileName);
76 }
77 };
78
79 /**
80 * Rather abstract informations about an instrument.
81 */
82 struct instrument_info_t {
83 String InstrumentName;
84 String FormatVersion;
85 String Product;
86 String Artists;
87 uint8_t KeyBindings[128];
88 uint8_t KeySwitchBindings[128];
89 };
90
91 /**
92 * Returns all managed instruments.
93 *
94 * This method has to be implemented by the descendant.
95 */
96 virtual std::vector<instrument_id_t> Instruments() = 0;
97
98 /**
99 * Returns the current life-time strategy for the given
100 * instrument.
101 *
102 * This method has to be implemented by the descendant.
103 */
104 virtual mode_t GetMode(const instrument_id_t& ID) = 0;
105
106 /**
107 * Change the current life-time strategy for the given
108 * instrument.
109 *
110 * This method has to be implemented by the descendant.
111 */
112 virtual void SetMode(const instrument_id_t& ID, mode_t Mode) = 0;
113
114 /**
115 * Same as SetMode(), but with the difference that this method
116 * won't block.
117 */
118 void SetModeInBackground(const instrument_id_t& ID, mode_t Mode);
119
120 /**
121 * Same as loading the given instrument directly on the given
122 * EngineChannel, but this method will not block, instead it
123 * will load the instrument in a separate thread.
124 *
125 * @param ID - the instrument to be loaded
126 * @param pEngineChannel - on which engine channel the instrument
127 * should be loaded
128 */
129 static void LoadInstrumentInBackground(instrument_id_t ID, EngineChannel* pEngineChannel);
130
131 /**
132 * Stops the background thread that has been started by
133 * LoadInstrumentInBackground.
134 */
135 static void StopBackgroundThread();
136
137 /**
138 * Returns the name of the given instrument as reflected by its
139 * file.
140 *
141 * This method has to be implemented by the descendant.
142 */
143 virtual String GetInstrumentName(instrument_id_t ID) = 0;
144
145 /**
146 * Returns a textual identifier of the data structure for the
147 * given loaded instrument, which usually reflects the name of
148 * of the library used to load the instrument (i.e. "libgig").
149 *
150 * This method has to be implemented by the descendant.
151 */
152 virtual String GetInstrumentDataStructureName(instrument_id_t ID) = 0;
153
154 /**
155 * Returns the version of the data structure for the given
156 * loaded instrument, which usually reflects the version of the
157 * library which was used to load the instrument (i.e. "3.1.0").
158 *
159 * This method has to be implemented by the descendant.
160 */
161 virtual String GetInstrumentDataStructureVersion(instrument_id_t ID) = 0;
162
163 /**
164 * Spawn an appropriate editor for the given instrument that is
165 * actually capable to handle the instrument's format and data
166 * structure. The instrument editor will be hosted in the
167 * sampler's own process to allow immediate live-editing of the
168 * instrument while playing the instrument in parallel by the
169 * sampler.
170 *
171 * For this to work, instrument editor applications have to
172 * implement the abstract interface class @c InstrumentEditor
173 * and have to generate a plugin DLL that has to be placed into
174 * the appropriate plugin directory of the sampler.
175 *
176 * This method has to be implemented by the descendant.
177 *
178 * @throws InstrumentManagerException - in case no compatible
179 * instrument editor is registered to the sampler
180 */
181 virtual void LaunchInstrumentEditor(instrument_id_t ID) throw (InstrumentManagerException) = 0;
182
183 /**
184 * Returns a list of instrument IDs of the provided instrument
185 * file in case the provided file's format is supported.
186 *
187 * @throws InstrumentManagerException if the format of the
188 * provided instrument file is not supported
189 */
190 virtual std::vector<instrument_id_t> GetInstrumentFileContent(String File) throw (InstrumentManagerException) = 0;
191
192 /**
193 * Get detailed informations about the provided instrument file.
194 *
195 * @throws InstrumentManagerException if the format of the
196 * provided instrument file is not supported
197 */
198 virtual instrument_info_t GetInstrumentInfo(instrument_id_t ID) throw (InstrumentManagerException) = 0;
199 };
200
201 }
202
203 #endif // __LS_INSTRUMENTMANAGER_H__

  ViewVC Help
Powered by ViewVC