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(int 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	/*
2	Copyright (C) 2008 - 2014 Christian Schoenebeck
3	*/
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	EVENT_TYPE_NOTEOFF = 2,
25	EVENT_TYPE_CC = 3,
26	EVENT_TYPE_PITCHBEND,
27	EVENT_TYPE_PROGRAM
28	};
29
30	struct event_t {
31	event_type_t Type;
32	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	};
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	* 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	* 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	bool SendProgramChangeToSampler(int Program);
87
88	/**
89	* 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	/**
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	/**
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	/////////////////////////////////////////////////////////////////
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	* 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	* 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
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
212	/**
213	* Constructor
214	*/
215	VirtualMidiDevice();
216
217	/**
218	* Destructor
219	*/
220	virtual ~VirtualMidiDevice();
221
222	private:
223	struct private_data_t;
224	private_data_t* const p;
225	};
226
227	} // namespace LinuxSampler
228
229	#endif // LS_VIRTUALMIDIDEVICE_H