engines/common/InstrumentScriptVM.h

/*
 * Copyright (c) 2014-2020 Christian Schoenebeck
 *
 * http://www.linuxsampler.org
 *
 * This file is part of LinuxSampler and released under the same terms.
 * See README file for details.
 */

#ifndef LS_INSTRUMENT_SCRIPT_VM_H
#define LS_INSTRUMENT_SCRIPT_VM_H

#include "../../common/global.h"
#include "../../common/ConstCapacityArray.h"
#include "../../scriptvm/ScriptVM.h"
#include "Event.h"
#include "../../common/Pool.h"
#include "InstrumentScriptVMFunctions.h"
#include "InstrumentScriptVMDynVars.h"

/**
 * Amount of bits on the left hand side of all pool_element_id_t numbers (i.e.
 * event_id_t, note_id_t) being reserved for script VM implementation internal
 * purposes.
 *
 * Right now there is only one bit reserved, which allows the VM (and its
 * built-in functions) to distinguish user supplied @c Event IDs (event_id_t)
 * from @c Note IDs (note_id_t).
 */
#define INSTR_SCRIPT_EVENT_ID_RESERVED_BITS 1

/**
 * Used by InstrScriptIDType_T to initialize its constants at compile time.
 *
 * This macro is already ready to initialize additional members for
 * InstrScriptIDType_T (that is more than the currently two enum constants).
 * Just keep in mind that you also have to increase
 * INSTR_SCRIPT_EVENT_ID_RESERVED_BITS when you add more!
 *
 * @param x - sequential consecutive number (starting with zero)
 */
#define INSTR_SCRIPT_ID_TYPE_FLAG(x) \
    (x << (sizeof(pool_element_id_t) * 8 - INSTR_SCRIPT_EVENT_ID_RESERVED_BITS))

/**
 * These flags are used to distinguish the individual ID Types in script scope
 * from each other. They are added as most left bit(s) to each ID in script
 * scope.
 */
enum InstrScriptIDType_T {
    /**
     * Used to mark IDs (in script scope) to actually be a MIDI event ID.
     */
    INSTR_SCRIPT_EVENT_ID_FLAG = INSTR_SCRIPT_ID_TYPE_FLAG(0LL),

    /**
     * Used to mark IDs (in script scope) to actually be a note ID.
     */
    INSTR_SCRIPT_NOTE_ID_FLAG = INSTR_SCRIPT_ID_TYPE_FLAG(1LL),
};

#define INSTR_SCRIPT_EVENT_GROUPS 28

#define EVENT_STATUS_INACTIVE 0
#define EVENT_STATUS_NOTE_QUEUE 1

enum {
    EVENT_PAR_NOTE = 1,
    EVENT_PAR_VELOCITY,
    EVENT_PAR_VOLUME,
    EVENT_PAR_TUNE,
    EVENT_PAR_0 = 1024,
    EVENT_PAR_1,
    EVENT_PAR_2,
    EVENT_PAR_3,
};

enum {
    CALLBACK_STATUS_TERMINATED = 0,
    CALLBACK_STATUS_QUEUE = 1,
    CALLBACK_STATUS_RUNNING = (1 << 1)
};

namespace LinuxSampler {

    class AbstractEngineChannel;
    struct InstrumentScript;

    /** @brief Convert IDs between script scope and engine internal scope.
     *
     * This class is used to translate unique IDs of events between script
     * scope and sampler engine internal scope, that is:
     * @code
     * int (script scope) -> event_id_t (engine internal scope)
     * int (script scope) -> note_id_t (engine internal scope)
     * @endcode
     * and vice versa:
     * @code
     * event_id_t (engine internal scope) -> int (script scope)
     * note_id_t (engine internal scope)  -> int (script scope)
     * @endcode
     * This is required because engine internally i.e. notes and regular events
     * are using their own, separate ID generating pool, and their ID number
     * set may thus overlap and historically there were built-in script
     * functions in KSP which allow to pass both regular MIDI event IDs, as well
     * as Note IDs. So we must be able to distinguish between them in our
     * built-in script function implementations. 
     *
     * @see INSTR_SCRIPT_EVENT_ID_RESERVED_BITS
     */
    class ScriptID {
    public:
        enum type_t {
            EVENT, ///< ID is actually an event ID
            NOTE, ///< ID is actually a note ID
        };

        /**
         * Construct a ScriptID object with an ID from script scope.
         */
        ScriptID(vmint id) : m_id(id) {}

        /**
         * Returns a ScriptID object constructed with an event ID from engine
         * internal scope.
         */
        inline static ScriptID fromEventID(event_id_t id) {
            return ScriptID(INSTR_SCRIPT_EVENT_ID_FLAG | id);
        }

        /**
         * Returns a ScriptID object constructed with a note ID from engine
         * internal scope.
         */
        inline static ScriptID fromNoteID(note_id_t id) {
            return ScriptID(INSTR_SCRIPT_NOTE_ID_FLAG | id);
        }

        /**
         * Whether the ID reflected by this ScriptID object is actually a note
         * ID or rather an event ID.
         */
        inline type_t type() const {
            return (m_id & INSTR_SCRIPT_NOTE_ID_FLAG) ? NOTE : EVENT;
        }

        inline bool isNoteID() const {
            return type() == NOTE;
        }

        inline bool isEventID() const {
            return type() == EVENT;
        }

        /**
         * Returns event ID (for engine internal scope) of the ID reflected by
         * this ScriptID object, it returns 0 (being an invalid ID) if the ID
         * reflected by this ScriptID object is not an event ID.
         */
        inline event_id_t eventID() const {
            switch (type()) {
                case EVENT: return m_id;
                default:    return 0; // not an event id, return invalid ID
            }
        }

