src/engines/InstrumentManager.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005, 2006 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 <vector>

namespace LinuxSampler {

    // just symbol prototyping
    class EngineChannel;

    /** @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));
                }
            };

            /**
             * 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);

            /**
             * Get global volume factor for this instrument.
             *
             * This method has to be implemented by the descendant.
             */
            virtual float GetVolume(const instrument_id_t& ID) = 0;

            /**
             * Change global volume factor for this instrument.
             *
             * This method has to be implemented by the descendant.
             */
            virtual void SetVolume(const instrument_id_t& ID, float Volume) = 0;

            /**
             * 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;
    };

};

#endif // __LS_INSTRUMENTMANAGER_H__
1	/***************************************************************************
2	* *
3	* LinuxSampler - modular, streaming capable sampler *
4	* *
5	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	* Copyright (C) 2005, 2006 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
29	#include <vector>
30
31	namespace LinuxSampler {
32
33	// just symbol prototyping
34	class EngineChannel;
35
36	/** @brief Abstract interface class for InstrumentManagers.
37	*
38	* Sampler engines should provide an InstrumentManager for allowing
39	* detailed information retrieval and setting of its managed instruments
40	* through this general API.
41	*/
42	class InstrumentManager {
43	public:
44	/**
45	* Defines life-time of an instrument.
46	*/
47	enum mode_t {
48	ON_DEMAND = 0, ///< Instrument will be loaded when needed, freed once not needed anymore.
49	ON_DEMAND_HOLD = 1, ///< Instrument will be loaded when needed and kept even if not needed anymore.
50	PERSISTENT = 2 ///< Instrument will immediately be loaded and kept all the time.
51	};
52
53	/**
54	* Reflects unique ID of an instrument.
55	*/
56	struct instrument_id_t {
57	String FileName; ///< File name of the instrument.
58	uint Index; ///< Index of the instrument within the file.
59
60	// 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
61	bool operator<(const instrument_id_t& o) const {
62	return (Index < o.Index \|\| (Index == o.Index && FileName < o.FileName));
63	}
64	};
65
66	/**
67	* Returns all managed instruments.
68	*
69	* This method has to be implemented by the descendant.
70	*/
71	virtual std::vector<instrument_id_t> Instruments() = 0;
72
73	/**
74	* Returns the current life-time strategy for the given
75	* instrument.
76	*
77	* This method has to be implemented by the descendant.
78	*/
79	virtual mode_t GetMode(const instrument_id_t& ID) = 0;
80
81	/**
82	* Change the current life-time strategy for the given
83	* instrument.
84	*
85	* This method has to be implemented by the descendant.
86	*/
87	virtual void SetMode(const instrument_id_t& ID, mode_t Mode) = 0;
88
89	/**
90	* Same as SetMode(), but with the difference that this method
91	* won't block.
92	*/
93	void SetModeInBackground(const instrument_id_t& ID, mode_t Mode);
94
95	/**
96	* Get global volume factor for this instrument.
97	*
98	* This method has to be implemented by the descendant.
99	*/
100	virtual float GetVolume(const instrument_id_t& ID) = 0;
101
102	/**
103	* Change global volume factor for this instrument.
104	*
105	* This method has to be implemented by the descendant.
106	*/
107	virtual void SetVolume(const instrument_id_t& ID, float Volume) = 0;
108
109	/**
110	* Same as loading the given instrument directly on the given
111	* EngineChannel, but this method will not block, instead it
112	* will load the instrument in a separate thread.
113	*
114	* @param ID - the instrument to be loaded
115	* @param pEngineChannel - on which engine channel the instrument
116	* should be loaded
117	*/
118	static void LoadInstrumentInBackground(instrument_id_t ID, EngineChannel* pEngineChannel);
119
120	/**
121	* Returns the name of the given instrument as reflected by its
122	* file.
123	*
124	* This method has to be implemented by the descendant.
125	*/
126	virtual String GetInstrumentName(instrument_id_t ID) = 0;
127	};
128
129	};
130
131	#endif // __LS_INSTRUMENTMANAGER_H__