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

    /**
     * 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
     */
    static void Destroy(Effect* pEffect);
};

} // 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			* Returns comma separated list of all effect systems currently available
25			* for this sampler. This list can vary on the exact configuration of the
26			* running machine and the options with which the sampler was compiled.
27			*/
28			static String AvailableEffectSystemsAsString();
29
30			/**
31			* Returns total amount of effects currently available for the sampler. This
32			* value can vary on the exact configuration of the running machine and
33			* especially on which effect plugins are currently installed on the machine.
34			*
35			* @e Note: When this method is called the 1st tim, it can take quite some
36			* time to return, since it will trigger a scan to retrieve all effects,
37			* currently available on the system. Those informations are then buffered
38			* in RAM and won't change on subsequent calls to AvailableEffectsCount()
39			* until an update of available effects is forced by calling
40			* UpdateAvailableEffects() .
41			*
42			* @see UpdateAvailableEffects()
43			*/
44			static uint AvailableEffectsCount();
45
46			/**
47			* Force to refresh the internal list of available effects and their
48			* detailed informations. This might be necessary e.g. when the user
49			* installed new effect plugins on his system and doesn't want to restart
50			* the whole sampler session just for being able to access the new effects.
51			*/
52			static void UpdateAvailableEffects();
53
54			/**
55			* Returns unique identifier and further detailed informations about the
56			* requested effect.
57			*
58			* @param index - index of the effect to retrieve informations about, must
59			* be between 0 and AvailableEffectsCount()
60			* @see UpdateAvailableEffects()
61			*/
62			static EffectInfo* GetEffectInfo(uint index);
63
64			/**
65			* Create an instance of the requested effect. You should call Destroy()
66			* once the effect is not used anymore.
67			*
68			* @param pInfo - unique identifier of the effect to create
69			* @returns pointer to new effect instance, throws an Exception otherwise
70			* @throws Exception - if the requested effect could not be instantiated
71			* successfully
72			*/
73			static Effect* Create(EffectInfo* pInfo) throw (Exception);
74
75			/**
76			* Destroy and free the given effect instance from memory, previously
77			* created with Create() .
78			*
79			* @param pEffect - effect instance to destroy
80			*/
81			static void Destroy(Effect* pEffect);
82			};
83
84			} // namespace LinuxSampler
85
86			#endif // LS_EFFECT_FACTORY_H