drivers/midi/VirtualMidiDevice.h

/*
    Copyright (C) 2008 - 2014 Christian Schoenebeck
 */

#ifndef LS_VIRTUALMIDIDEVICE_H
#define LS_VIRTUALMIDIDEVICE_H

#include "../../common/global.h"

namespace LinuxSampler {

/**
 * Light-weight MIDI interface (for MIDI in & out) intended to be used by
 * pure software MIDI "devices", that is e.g. a graphical virtual MIDI
 * keyboard in an instrument editor or in a sampler frontend. This class
 * should not be used for regular MIDI input device drivers for the sampler.
 * This primitive interface by design doesn't care about jitter, fast event
 * delivery or masses and masses of events in a short time!
 */
class VirtualMidiDevice {
public:
    enum event_type_t {
        EVENT_TYPE_NOTEON  = 1,
        EVENT_TYPE_NOTEOFF = 2,
        EVENT_TYPE_CC      = 3,
        EVENT_TYPE_PITCHBEND,
        EVENT_TYPE_PROGRAM
    };

    struct event_t {
        event_type_t Type;
        uint8_t      Arg1; ///< Depends on @c Type (e.g. key number for note on/off events).
        uint8_t      Arg2; ///< Depends on @c Type (e.g. velocity for note on/off events).
    };

    /////////////////////////////////////////////////////////////////
    // Device methods
    //     (called by the VirtualMidiDevice implementation)

    /**
     * Sends a MIDI @e note @e on event to the sampler.
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided values invalid)
     */
    bool SendNoteOnToSampler(uint8_t Key, uint8_t Velocity);

    /**
     * Sends a MIDI @e note @e off event to the sampler.
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided values invalid)
     */
    bool SendNoteOffToSampler(uint8_t Key, uint8_t Velocity);

    /**
     * Sends a MIDI @e Control @e Change event to the sampler.
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided values invalid)
     */
    bool SendCCToSampler(uint8_t Controller, uint8_t Value);

    /**
     * Sends a MIDI @e Pitch @e Bend event to the sampler.
     *
     * @param Pitch - MIDI pitch value (-8192 ... +8191)
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided pitch value out of valid range)
     */
    bool SendPitchBendToSampler(int Pitch);

    /**
     * Sends a MIDI @e Program @e Change event to the sampler.
     *
     * If you want to change the sound bank, call SendCCToSampler() (with
     * controller = 0 for bank select MSB and/or controller = 32 for bank select
     * LSB) before calling this method.
     *
     * @param Program - MIDI program number
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided value invalid)
     */
    bool SendProgramChangeToSampler(uint8_t Program);

    /**
     * Can be called by the virtual MIDI device to check whether a new note
     * on or note off MIDI event arrived to the sampler during the last
     * call to this method. So this is a asynchronously, "polling" based
     * communication mechanism, which works in conjunction with the
     * NoteIsActive() method call.
     */
    bool NotesChanged();

    /**
     * Can be called by the virtual MIDI device to check whether a new note
     * on or note off MIDI event arrived to the sampler for @a Key during
     * the last call to this method. So this is a asynchronously,
     * "polling" based communication mechanism, which works in
     * conjunction with the NoteIsActive() method call.
     */
    bool NoteChanged(uint8_t Key);

    /**
     * Can be called by the virtual MIDI device to check which key / note
     * is currently active by the sampler, e.g. to highlight the
     * respective keys on a graphical virtual keyboard.
     *
     * @see NotesChanged(), NoteChanged()
     */
    bool NoteIsActive(uint8_t Key);

    /**
     * Returns the velocity of the @e last note on event. No FIFO is used!
     */
    uint8_t NoteOnVelocity(uint8_t Key);

    /**
     * Returns the velocity of the @e last note off event. No FIFO is used!
     */
    uint8_t NoteOffVelocity(uint8_t Key);