        /**
         * Returns note ID (for engine internal scope) of the ID reflected by
         * this ScriptID object, it returns 0 (being an invalid ID) if the ID
         * reflected by this ScriptID object is not a note ID.
         */
        inline note_id_t noteID() const {
            switch (type()) {
                case NOTE: return ~INSTR_SCRIPT_NOTE_ID_FLAG & m_id;
                default:   return 0; // not a note id, return invalid ID
            }
        }

        /**
         * Integer cast operator, which returns an ID number of this ScripID
         * object intended for script scope.
         */
        inline operator vmint() const {
            return m_id;
        }

    private:
        vmint m_id;
    };

    /** @brief List of Event IDs.
     *
     * Used for built-in script functions:
     *     by_marks(), set_event_mark(), delete_event_mark()
     */
    class EventGroup : protected ConstCapacityArray<vmint> {
    public:
        EventGroup() : ConstCapacityArray<vmint>(CONFIG_MAX_EVENTS_PER_FRAGMENT), m_script(NULL) {}
        void insert(vmint eventID);
        void erase(vmint eventID);
        void setScript(InstrumentScript* pScript) { m_script = pScript; }
        inline size_t size() const { return ConstCapacityArray<vmint>::size(); }
        inline void clear() { ConstCapacityArray<vmint>::clear(); }
        inline vmint& operator[](ssize_t index) { return ConstCapacityArray<vmint>::operator[](index); }
        inline const vmint& operator[](ssize_t index) const { return ConstCapacityArray<vmint>::operator[](index); }
    protected:
        InstrumentScript* m_script;
    };

    /** @brief Real-time instrument script VM representation.
     *
     * Holds the VM representation of all event handlers of the currently loaded
     * script, ready to be executed by the sampler engine.
     *
     * Even thought scripts (or to be more specific their event handler objects)
     * are shared between sampler engine channels, the InstrumentScript struct
     * instances though are not shared. Each sampler engine channel has its own
     * instance of a InstrumentScript struct. That's important, because this
     * struct also holds engine channel local informations, for example the
     * events that occured on the respective engine channel.
     */
    struct InstrumentScript {
        VMParserContext*      parserContext; ///< VM represenation of the currently loaded script or NULL if not script was loaded. Note that it is also not NULL if parser errors occurred!
        bool                  bHasValidScript; ///< True in case there is a valid script currently loaded, false if script processing shall be skipped.
        VMEventHandler*       handlerInit; ///< VM representation of script's initilization callback or NULL if current script did not define such an init handler.
        VMEventHandler*       handlerNote; ///< VM representation of script's MIDI note on callback or NULL if current script did not define such an event handler.
        VMEventHandler*       handlerRelease; ///< VM representation of script's MIDI note off callback or NULL if current script did not define such an event handler.
        VMEventHandler*       handlerController; ///< VM representation of script's MIDI controller callback or NULL if current script did not define such an event handler.
        VMEventHandler*       handlerRpn; ///< VM representation of script's MIDI RPN event callback or NULL if current script did not define such an event handler.
        VMEventHandler*       handlerNrpn; ///< VM representation of script's MIDI NRPN event callback or NULL if current script did not define such an event handler.
        Pool<ScriptEvent>*    pEvents; ///< Pool of all available script execution instances. ScriptEvents available to be allocated from the Pool are currently unused / not executiong, whereas the ScriptEvents allocated on the list are currently suspended / have not finished execution yet (@see pKeyEvents).
        RTList<ScriptEvent>*  pKeyEvents[128]; ///< Stores previously finished executed "note on" script events for the respective active note/key as long as the key/note is active. This is however only done if there is a "note" script event handler and a "release" script event handler defined in the script and both handlers use (reference) polyphonic variables. If that is not the case, then this list is not used at all. So the purpose of pKeyEvents is only to implement preserving/passing polyphonic variable data from "on note .. end on" script block to the respective "on release .. end on" script block.
        RTAVLTree<ScriptEvent> suspendedEvents; ///< Contains pointers to all suspended events, sorted by time when those script events are to be resumed next.
        AbstractEngineChannel* pEngineChannel;
        String                code; ///< Source code of the instrument script. Used in case the sampler engine is changed, in that case a new ScriptVM object is created for the engine and VMParserContext object for this script needs to be recreated as well. Thus the script is then parsed again by passing the source code to recreate the parser context.
        EventGroup            eventGroups[INSTR_SCRIPT_EVENT_GROUPS]; ///< Used for built-in script functions: by_event_marks(), set_event_mark(), delete_event_mark().

        InstrumentScript(AbstractEngineChannel* pEngineChannel);
        ~InstrumentScript();

        void load(const String& text, const std::map<String,String>& patchVars);
        void unload();
        void resetAll();
        void resetEvents();
    };

    /** @brief Real-time instrument script virtual machine.
     *
     * Extends the core ScriptVM implementation with MIDI specific built-in
     * script functions and MIDI specific built-in script variables required
     * for MIDI processing by instrument script for all sampler engine
     * implementations (sampler formats) of this sampler.
     *
     * Note that this class is currently re-entrant safe, but @b not thread
     * safe! See also comments of base class ScriptVM regarding this issue.
     */
    class InstrumentScriptVM : public ScriptVM {
    public:
        InstrumentScriptVM();
        VMExecStatus_t exec(VMParserContext* parserCtx, ScriptEvent* event);
        VMFunction* functionByName(const String& name) OVERRIDE;
        std::map<String,VMIntPtr*> builtInIntVariables() OVERRIDE;
        std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
        std::map<String,vmint> builtInConstIntVariables() OVERRIDE;
        std::map<String,VMDynVar*> builtInDynamicVariables() OVERRIDE;
    protected:
        ScriptEvent* m_event; ///< The event currently executed by exec().

