/[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 1536 - (show annotations) (download) (as text)
Mon Dec 3 16:41:17 2007 UTC (12 years, 8 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 8691 byte(s)
* added index bounds check to quite new LSCP command
  "GET FILE INSTRUMENT INFO"

1 /***************************************************************************
2 * *
3 * LinuxSampler - modular, streaming capable sampler *
4 * *
5 * Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6 * Copyright (C) 2005 - 2007 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 };
88
89 /**
90 * Returns all managed instruments.
91 *
92 * This method has to be implemented by the descendant.
93 */
94 virtual std::vector<instrument_id_t> Instruments() = 0;
95
96 /**
97 * Returns the current life-time strategy for the given
98 * instrument.
99 *
100 * This method has to be implemented by the descendant.
101 */
102 virtual mode_t GetMode(const instrument_id_t& ID) = 0;
103
104 /**
105 * Change the current life-time strategy for the given
106 * instrument.
107 *
108 * This method has to be implemented by the descendant.
109 */
110 virtual void SetMode(const instrument_id_t& ID, mode_t Mode) = 0;
111
112 /**
113 * Same as SetMode(), but with the difference that this method
114 * won't block.
115 */
116 void SetModeInBackground(const instrument_id_t& ID, mode_t Mode);
117
118 /**
119 * Same as loading the given instrument directly on the given
120 * EngineChannel, but this method will not block, instead it
121 * will load the instrument in a separate thread.
122 *
123 * @param ID - the instrument to be loaded
124 * @param pEngineChannel - on which engine channel the instrument
125 * should be loaded
126 */
127 static void LoadInstrumentInBackground(instrument_id_t ID, EngineChannel* pEngineChannel);
128
129 /**
130 * Returns the name of the given instrument as reflected by its
131 * file.
132 *
133 * This method has to be implemented by the descendant.
134 */
135 virtual String GetInstrumentName(instrument_id_t ID) = 0;
136
137 /**
138 * Returns a textual identifier of the data structure for the
139 * given loaded instrument, which usually reflects the name of
140 * of the library used to load the instrument (i.e. "libgig").
141 *
142 * This method has to be implemented by the descendant.
143 */
144 virtual String GetInstrumentDataStructureName(instrument_id_t ID) = 0;
145
146 /**
147 * Returns the version of the data structure for the given
148 * loaded instrument, which usually reflects the version of the
149 * library which was used to load the instrument (i.e. "3.1.0").
150 *
151 * This method has to be implemented by the descendant.
152 */
153 virtual String GetInstrumentDataStructureVersion(instrument_id_t ID) = 0;
154
155 /**
156 * Spawn an appropriate editor for the given instrument that is
157 * actually capable to handle the instrument's format and data
158 * structure. The instrument editor will be hosted in the
159 * sampler's own process to allow immediate live-editing of the
160 * instrument while playing the instrument in parallel by the
161 * sampler.
162 *
163 * For this to work, instrument editor applications have to
164 * implement the abstract interface class @c InstrumentEditor
165 * and have to generate a plugin DLL that has to be placed into
166 * the appropriate plugin directory of the sampler.
167 *
168 * This method has to be implemented by the descendant.
169 *
170 * @throws InstrumentManagerException - in case no compatible
171 * instrument editor is registered to the sampler
172 */
173 virtual void LaunchInstrumentEditor(instrument_id_t ID) throw (InstrumentManagerException) = 0;
174
175 /**
176 * Returns a list of instrument IDs of the provided instrument
177 * file in case the provided file's format is supported.
178 *
179 * @throws InstrumentManagerException if the format of the
180 * provided instrument file is not supported
181 */
182 virtual std::vector<instrument_id_t> GetInstrumentFileContent(String File) throw (InstrumentManagerException) = 0;
183
184 /**
185 * Get detailed informations about the provided instrument file.
186 *
187 * @throws InstrumentManagerException if the format of the
188 * provided instrument file is not supported
189 */
190 virtual instrument_info_t GetInstrumentInfo(instrument_id_t ID) throw (InstrumentManagerException) = 0;
191 };
192
193 }
194
195 #endif // __LS_INSTRUMENTMANAGER_H__

  ViewVC Help
Powered by ViewVC