    /**
     * Can be called by the virtual MIDI device to check whether a Control
     * Change MIDI event arrived to the sampler during the last
     * call to this method. So this is a asynchronously, "polling" based
     * communication mechanism, which works in conjunction with the
     * ControllerValue() method call.
     */
    bool ControllersChanged();

    /**
     * Can be called by the virtual MIDI device to check whether a Control
     * Change MIDI event arrived to the sampler for @a Controller during
     * the last call to this method. So this is a asynchronously,
     * "polling" based communication mechanism, which works in
     * conjunction with the ControllerValue() method call.
     */
    bool ControllerChanged(uint8_t Controller);

    /**
     * Returns the value of the @e last Control Change event. No FIFO is used!
     */
    uint8_t ControllerValue(uint8_t Controller);

    /////////////////////////////////////////////////////////////////
    // Sampler methods
    //     (usually only called by the Sampler)

    /**
     * Informs the virtual MIDI device that a @e note @e on event occured
     * (e.g. caused by a MIDI keyboard connected to the sampler).
     * Communication acts asynchronously, that is this method call doesn't
     * lock in any way and returns immediately. It is thus realtime safe.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @see ActiveNotesChanged(), NoteIsActive()
     */
    void SendNoteOnToDevice(uint8_t Key, uint8_t Velocity);

    /**
     * Informs the virtual MIDI device that a @e note @e off event occured
     * (e.g. caused by a MIDI keyboard connected to the sampler).
     * Communication acts asynchronously, that is this method call doesn't
     * lock in any way and returns immediately. It is thus realtime safe.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @see ActiveNotesChanged(), NoteIsActive()
     */
    void SendNoteOffToDevice(uint8_t Key, uint8_t Velocity);

    /**
     * Informs the virtual MIDI device that a @e Control @e Change event
     * occured (e.g. caused by a MIDI keyboard connected to the sampler).
     * Communication acts asynchronously, that is this method call doesn't
     * lock in any way and returns immediately. It is thus realtime safe.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @see ControllersChanged(), ControllerValue()
     */
    void SendCCToDevice(uint8_t Controller, uint8_t Value);

    /**
     * Gets the next pending MIDI event from the virtual MIDI device by
     * using a lockfree FIFO.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @param Event - destination for writing the next event to
     * @returns true on success, false if no event pending
     */
    bool GetMidiEventFromDevice(event_t& Event);
    
    /////////////////////////////////////////////////////////////////
    // General Purpose Methods
    
    /**
     * Adjusts the internal event buffer to cover at least the given
     * amount of MIDI events. This might be useful, since the internal
     * event buffer is by default quite small (i.e. just 12 events).
     *
     * This method is not thread safe! Any operations upon this device
     * have to be stopped before calling this method!
     */
    void SetMaxEvents(int n);

    /**
     * Constructor
     */
    VirtualMidiDevice();

    /**
     * Destructor
     */
    virtual ~VirtualMidiDevice();

private:
    struct private_data_t;
    private_data_t* const p;
};

} // namespace LinuxSampler