        // built-in script variables
        VMInt8Array m_CC;
        VMInt8RelPtr m_CC_NUM;
        VMIntRelPtr  m_EVENT_ID;
        VMInt8RelPtr m_EVENT_NOTE;
        VMInt8RelPtr m_EVENT_VELOCITY;
        VMInt8Array  m_KEY_DOWN;
        VMInt16RelPtr m_RPN_ADDRESS; // used for both RPN and NRPN events
        VMInt16RelPtr m_RPN_VALUE;   // used for both RPN and NRPN events
        //VMIntArray m_POLY_AT; //TODO: ...
        //int m_POLY_AT_NUM; //TODO: ...
        VMInt32RelPtr m_NI_CALLBACK_TYPE;
        VMInt8RelPtr m_NKSP_IGNORE_WAIT;
        VMIntRelPtr  m_NKSP_CALLBACK_PARENT_ID;

        // built-in script functions
        InstrumentScriptVMFunction_play_note m_fnPlayNote;
        InstrumentScriptVMFunction_set_controller m_fnSetController;
        InstrumentScriptVMFunction_set_rpn m_fnSetRpn;
        InstrumentScriptVMFunction_set_nrpn m_fnSetNrpn;
        InstrumentScriptVMFunction_ignore_event m_fnIgnoreEvent;
        InstrumentScriptVMFunction_ignore_controller m_fnIgnoreController;
        InstrumentScriptVMFunction_note_off m_fnNoteOff;
        InstrumentScriptVMFunction_set_event_mark m_fnSetEventMark;
        InstrumentScriptVMFunction_delete_event_mark m_fnDeleteEventMark;
        InstrumentScriptVMFunction_by_marks m_fnByMarks;
        InstrumentScriptVMFunction_change_vol m_fnChangeVol;
        InstrumentScriptVMFunction_change_vol_time m_fnChangeVolTime;
        InstrumentScriptVMFunction_change_tune m_fnChangeTune;
        InstrumentScriptVMFunction_change_tune_time m_fnChangeTuneTime;
        InstrumentScriptVMFunction_change_pan m_fnChangePan;
        InstrumentScriptVMFunction_change_pan_time m_fnChangePanTime;
        InstrumentScriptVMFunction_change_pan_curve m_fnChangePanCurve;
        InstrumentScriptVMFunction_change_cutoff m_fnChangeCutoff;
        InstrumentScriptVMFunction_change_reso m_fnChangeReso;
        InstrumentScriptVMFunction_change_attack m_fnChangeAttack;
        InstrumentScriptVMFunction_change_decay m_fnChangeDecay;
        InstrumentScriptVMFunction_change_sustain m_fnChangeSustain;
        InstrumentScriptVMFunction_change_release m_fnChangeRelease;
        InstrumentScriptVMFunction_change_cutoff_attack m_fnChangeCutoffAttack;
        InstrumentScriptVMFunction_change_cutoff_decay m_fnChangeCutoffDecay;
        InstrumentScriptVMFunction_change_cutoff_sustain m_fnChangeCutoffSustain;
        InstrumentScriptVMFunction_change_cutoff_release m_fnChangeCutoffRelease;
        InstrumentScriptVMFunction_change_amp_lfo_depth m_fnChangeAmpLFODepth;
        InstrumentScriptVMFunction_change_amp_lfo_freq m_fnChangeAmpLFOFreq;
        InstrumentScriptVMFunction_change_cutoff_lfo_depth m_fnChangeCutoffLFODepth;
        InstrumentScriptVMFunction_change_cutoff_lfo_freq m_fnChangeCutoffLFOFreq;
        InstrumentScriptVMFunction_change_pitch_lfo_depth m_fnChangePitchLFODepth;
        InstrumentScriptVMFunction_change_pitch_lfo_freq m_fnChangePitchLFOFreq;
        InstrumentScriptVMFunction_change_note m_fnChangeNote;
        InstrumentScriptVMFunction_change_velo m_fnChangeVelo;
        InstrumentScriptVMFunction_fork m_fnFork;
        InstrumentScriptVMFunction_event_status m_fnEventStatus;
        InstrumentScriptVMFunction_wait m_fnWait2;
        InstrumentScriptVMFunction_stop_wait m_fnStopWait;
        InstrumentScriptVMFunction_abort m_fnAbort;
        InstrumentScriptVMFunction_fade_in m_fnFadeIn;
        InstrumentScriptVMFunction_fade_out m_fnFadeOut;
        InstrumentScriptVMFunction_change_vol_curve m_fnChangeVolCurve;
        InstrumentScriptVMFunction_change_tune_curve m_fnChangeTuneCurve;
        InstrumentScriptVMFunction_get_event_par m_fnGetEventPar;
        InstrumentScriptVMFunction_set_event_par m_fnSetEventPar;
        InstrumentScriptVMFunction_change_play_pos m_fnChangePlayPos;
        InstrumentScriptVMFunction_callback_status m_fnCallbackStatus;
        InstrumentScriptVMDynVar_ENGINE_UPTIME m_varEngineUptime;
        InstrumentScriptVMDynVar_NI_CALLBACK_ID m_varCallbackID;
        InstrumentScriptVMDynVar_ALL_EVENTS m_varAllEvents;
        InstrumentScriptVMDynVar_NKSP_CALLBACK_CHILD_ID m_varCallbackChildID;

