src/effects/EffectFactory.h

/*
    Copyright (C) 2010 Christian Schoenebeck
*/

#ifndef LS_EFFECT_FACTORY_H
#define LS_EFFECT_FACTORY_H

#include "Effect.h"
#include "EffectInfo.h"
#include "../common/Exception.h"

namespace LinuxSampler {

/**
 * Manages all sampler internal effects. It offers a list and detailed
 * informations about all internal effects available for the sampler and allows
 * to create and destroy instances of those effects. It provides a general
 * interface for these functions, independent of the respective effect system's
 * implementation details.
 */
class EffectFactory {
public:
    /**
     * Used as search criteria for plugin DLL filenames by GetEffectInfo() .
     * These flags can be bitwise or-ed.
     */
    enum ModuleMatchFlag_t {
        MODULE_MATCH_EXACTLY = 0,    ///< The plugin DLL filename has to match exactly.
        MODULE_IGNORE_CASE = 1,      ///< Ignore upper case / lower case differences in the module names.
        MODULE_IGNORE_EXTENSION = 2, ///< Strip off the file extension (if any) before comparing the DLL filenames.
        MODULE_IGNORE_PATH = 4,      ///< Strip off the path of the plugin DLL filename before comparing.
        MODULE_IGNORE_ALL = -1       ///< Will match all modules successfully, no matter what module name was provided.
    };

    /**
     * Returns comma separated list of all effect systems currently available
     * for this sampler. This list can vary on the exact configuration of the
     * running machine and the options with which the sampler was compiled.
     */
    static String AvailableEffectSystemsAsString();

    /**
     * Returns total amount of effects currently available for the sampler. This
     * value can vary on the exact configuration of the running machine and
     * especially on which effect plugins are currently installed on the machine.
     *
     * @e Note: When this method is called the 1st tim, it can take quite some
     * time to return, since it will trigger a scan to retrieve all effects,
     * currently available on the system. Those informations are then buffered
     * in RAM and won't change on subsequent calls to AvailableEffectsCount()
     * until an update of available effects is forced by calling
     * UpdateAvailableEffects() .
     *
     * @see UpdateAvailableEffects()
     */
    static uint AvailableEffectsCount();

    /**
     * Force to refresh the internal list of available effects and their
     * detailed informations. This might be necessary e.g. when the user
     * installed new effect plugins on his system and doesn't want to restart
     * the whole sampler session just for being able to access the new effects.
     */
    static void UpdateAvailableEffects();

    /**
     * Returns unique identifier and further detailed informations about the
     * requested effect.
     *
     * @param index - index of the effect to retrieve informations about, must
     *                be between 0 and AvailableEffectsCount()
     * @see UpdateAvailableEffects()
     */
    static EffectInfo* GetEffectInfo(uint index);

    /**
     * Returns unique identifier and further detailed informations about the
     * the requested effect. Since the effect plugin's DLL filename (a.k.a.
     * @a module) can vary for the very same effect on different systems, it
     * is possible to use @a iModuleMatchFlags for defining in which way the
     * provided DLL filename should be matched in this search or whether it
     * should even be ignored completely. This allows to reload sampler sessions
     * created on one system, successfully on another system, probably even
     * having a completely different OS (e.g. Linux vs. Windows).
     *
     * @param effectSystem - e.g. 'LADSPA'
     * @param module - usually the DLL filename of the effect plugin
     * @param effectName - unique identifier of the effect within its plugin module
     * @param iModuleMatchFlags - (optional) defines how strong the given
     *                            @a module must match with the actual on the
     *                            system available module name, the flags can
     *                            be bitwise or-ed
     *                            (default: the module name must match exactly)
     * @returns effect info or NULL if there is no such effect
     * @see ModuleMatchFlag_t
     */
    static EffectInfo* GetEffectInfo(String effectSystem, String module, String effectName, int iModuleMatchFlags = MODULE_MATCH_EXACTLY);

    /**
     * Create an instance of the requested effect. You should call Destroy()
     * once the effect is not used anymore.
     *
     * @param pInfo - unique identifier of the effect to create
     * @returns pointer to new effect instance, throws an Exception otherwise
     * @throws Exception - if the requested effect could not be instantiated
     *                     successfully
     */
    static Effect* Create(EffectInfo* pInfo) throw (Exception);

    /**
     * Destroy and free the given effect instance from memory, previously
     * created with Create() .
     *
     * @param pEffect - effect instance to destroy
     * @throws Exception - if effect is still in use
     */
    static void Destroy(Effect* pEffect) throw (Exception);

    /**
     * Returns total amount of effect instances created with Create() .
     */
    static uint EffectInstancesCount();

    /**
     * Returns effect instance for the given index.
     *
     * @param index - index of the effect instance must be between 0 and
     *                EffectInstancesCount()
     * @returns effect instance, or NULL if index out of bounds
     */
    static Effect* GetEffectInstance(uint index);

    /**
     * Returns effect instance with the given effect instance ID.
     *
     * @param id - effect instance ID of sought effect instance
     * @returns effect instance or NULL if no effect instance with that ID
     *          could be found
     */
    static Effect* GetEffectInstanceByID(int id);
};

} // namespace LinuxSampler

