src/engines/InstrumentManager.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005 - 2007 Christian Schoenebeck                       *
 *                                                                         *
 *   This library is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This library is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this library; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __LS_INSTRUMENTMANAGER_H__
#define __LS_INSTRUMENTMANAGER_H__

#include "../common/global.h"
#include "../common/Exception.h"

#include <vector>

namespace LinuxSampler {

    // just symbol prototyping
    class EngineChannel;

    /**
     * Will be thrown by InstrumentManager implementations on errors.
     */
    class InstrumentManagerException : public Exception {
        public:
            InstrumentManagerException(String msg) : Exception(msg) {}
    };

    /** @brief Abstract interface class for InstrumentManagers.
     *
     * Sampler engines should provide an InstrumentManager for allowing
     * detailed information retrieval and setting of its managed instruments
     * through this general API.
     */
    class InstrumentManager {
        public:
            /**
             * Defines life-time of an instrument.
             */
            enum mode_t {
                ON_DEMAND      = 0, ///< Instrument will be loaded when needed, freed once not needed anymore.
                ON_DEMAND_HOLD = 1, ///< Instrument will be loaded when needed and kept even if not needed anymore.
                PERSISTENT     = 2  ///< Instrument will immediately be loaded and kept all the time.
            };

            /**
             * Reflects unique ID of an instrument.
             */
            struct instrument_id_t {
                String FileName; ///< File name of the instrument.
                uint   Index;    ///< Index of the instrument within the file.

                // 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
                bool operator<(const instrument_id_t& o) const {
                    return (Index < o.Index || (Index == o.Index && FileName < o.FileName));
                }

                bool operator==(const instrument_id_t& o) const {
                    return (Index == o.Index && FileName == o.FileName);
                }
            };

            /**
             * Rather abstract informations about an instrument.
             */
            struct instrument_info_t {
                String InstrumentName;
                String FormatVersion;
                String Product;
                String Artists;
            };

            /**
             * Returns all managed instruments.
             *
             * This method has to be implemented by the descendant.
             */
            virtual std::vector<instrument_id_t> Instruments() = 0;

            /**
             * Returns the current life-time strategy for the given
             * instrument.
             *
             * This method has to be implemented by the descendant.
             */
            virtual mode_t GetMode(const instrument_id_t& ID) = 0;

            /**
             * Change the current life-time strategy for the given
             * instrument.
             *
             * This method has to be implemented by the descendant.
             */
            virtual void SetMode(const instrument_id_t& ID, mode_t Mode) = 0;

            /**
             * Same as SetMode(), but with the difference that this method
             * won't block.
             */
            void SetModeInBackground(const instrument_id_t& ID, mode_t Mode);

            /**
             * Same as loading the given instrument directly on the given
             * EngineChannel, but this method will not block, instead it
             * will load the instrument in a separate thread.
             *
             * @param ID - the instrument to be loaded
             * @param pEngineChannel - on which engine channel the instrument
             *                         should be loaded
             */
            static void LoadInstrumentInBackground(instrument_id_t ID, EngineChannel* pEngineChannel);

            /**
             * Returns the name of the given instrument as reflected by its
             * file.
             *
             * This method has to be implemented by the descendant.
             */
            virtual String GetInstrumentName(instrument_id_t ID) = 0;

            /**
             * Returns a textual identifier of the data structure for the
             * given loaded instrument, which usually reflects the name of
             * of the library used to load the instrument (i.e. "libgig").
             *
             * This method has to be implemented by the descendant.
             */
            virtual String GetInstrumentDataStructureName(instrument_id_t ID) = 0;

            /**
             * Returns the version of the data structure for the given
             * loaded instrument, which usually reflects the version of the
             * library which was used to load the instrument (i.e. "3.1.0").
             *
             * This method has to be implemented by the descendant.
             */
            virtual String GetInstrumentDataStructureVersion(instrument_id_t ID) = 0;

            /**
             * Spawn an appropriate editor for the given instrument that is
             * actually capable to handle the instrument's format and data
             * structure. The instrument editor will be hosted in the
             * sampler's own process to allow immediate live-editing of the
             * instrument while playing the instrument in parallel by the
             * sampler.
             *
             * For this to work, instrument editor applications have to
             * implement the abstract interface class @c InstrumentEditor
             * and have to generate a plugin DLL that has to be placed into
             * the appropriate plugin directory of the sampler.
             *
             * This method has to be implemented by the descendant.
             *
             * @throws InstrumentManagerException - in case no compatible
             *         instrument editor is registered to the sampler
             */
            virtual void LaunchInstrumentEditor(instrument_id_t ID) throw (InstrumentManagerException) = 0;

            /**
             * Returns a list of instrument IDs of the provided instrument
             * file in case the provided file's format is supported.
             *
             * @throws InstrumentManagerException if the format of the
             *         provided instrument file is not supported
             */
            virtual std::vector<instrument_id_t> GetInstrumentFileContent(String File) throw (InstrumentManagerException) = 0;

            /**
             * Get detailed informations about the provided instrument file.
             *
             * @throws InstrumentManagerException if the format of the
             *         provided instrument file is not supported
             */
            virtual instrument_info_t GetInstrumentInfo(instrument_id_t ID) throw (InstrumentManagerException) = 0;
    };

}

#endif // __LS_INSTRUMENTMANAGER_H__
1	schoenebeck	947	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5			* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	1212	* Copyright (C) 2005 - 2007 Christian Schoenebeck *
7	schoenebeck	947	* *
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	schoenebeck	1212	#include "../common/Exception.h"
29	schoenebeck	947
30			#include <vector>
31
32			namespace LinuxSampler {
33
34			// just symbol prototyping
35			class EngineChannel;
36
37	schoenebeck	1212	/**
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	schoenebeck	947	/** @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	schoenebeck	1536
74			bool operator==(const instrument_id_t& o) const {
75			return (Index == o.Index && FileName == o.FileName);
76			}
77	schoenebeck	947	};
78
79			/**
80	schoenebeck	1525	* 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	schoenebeck	947	* 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	schoenebeck	1212
137	schoenebeck	1321	/**
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	schoenebeck	1212
146	schoenebeck	1321	/**
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	schoenebeck	1212
155	schoenebeck	1321	/**
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	schoenebeck	1212	virtual void LaunchInstrumentEditor(instrument_id_t ID) throw (InstrumentManagerException) = 0;
174	schoenebeck	1525
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	schoenebeck	947	};
192
193	schoenebeck	1212	}
194	schoenebeck	947
195			#endif // __LS_INSTRUMENTMANAGER_H__