        friend class InstrumentScriptVMFunction_play_note;
        friend class InstrumentScriptVMFunction_set_controller;
        friend class InstrumentScriptVMFunction_set_rpn;
        friend class InstrumentScriptVMFunction_set_nrpn;
        friend class InstrumentScriptVMFunction_ignore_event;
        friend class InstrumentScriptVMFunction_ignore_controller;
        friend class InstrumentScriptVMFunction_note_off;
        friend class InstrumentScriptVMFunction_set_event_mark;
        friend class InstrumentScriptVMFunction_delete_event_mark;
        friend class InstrumentScriptVMFunction_by_marks;
        friend class InstrumentScriptVMFunction_change_vol;
        friend class InstrumentScriptVMFunction_change_vol_time;
        friend class InstrumentScriptVMFunction_change_tune;
        friend class InstrumentScriptVMFunction_change_tune_time;
        friend class InstrumentScriptVMFunction_change_pan;
        friend class InstrumentScriptVMFunction_change_pan_time;
        friend class InstrumentScriptVMFunction_change_pan_curve;
        friend class InstrumentScriptVMFunction_change_cutoff;
        friend class InstrumentScriptVMFunction_change_reso;
        friend class InstrumentScriptVMFunction_change_attack;
        friend class InstrumentScriptVMFunction_change_decay;
        friend class InstrumentScriptVMFunction_change_release;
        friend class InstrumentScriptVMFunction_change_sustain;
        friend class InstrumentScriptVMFunction_change_cutoff_attack;
        friend class InstrumentScriptVMFunction_change_cutoff_decay;
        friend class InstrumentScriptVMFunction_change_cutoff_release;
        friend class InstrumentScriptVMFunction_change_cutoff_sustain;
        friend class VMChangeSynthParamFunction;
        friend class InstrumentScriptVMFunction_change_amp_lfo_depth;
        friend class InstrumentScriptVMFunction_change_amp_lfo_freq;
        friend class InstrumentScriptVMFunction_change_cutoff_lfo_depth;
        friend class InstrumentScriptVMFunction_change_cutoff_lfo_freq;
        friend class InstrumentScriptVMFunction_change_pitch_lfo_depth;
        friend class InstrumentScriptVMFunction_change_pitch_lfo_freq;
        friend class VMChangeFadeCurveFunction;
        friend class InstrumentScriptVMFunction_fade_in;
        friend class InstrumentScriptVMFunction_fade_out;
        friend class InstrumentScriptVMFunction_get_event_par;
        friend class InstrumentScriptVMFunction_set_event_par;
        friend class InstrumentScriptVMFunction_change_note;
        friend class InstrumentScriptVMFunction_change_velo;
        friend class InstrumentScriptVMFunction_change_play_pos;
        friend class InstrumentScriptVMFunction_event_status;
        friend class InstrumentScriptVMFunction_wait;
        friend class InstrumentScriptVMFunction_stop_wait;
        friend class InstrumentScriptVMFunction_abort;
        friend class InstrumentScriptVMFunction_fork;
        friend class InstrumentScriptVMFunction_callback_status;
        friend class InstrumentScriptVMDynVar_ENGINE_UPTIME;
        friend class InstrumentScriptVMDynVar_NI_CALLBACK_ID;
        friend class InstrumentScriptVMDynVar_ALL_EVENTS;
        friend class InstrumentScriptVMDynVar_NKSP_CALLBACK_CHILD_ID;
    };

} // namespace LinuxSampler