#endif // LS_VIRTUALMIDIDEVICE_H
1	schoenebeck	1659	/*
2	schoenebeck	2521	Copyright (C) 2008 - 2014 Christian Schoenebeck
3	schoenebeck	1659	*/
4
5			#ifndef LS_VIRTUALMIDIDEVICE_H
6			#define LS_VIRTUALMIDIDEVICE_H
7
8			#include "../../common/global.h"
9
10			namespace LinuxSampler {
11
12			/**
13			* Light-weight MIDI interface (for MIDI in & out) intended to be used by
14			* pure software MIDI "devices", that is e.g. a graphical virtual MIDI
15			* keyboard in an instrument editor or in a sampler frontend. This class
16			* should not be used for regular MIDI input device drivers for the sampler.
17			* This primitive interface by design doesn't care about jitter, fast event
18			* delivery or masses and masses of events in a short time!
19			*/
20			class VirtualMidiDevice {
21			public:
22			enum event_type_t {
23			EVENT_TYPE_NOTEON = 1,
24	schoenebeck	2025	EVENT_TYPE_NOTEOFF = 2,
25	schoenebeck	2521	EVENT_TYPE_CC = 3,
26			EVENT_TYPE_PITCHBEND,
27			EVENT_TYPE_PROGRAM
28	schoenebeck	1659	};
29
30			struct event_t {
31			event_type_t Type;
32	schoenebeck	2025	uint8_t Arg1; ///< Depends on @c Type (e.g. key number for note on/off events).
33			uint8_t Arg2; ///< Depends on @c Type (e.g. velocity for note on/off events).
34	schoenebeck	1659	};
35
36			/////////////////////////////////////////////////////////////////
37			// Device methods
38			// (called by the VirtualMidiDevice implementation)
39
40			/**
41			* Sends a MIDI @e note @e on event to the sampler.
42			*
43			* @returns true on success, false if internal FIFO full
44			* (or provided values invalid)
45			*/
46			bool SendNoteOnToSampler(uint8_t Key, uint8_t Velocity);
47
48			/**
49			* Sends a MIDI @e note @e off event to the sampler.
50			*
51			* @returns true on success, false if internal FIFO full
52			* (or provided values invalid)
53			*/
54			bool SendNoteOffToSampler(uint8_t Key, uint8_t Velocity);
55
56			/**
57	schoenebeck	2025	* Sends a MIDI @e Control @e Change event to the sampler.
58			*
59			* @returns true on success, false if internal FIFO full
60			* (or provided values invalid)
61			*/
62			bool SendCCToSampler(uint8_t Controller, uint8_t Value);
63
64			/**
65	schoenebeck	2521	* Sends a MIDI @e Pitch @e Bend event to the sampler.
66			*
67			* @param Pitch - MIDI pitch value (-8192 ... +8191)
68			*
69			* @returns true on success, false if internal FIFO full
70			* (or provided pitch value out of valid range)
71			*/
72			bool SendPitchBendToSampler(int Pitch);
73
74			/**
75			* Sends a MIDI @e Program @e Change event to the sampler.
76			*
77			* If you want to change the sound bank, call SendCCToSampler() (with
78			* controller = 0 for bank select MSB and/or controller = 32 for bank select
79			* LSB) before calling this method.
80			*
81			* @param Program - MIDI program number
82			*
83			* @returns true on success, false if internal FIFO full
84			* (or provided value invalid)
85			*/
86	schoenebeck	2522	bool SendProgramChangeToSampler(uint8_t Program);
87	schoenebeck	2521
88			/**
89	schoenebeck	1659	* Can be called by the virtual MIDI device to check whether a new note
90			* on or note off MIDI event arrived to the sampler during the last
91			* call to this method. So this is a asynchronously, "polling" based
92			* communication mechanism, which works in conjunction with the
93			* NoteIsActive() method call.
94			*/
95			bool NotesChanged();
96
97			/**
98			* Can be called by the virtual MIDI device to check whether a new note
99			* on or note off MIDI event arrived to the sampler for @a Key during
100			* the last call to this method. So this is a asynchronously,
101			* "polling" based communication mechanism, which works in
102			* conjunction with the NoteIsActive() method call.
103			*/
104			bool NoteChanged(uint8_t Key);
105
106			/**
107			* Can be called by the virtual MIDI device to check which key / note
108			* is currently active by the sampler, e.g. to highlight the
109			* respective keys on a graphical virtual keyboard.
110			*
111			* @see NotesChanged(), NoteChanged()
112			*/
113			bool NoteIsActive(uint8_t Key);
114
115	schoenebeck	1663	/**
116			* Returns the velocity of the @e last note on event. No FIFO is used!
117			*/
118			uint8_t NoteOnVelocity(uint8_t Key);
119
120			/**
121			* Returns the velocity of the @e last note off event. No FIFO is used!
122			*/
123			uint8_t NoteOffVelocity(uint8_t Key);
124
125	schoenebeck	2025	/**
126			* Can be called by the virtual MIDI device to check whether a Control
127			* Change MIDI event arrived to the sampler during the last
128			* call to this method. So this is a asynchronously, "polling" based
129			* communication mechanism, which works in conjunction with the
130			* ControllerValue() method call.
131			*/
132			bool ControllersChanged();
133
134			/**
135			* Can be called by the virtual MIDI device to check whether a Control
136			* Change MIDI event arrived to the sampler for @a Controller during
137			* the last call to this method. So this is a asynchronously,
138			* "polling" based communication mechanism, which works in
139			* conjunction with the ControllerValue() method call.
140			*/
141			bool ControllerChanged(uint8_t Controller);
142
143			/**
144			* Returns the value of the @e last Control Change event. No FIFO is used!
145			*/
146			uint8_t ControllerValue(uint8_t Controller);
147
148	schoenebeck	1659	/////////////////////////////////////////////////////////////////
149			// Sampler methods
150			// (usually only called by the Sampler)
151
152			/**
153			* Informs the virtual MIDI device that a @e note @e on event occured
154			* (e.g. caused by a MIDI keyboard connected to the sampler).
155			* Communication acts asynchronously, that is this method call doesn't
156			* lock in any way and returns immediately. It is thus realtime safe.
157			*
158			* @e Note: this method is usually only called by the sampler.
159			*
160			* @see ActiveNotesChanged(), NoteIsActive()
161			*/
162			void SendNoteOnToDevice(uint8_t Key, uint8_t Velocity);
163
164			/**
165			* Informs the virtual MIDI device that a @e note @e off event occured
166			* (e.g. caused by a MIDI keyboard connected to the sampler).
167			* Communication acts asynchronously, that is this method call doesn't
168			* lock in any way and returns immediately. It is thus realtime safe.
169			*
170			* @e Note: this method is usually only called by the sampler.
171			*
172			* @see ActiveNotesChanged(), NoteIsActive()
173			*/
174			void SendNoteOffToDevice(uint8_t Key, uint8_t Velocity);
175
176			/**
177	schoenebeck	2025	* Informs the virtual MIDI device that a @e Control @e Change event
178			* occured (e.g. caused by a MIDI keyboard connected to the sampler).
179			* Communication acts asynchronously, that is this method call doesn't
180			* lock in any way and returns immediately. It is thus realtime safe.
181			*
182			* @e Note: this method is usually only called by the sampler.
183			*
184			* @see ControllersChanged(), ControllerValue()
185			*/
186			void SendCCToDevice(uint8_t Controller, uint8_t Value);
187
188			/**
189	schoenebeck	1659	* Gets the next pending MIDI event from the virtual MIDI device by
190			* using a lockfree FIFO.
191			*
192			* @e Note: this method is usually only called by the sampler.
193			*
194			* @param Event - destination for writing the next event to
195			* @returns true on success, false if no event pending
196			*/
197			bool GetMidiEventFromDevice(event_t& Event);
198	schoenebeck	2384
199			/////////////////////////////////////////////////////////////////
200			// General Purpose Methods
201
202			/**
203			* Adjusts the internal event buffer to cover at least the given
204			* amount of MIDI events. This might be useful, since the internal
205			* event buffer is by default quite small (i.e. just 12 events).
206			*
207			* This method is not thread safe! Any operations upon this device
208			* have to be stopped before calling this method!
209			*/
210			void SetMaxEvents(int n);
211	schoenebeck	1659
212			/**
213			* Constructor
214			*/
215			VirtualMidiDevice();
216
217			/**
218			* Destructor
219			*/
220			virtual ~VirtualMidiDevice();
221
222			private:
223	persson	1896	struct private_data_t;
224			private_data_t* const p;
225	schoenebeck	1659	};
226
227			} // namespace LinuxSampler
228
229			#endif // LS_VIRTUALMIDIDEVICE_H