#endif // LS_EFFECT_FACTORY_H
1	schoenebeck	2124	/*
2			Copyright (C) 2010 Christian Schoenebeck
3			*/
4
5			#ifndef LS_EFFECT_FACTORY_H
6			#define LS_EFFECT_FACTORY_H
7
8			#include "Effect.h"
9			#include "EffectInfo.h"
10			#include "../common/Exception.h"
11
12			namespace LinuxSampler {
13
14			/**
15			* Manages all sampler internal effects. It offers a list and detailed
16			* informations about all internal effects available for the sampler and allows
17			* to create and destroy instances of those effects. It provides a general
18			* interface for these functions, independent of the respective effect system's
19			* implementation details.
20			*/
21			class EffectFactory {
22			public:
23			/**
24	schoenebeck	2135	* Used as search criteria for plugin DLL filenames by GetEffectInfo() .
25			* These flags can be bitwise or-ed.
26			*/
27			enum ModuleMatchFlag_t {
28			MODULE_MATCH_EXACTLY = 0, ///< The plugin DLL filename has to match exactly.
29			MODULE_IGNORE_CASE = 1, ///< Ignore upper case / lower case differences in the module names.
30			MODULE_IGNORE_EXTENSION = 2, ///< Strip off the file extension (if any) before comparing the DLL filenames.
31			MODULE_IGNORE_PATH = 4, ///< Strip off the path of the plugin DLL filename before comparing.
32			MODULE_IGNORE_ALL = -1 ///< Will match all modules successfully, no matter what module name was provided.
33			};
34
35			/**
36	schoenebeck	2124	* Returns comma separated list of all effect systems currently available
37			* for this sampler. This list can vary on the exact configuration of the
38			* running machine and the options with which the sampler was compiled.
39			*/
40			static String AvailableEffectSystemsAsString();
41
42			/**
43			* Returns total amount of effects currently available for the sampler. This
44			* value can vary on the exact configuration of the running machine and
45			* especially on which effect plugins are currently installed on the machine.
46			*
47			* @e Note: When this method is called the 1st tim, it can take quite some
48			* time to return, since it will trigger a scan to retrieve all effects,
49			* currently available on the system. Those informations are then buffered
50			* in RAM and won't change on subsequent calls to AvailableEffectsCount()
51			* until an update of available effects is forced by calling
52			* UpdateAvailableEffects() .
53			*
54			* @see UpdateAvailableEffects()
55			*/
56			static uint AvailableEffectsCount();
57
58			/**
59			* Force to refresh the internal list of available effects and their
60			* detailed informations. This might be necessary e.g. when the user
61			* installed new effect plugins on his system and doesn't want to restart
62			* the whole sampler session just for being able to access the new effects.
63			*/
64			static void UpdateAvailableEffects();
65
66			/**
67			* Returns unique identifier and further detailed informations about the
68			* requested effect.
69			*
70			* @param index - index of the effect to retrieve informations about, must
71			* be between 0 and AvailableEffectsCount()
72			* @see UpdateAvailableEffects()
73			*/
74			static EffectInfo* GetEffectInfo(uint index);
75
76			/**
77	schoenebeck	2135	* Returns unique identifier and further detailed informations about the
78			* the requested effect. Since the effect plugin's DLL filename (a.k.a.
79			* @a module) can vary for the very same effect on different systems, it
80			* is possible to use @a iModuleMatchFlags for defining in which way the
81			* provided DLL filename should be matched in this search or whether it
82			* should even be ignored completely. This allows to reload sampler sessions
83			* created on one system, successfully on another system, probably even
84			* having a completely different OS (e.g. Linux vs. Windows).
85			*
86			* @param effectSystem - e.g. 'LADSPA'
87			* @param module - usually the DLL filename of the effect plugin
88			* @param effectName - unique identifier of the effect within its plugin module
89			* @param iModuleMatchFlags - (optional) defines how strong the given
90			* @a module must match with the actual on the
91			* system available module name, the flags can
92			* be bitwise or-ed
93			* (default: the module name must match exactly)
94			* @returns effect info or NULL if there is no such effect
95			* @see ModuleMatchFlag_t
96			*/
97			static EffectInfo* GetEffectInfo(String effectSystem, String module, String effectName, int iModuleMatchFlags = MODULE_MATCH_EXACTLY);
98
99			/**
100	schoenebeck	2124	* Create an instance of the requested effect. You should call Destroy()
101			* once the effect is not used anymore.
102			*
103			* @param pInfo - unique identifier of the effect to create
104			* @returns pointer to new effect instance, throws an Exception otherwise
105			* @throws Exception - if the requested effect could not be instantiated
106			* successfully
107			*/
108			static Effect* Create(EffectInfo* pInfo) throw (Exception);
109
110			/**
111			* Destroy and free the given effect instance from memory, previously
112			* created with Create() .
113			*
114			* @param pEffect - effect instance to destroy
115	schoenebeck	2135	* @throws Exception - if effect is still in use
116	schoenebeck	2124	*/
117	schoenebeck	2135	static void Destroy(Effect* pEffect) throw (Exception);
118
119			/**
120			* Returns total amount of effect instances created with Create() .
121			*/
122			static uint EffectInstancesCount();
123
124			/**
125			* Returns effect instance for the given index.
126			*
127			* @param index - index of the effect instance must be between 0 and
128			* EffectInstancesCount()
129			* @returns effect instance, or NULL if index out of bounds
130			*/
131			static Effect* GetEffectInstance(uint index);
132
133			/**
134			* Returns effect instance with the given effect instance ID.
135			*
136			* @param id - effect instance ID of sought effect instance
137			* @returns effect instance or NULL if no effect instance with that ID
138			* could be found
139			*/
140			static Effect* GetEffectInstanceByID(int id);
141	schoenebeck	2124	};
142
143			} // namespace LinuxSampler
144
145			#endif // LS_EFFECT_FACTORY_H