#endif // LS_INSTRUMENT_SCRIPT_VM_H
1	schoenebeck	2594	/*
2	schoenebeck	3690	* Copyright (c) 2014-2020 Christian Schoenebeck
3	schoenebeck	2594	*
4			* http://www.linuxsampler.org
5			*
6			* This file is part of LinuxSampler and released under the same terms.
7			* See README file for details.
8			*/
9
10			#ifndef LS_INSTRUMENT_SCRIPT_VM_H
11			#define LS_INSTRUMENT_SCRIPT_VM_H
12
13			#include "../../common/global.h"
14	schoenebeck	2630	#include "../../common/ConstCapacityArray.h"
15	schoenebeck	2594	#include "../../scriptvm/ScriptVM.h"
16			#include "Event.h"
17	schoenebeck	2611	#include "../../common/Pool.h"
18	schoenebeck	2596	#include "InstrumentScriptVMFunctions.h"
19	schoenebeck	2942	#include "InstrumentScriptVMDynVars.h"
20	schoenebeck	2594
21	schoenebeck	2879	/**
22			* Amount of bits on the left hand side of all pool_element_id_t numbers (i.e.
23			* event_id_t, note_id_t) being reserved for script VM implementation internal
24			* purposes.
25			*
26			* Right now there is only one bit reserved, which allows the VM (and its
27			* built-in functions) to distinguish user supplied @c Event IDs (event_id_t)
28			* from @c Note IDs (note_id_t).
29			*/
30			#define INSTR_SCRIPT_EVENT_ID_RESERVED_BITS 1
31
32			/**
33	schoenebeck	2948	* Used by InstrScriptIDType_T to initialize its constants at compile time.
34			*
35			* This macro is already ready to initialize additional members for
36			* InstrScriptIDType_T (that is more than the currently two enum constants).
37			* Just keep in mind that you also have to increase
38			* INSTR_SCRIPT_EVENT_ID_RESERVED_BITS when you add more!
39			*
40			* @param x - sequential consecutive number (starting with zero)
41	schoenebeck	2879	*/
42	schoenebeck	2948	#define INSTR_SCRIPT_ID_TYPE_FLAG(x) \
43			(x << (sizeof(pool_element_id_t) * 8 - INSTR_SCRIPT_EVENT_ID_RESERVED_BITS))
44	schoenebeck	2879
45	schoenebeck	2948	/**
46			* These flags are used to distinguish the individual ID Types in script scope
47			* from each other. They are added as most left bit(s) to each ID in script
48			* scope.
49			*/
50			enum InstrScriptIDType_T {
51			/**
52			* Used to mark IDs (in script scope) to actually be a MIDI event ID.
53			*/
54	schoenebeck	3557	INSTR_SCRIPT_EVENT_ID_FLAG = INSTR_SCRIPT_ID_TYPE_FLAG(0LL),
55	schoenebeck	2948
56			/**
57			* Used to mark IDs (in script scope) to actually be a note ID.
58			*/
59	schoenebeck	3557	INSTR_SCRIPT_NOTE_ID_FLAG = INSTR_SCRIPT_ID_TYPE_FLAG(1LL),
60	schoenebeck	2948	};
61
62	schoenebeck	2630	#define INSTR_SCRIPT_EVENT_GROUPS 28
63
64	schoenebeck	2935	#define EVENT_STATUS_INACTIVE 0
65			#define EVENT_STATUS_NOTE_QUEUE 1
66
67	schoenebeck	3193	enum {
68			EVENT_PAR_NOTE = 1,
69			EVENT_PAR_VELOCITY,
70			EVENT_PAR_VOLUME,
71			EVENT_PAR_TUNE,
72			EVENT_PAR_0 = 1024,
73			EVENT_PAR_1,
74			EVENT_PAR_2,
75			EVENT_PAR_3,
76			};
77
78	schoenebeck	3296	enum {
79			CALLBACK_STATUS_TERMINATED = 0,
80			CALLBACK_STATUS_QUEUE = 1,
81			CALLBACK_STATUS_RUNNING = (1 << 1)
82			};
83
84	schoenebeck	2594	namespace LinuxSampler {
85
86	schoenebeck	2611	class AbstractEngineChannel;
87	schoenebeck	3034	struct InstrumentScript;
88	schoenebeck	2611
89	schoenebeck	2879	/** @brief Convert IDs between script scope and engine internal scope.
90			*
91			* This class is used to translate unique IDs of events between script
92			* scope and sampler engine internal scope, that is:
93			* @code
94			* int (script scope) -> event_id_t (engine internal scope)
95			* int (script scope) -> note_id_t (engine internal scope)
96			* @endcode
97			* and vice versa:
98			* @code
99			* event_id_t (engine internal scope) -> int (script scope)
100			* note_id_t (engine internal scope) -> int (script scope)
101			* @endcode
102	schoenebeck	2948	* This is required because engine internally i.e. notes and regular events
103			* are using their own, separate ID generating pool, and their ID number
104			* set may thus overlap and historically there were built-in script
105			* functions in KSP which allow to pass both regular MIDI event IDs, as well
106			* as Note IDs. So we must be able to distinguish between them in our
107			* built-in script function implementations.
108	schoenebeck	2879	*
109			* @see INSTR_SCRIPT_EVENT_ID_RESERVED_BITS
110			*/
111			class ScriptID {
112			public:
113			enum type_t {
114			EVENT, ///< ID is actually an event ID
115			NOTE, ///< ID is actually a note ID
116			};
117
118			/**
119			* Construct a ScriptID object with an ID from script scope.
120			*/
121	schoenebeck	3557	ScriptID(vmint id) : m_id(id) {}
122	schoenebeck	2879
123			/**
124			* Returns a ScriptID object constructed with an event ID from engine
125			* internal scope.
126			*/
127			inline static ScriptID fromEventID(event_id_t id) {
128	schoenebeck	2948	return ScriptID(INSTR_SCRIPT_EVENT_ID_FLAG \| id);
129	schoenebeck	2879	}
130
131			/**
132			* Returns a ScriptID object constructed with a note ID from engine
133			* internal scope.
134			*/
135			inline static ScriptID fromNoteID(note_id_t id) {
136			return ScriptID(INSTR_SCRIPT_NOTE_ID_FLAG \| id);
137			}
138
139			/**
140			* Whether the ID reflected by this ScriptID object is actually a note
141			* ID or rather an event ID.
142			*/
143			inline type_t type() const {
144			return (m_id & INSTR_SCRIPT_NOTE_ID_FLAG) ? NOTE : EVENT;
145			}
146
147			inline bool isNoteID() const {
148			return type() == NOTE;
149			}
150
151			inline bool isEventID() const {
152			return type() == EVENT;
153			}
154
155			/**
156			* Returns event ID (for engine internal scope) of the ID reflected by
157			* this ScriptID object, it returns 0 (being an invalid ID) if the ID
158			* reflected by this ScriptID object is not an event ID.
159			*/
160			inline event_id_t eventID() const {
161			switch (type()) {
162			case EVENT: return m_id;
163			default: return 0; // not an event id, return invalid ID
164			}
165			}
166
167			/**
168			* Returns note ID (for engine internal scope) of the ID reflected by
169			* this ScriptID object, it returns 0 (being an invalid ID) if the ID
170			* reflected by this ScriptID object is not a note ID.
171			*/
172			inline note_id_t noteID() const {
173			switch (type()) {
174			case NOTE: return ~INSTR_SCRIPT_NOTE_ID_FLAG & m_id;
175			default: return 0; // not a note id, return invalid ID
176			}
177			}
178
179			/**
180			* Integer cast operator, which returns an ID number of this ScripID
181			* object intended for script scope.
182			*/
183	schoenebeck	3557	inline operator vmint() const {
184	schoenebeck	2879	return m_id;
185			}
186
187			private:
188	schoenebeck	3557	vmint m_id;
189	schoenebeck	2879	};
190
191	schoenebeck	2630	/** @brief List of Event IDs.
192			*
193			* Used for built-in script functions:
194			* by_marks(), set_event_mark(), delete_event_mark()
195			*/
196	schoenebeck	3557	class EventGroup : protected ConstCapacityArray<vmint> {
197	schoenebeck	2630	public:
198	schoenebeck	3557	EventGroup() : ConstCapacityArray<vmint>(CONFIG_MAX_EVENTS_PER_FRAGMENT), m_script(NULL) {}
199			void insert(vmint eventID);
200			void erase(vmint eventID);
201	schoenebeck	2630	void setScript(InstrumentScript* pScript) { m_script = pScript; }
202	schoenebeck	3557	inline size_t size() const { return ConstCapacityArray<vmint>::size(); }
203			inline void clear() { ConstCapacityArray<vmint>::clear(); }
204			inline vmint& operator[](ssize_t index) { return ConstCapacityArray<vmint>::operator[](index); }
205			inline const vmint& operator[](ssize_t index) const { return ConstCapacityArray<vmint>::operator[](index); }
206	schoenebeck	2630	protected:
207			InstrumentScript* m_script;
208			};
209
210	schoenebeck	2611	/** @brief Real-time instrument script VM representation.
211			*
212			* Holds the VM representation of all event handlers of the currently loaded
213			* script, ready to be executed by the sampler engine.
214	schoenebeck	2645	*
215			* Even thought scripts (or to be more specific their event handler objects)
216			* are shared between sampler engine channels, the InstrumentScript struct
217			* instances though are not shared. Each sampler engine channel has its own
218			* instance of a InstrumentScript struct. That's important, because this
219			* struct also holds engine channel local informations, for example the
220			* events that occured on the respective engine channel.
221	schoenebeck	2611	*/
222			struct InstrumentScript {
223			VMParserContext* parserContext; ///< VM represenation of the currently loaded script or NULL if not script was loaded. Note that it is also not NULL if parser errors occurred!
224			bool bHasValidScript; ///< True in case there is a valid script currently loaded, false if script processing shall be skipped.
225			VMEventHandler* handlerInit; ///< VM representation of script's initilization callback or NULL if current script did not define such an init handler.
226			VMEventHandler* handlerNote; ///< VM representation of script's MIDI note on callback or NULL if current script did not define such an event handler.
227			VMEventHandler* handlerRelease; ///< VM representation of script's MIDI note off callback or NULL if current script did not define such an event handler.
228			VMEventHandler* handlerController; ///< VM representation of script's MIDI controller callback or NULL if current script did not define such an event handler.
229	schoenebeck	3690	VMEventHandler* handlerRpn; ///< VM representation of script's MIDI RPN event callback or NULL if current script did not define such an event handler.
230			VMEventHandler* handlerNrpn; ///< VM representation of script's MIDI NRPN event callback or NULL if current script did not define such an event handler.
231	schoenebeck	2645	Pool<ScriptEvent>* pEvents; ///< Pool of all available script execution instances. ScriptEvents available to be allocated from the Pool are currently unused / not executiong, whereas the ScriptEvents allocated on the list are currently suspended / have not finished execution yet (@see pKeyEvents).
232			RTList<ScriptEvent>* pKeyEvents[128]; ///< Stores previously finished executed "note on" script events for the respective active note/key as long as the key/note is active. This is however only done if there is a "note" script event handler and a "release" script event handler defined in the script and both handlers use (reference) polyphonic variables. If that is not the case, then this list is not used at all. So the purpose of pKeyEvents is only to implement preserving/passing polyphonic variable data from "on note .. end on" script block to the respective "on release .. end on" script block.
233	schoenebeck	2871	RTAVLTree<ScriptEvent> suspendedEvents; ///< Contains pointers to all suspended events, sorted by time when those script events are to be resumed next.
234	schoenebeck	2611	AbstractEngineChannel* pEngineChannel;
235	schoenebeck	2612	String code; ///< Source code of the instrument script. Used in case the sampler engine is changed, in that case a new ScriptVM object is created for the engine and VMParserContext object for this script needs to be recreated as well. Thus the script is then parsed again by passing the source code to recreate the parser context.
236	schoenebeck	2630	EventGroup eventGroups[INSTR_SCRIPT_EVENT_GROUPS]; ///< Used for built-in script functions: by_event_marks(), set_event_mark(), delete_event_mark().
237	schoenebeck	2611
238	schoenebeck	2630	InstrumentScript(AbstractEngineChannel* pEngineChannel);
239	schoenebeck	2645	~InstrumentScript();
240	schoenebeck	2611
241	schoenebeck	3733	void load(const String& text, const std::map<String,String>& patchVars);
242	schoenebeck	2612	void unload();
243			void resetAll();
244	schoenebeck	2871	void resetEvents();
245	schoenebeck	2611	};
246
247	schoenebeck	2594	/** @brief Real-time instrument script virtual machine.
248			*
249			* Extends the core ScriptVM implementation with MIDI specific built-in
250			* script functions and MIDI specific built-in script variables required
251			* for MIDI processing by instrument script for all sampler engine
252			* implementations (sampler formats) of this sampler.
253			*
254			* Note that this class is currently re-entrant safe, but @b not thread
255			* safe! See also comments of base class ScriptVM regarding this issue.
256			*/
257			class InstrumentScriptVM : public ScriptVM {
258			public:
259			InstrumentScriptVM();
260			VMExecStatus_t exec(VMParserContext* parserCtx, ScriptEvent* event);
261	schoenebeck	2596	VMFunction* functionByName(const String& name) OVERRIDE;
262	schoenebeck	3557	std::map<String,VMIntPtr*> builtInIntVariables() OVERRIDE;
263	schoenebeck	2594	std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
264	schoenebeck	3557	std::map<String,vmint> builtInConstIntVariables() OVERRIDE;
265	schoenebeck	2942	std::map<String,VMDynVar*> builtInDynamicVariables() OVERRIDE;
266	schoenebeck	2594	protected:
267			ScriptEvent* m_event; ///< The event currently executed by exec().
268
269	schoenebeck	3082	// built-in script variables
270	schoenebeck	2594	VMInt8Array m_CC;
271			VMInt8RelPtr m_CC_NUM;
272	schoenebeck	2598	VMIntRelPtr m_EVENT_ID;
273	schoenebeck	2594	VMInt8RelPtr m_EVENT_NOTE;
274			VMInt8RelPtr m_EVENT_VELOCITY;
275	schoenebeck	2613	VMInt8Array m_KEY_DOWN;
276	schoenebeck	3690	VMInt16RelPtr m_RPN_ADDRESS; // used for both RPN and NRPN events
277			VMInt16RelPtr m_RPN_VALUE; // used for both RPN and NRPN events
278	schoenebeck	2594	//VMIntArray m_POLY_AT; //TODO: ...
279			//int m_POLY_AT_NUM; //TODO: ...
280	schoenebeck	3557	VMInt32RelPtr m_NI_CALLBACK_TYPE;
281			VMInt8RelPtr m_NKSP_IGNORE_WAIT;
282	schoenebeck	3293	VMIntRelPtr m_NKSP_CALLBACK_PARENT_ID;
283	schoenebeck	2596
284	schoenebeck	3082	// built-in script functions
285	schoenebeck	2596	InstrumentScriptVMFunction_play_note m_fnPlayNote;
286	schoenebeck	2600	InstrumentScriptVMFunction_set_controller m_fnSetController;
287	schoenebeck	3691	InstrumentScriptVMFunction_set_rpn m_fnSetRpn;
288			InstrumentScriptVMFunction_set_nrpn m_fnSetNrpn;
289	schoenebeck	2600	InstrumentScriptVMFunction_ignore_event m_fnIgnoreEvent;
290			InstrumentScriptVMFunction_ignore_controller m_fnIgnoreController;
291	schoenebeck	2629	InstrumentScriptVMFunction_note_off m_fnNoteOff;
292	schoenebeck	2630	InstrumentScriptVMFunction_set_event_mark m_fnSetEventMark;
293			InstrumentScriptVMFunction_delete_event_mark m_fnDeleteEventMark;
294			InstrumentScriptVMFunction_by_marks m_fnByMarks;
295	schoenebeck	2931	InstrumentScriptVMFunction_change_vol m_fnChangeVol;
296	schoenebeck	3188	InstrumentScriptVMFunction_change_vol_time m_fnChangeVolTime;
297	schoenebeck	2931	InstrumentScriptVMFunction_change_tune m_fnChangeTune;
298	schoenebeck	3188	InstrumentScriptVMFunction_change_tune_time m_fnChangeTuneTime;
299	schoenebeck	2931	InstrumentScriptVMFunction_change_pan m_fnChangePan;
300	schoenebeck	3335	InstrumentScriptVMFunction_change_pan_time m_fnChangePanTime;
301			InstrumentScriptVMFunction_change_pan_curve m_fnChangePanCurve;
302	schoenebeck	2935	InstrumentScriptVMFunction_change_cutoff m_fnChangeCutoff;
303			InstrumentScriptVMFunction_change_reso m_fnChangeReso;
304	schoenebeck	2953	InstrumentScriptVMFunction_change_attack m_fnChangeAttack;
305			InstrumentScriptVMFunction_change_decay m_fnChangeDecay;
306	schoenebeck	3316	InstrumentScriptVMFunction_change_sustain m_fnChangeSustain;
307	schoenebeck	2953	InstrumentScriptVMFunction_change_release m_fnChangeRelease;
308	schoenebeck	3360	InstrumentScriptVMFunction_change_cutoff_attack m_fnChangeCutoffAttack;
309			InstrumentScriptVMFunction_change_cutoff_decay m_fnChangeCutoffDecay;
310			InstrumentScriptVMFunction_change_cutoff_sustain m_fnChangeCutoffSustain;
311			InstrumentScriptVMFunction_change_cutoff_release m_fnChangeCutoffRelease;
312	schoenebeck	3118	InstrumentScriptVMFunction_change_amp_lfo_depth m_fnChangeAmpLFODepth;
313			InstrumentScriptVMFunction_change_amp_lfo_freq m_fnChangeAmpLFOFreq;
314	schoenebeck	3360	InstrumentScriptVMFunction_change_cutoff_lfo_depth m_fnChangeCutoffLFODepth;
315			InstrumentScriptVMFunction_change_cutoff_lfo_freq m_fnChangeCutoffLFOFreq;
316	schoenebeck	3118	InstrumentScriptVMFunction_change_pitch_lfo_depth m_fnChangePitchLFODepth;
317			InstrumentScriptVMFunction_change_pitch_lfo_freq m_fnChangePitchLFOFreq;
318	schoenebeck	3214	InstrumentScriptVMFunction_change_note m_fnChangeNote;
319			InstrumentScriptVMFunction_change_velo m_fnChangeVelo;
320	schoenebeck	3293	InstrumentScriptVMFunction_fork m_fnFork;
321	schoenebeck	2935	InstrumentScriptVMFunction_event_status m_fnEventStatus;
322	schoenebeck	2948	InstrumentScriptVMFunction_wait m_fnWait2;
323			InstrumentScriptVMFunction_stop_wait m_fnStopWait;
324	schoenebeck	3277	InstrumentScriptVMFunction_abort m_fnAbort;
325	schoenebeck	3188	InstrumentScriptVMFunction_fade_in m_fnFadeIn;
326			InstrumentScriptVMFunction_fade_out m_fnFadeOut;
327	schoenebeck	3246	InstrumentScriptVMFunction_change_vol_curve m_fnChangeVolCurve;
328			InstrumentScriptVMFunction_change_tune_curve m_fnChangeTuneCurve;
329	schoenebeck	3193	InstrumentScriptVMFunction_get_event_par m_fnGetEventPar;
330			InstrumentScriptVMFunction_set_event_par m_fnSetEventPar;
331	schoenebeck	3255	InstrumentScriptVMFunction_change_play_pos m_fnChangePlayPos;
332	schoenebeck	3296	InstrumentScriptVMFunction_callback_status m_fnCallbackStatus;
333	schoenebeck	2942	InstrumentScriptVMDynVar_ENGINE_UPTIME m_varEngineUptime;
334	schoenebeck	2948	InstrumentScriptVMDynVar_NI_CALLBACK_ID m_varCallbackID;
335	schoenebeck	3073	InstrumentScriptVMDynVar_ALL_EVENTS m_varAllEvents;
336	schoenebeck	3293	InstrumentScriptVMDynVar_NKSP_CALLBACK_CHILD_ID m_varCallbackChildID;
337	schoenebeck	2596
338			friend class InstrumentScriptVMFunction_play_note;
339	schoenebeck	2600	friend class InstrumentScriptVMFunction_set_controller;
340	schoenebeck	3691	friend class InstrumentScriptVMFunction_set_rpn;
341			friend class InstrumentScriptVMFunction_set_nrpn;
342	schoenebeck	2598	friend class InstrumentScriptVMFunction_ignore_event;
343			friend class InstrumentScriptVMFunction_ignore_controller;
344	schoenebeck	2629	friend class InstrumentScriptVMFunction_note_off;
345	schoenebeck	2630	friend class InstrumentScriptVMFunction_set_event_mark;
346			friend class InstrumentScriptVMFunction_delete_event_mark;
347			friend class InstrumentScriptVMFunction_by_marks;
348	schoenebeck	2931	friend class InstrumentScriptVMFunction_change_vol;
349	schoenebeck	3188	friend class InstrumentScriptVMFunction_change_vol_time;
350	schoenebeck	2931	friend class InstrumentScriptVMFunction_change_tune;
351	schoenebeck	3188	friend class InstrumentScriptVMFunction_change_tune_time;
352	schoenebeck	2931	friend class InstrumentScriptVMFunction_change_pan;
353	schoenebeck	3335	friend class InstrumentScriptVMFunction_change_pan_time;
354			friend class InstrumentScriptVMFunction_change_pan_curve;
355	schoenebeck	2935	friend class InstrumentScriptVMFunction_change_cutoff;
356			friend class InstrumentScriptVMFunction_change_reso;
357	schoenebeck	2953	friend class InstrumentScriptVMFunction_change_attack;
358			friend class InstrumentScriptVMFunction_change_decay;
359			friend class InstrumentScriptVMFunction_change_release;
360	schoenebeck	3316	friend class InstrumentScriptVMFunction_change_sustain;
361	schoenebeck	3360	friend class InstrumentScriptVMFunction_change_cutoff_attack;
362			friend class InstrumentScriptVMFunction_change_cutoff_decay;
363			friend class InstrumentScriptVMFunction_change_cutoff_release;
364			friend class InstrumentScriptVMFunction_change_cutoff_sustain;
365	schoenebeck	3118	friend class VMChangeSynthParamFunction;
366			friend class InstrumentScriptVMFunction_change_amp_lfo_depth;
367			friend class InstrumentScriptVMFunction_change_amp_lfo_freq;
368	schoenebeck	3360	friend class InstrumentScriptVMFunction_change_cutoff_lfo_depth;
369			friend class InstrumentScriptVMFunction_change_cutoff_lfo_freq;
370	schoenebeck	3118	friend class InstrumentScriptVMFunction_change_pitch_lfo_depth;
371			friend class InstrumentScriptVMFunction_change_pitch_lfo_freq;
372	schoenebeck	3246	friend class VMChangeFadeCurveFunction;
373	schoenebeck	3188	friend class InstrumentScriptVMFunction_fade_in;
374			friend class InstrumentScriptVMFunction_fade_out;
375	schoenebeck	3193	friend class InstrumentScriptVMFunction_get_event_par;
376			friend class InstrumentScriptVMFunction_set_event_par;
377	schoenebeck	3214	friend class InstrumentScriptVMFunction_change_note;
378			friend class InstrumentScriptVMFunction_change_velo;
379	schoenebeck	3255	friend class InstrumentScriptVMFunction_change_play_pos;
380	schoenebeck	2935	friend class InstrumentScriptVMFunction_event_status;
381	schoenebeck	2948	friend class InstrumentScriptVMFunction_wait;
382			friend class InstrumentScriptVMFunction_stop_wait;
383	schoenebeck	3277	friend class InstrumentScriptVMFunction_abort;
384	schoenebeck	3293	friend class InstrumentScriptVMFunction_fork;
385	schoenebeck	3296	friend class InstrumentScriptVMFunction_callback_status;
386	schoenebeck	2942	friend class InstrumentScriptVMDynVar_ENGINE_UPTIME;
387	schoenebeck	2948	friend class InstrumentScriptVMDynVar_NI_CALLBACK_ID;
388	schoenebeck	3073	friend class InstrumentScriptVMDynVar_ALL_EVENTS;
389	schoenebeck	3293	friend class InstrumentScriptVMDynVar_NKSP_CALLBACK_CHILD_ID;
390	schoenebeck	2594	};
391
392			} // namespace LinuxSampler
393
394			#endif // LS_INSTRUMENT_SCRIPT_VM_H