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 |