drivers/midi/VirtualMidiDevice.h

/*
    Copyright (C) 2008 - 2012 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
    };

    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);

    /**
     * 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 - 2012 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	};
27
28	struct event_t {
29	event_type_t Type;
30	uint8_t Arg1; ///< Depends on @c Type (e.g. key number for note on/off events).
31	uint8_t Arg2; ///< Depends on @c Type (e.g. velocity for note on/off events).
32	};
33
34	/////////////////////////////////////////////////////////////////
35	// Device methods
36	// (called by the VirtualMidiDevice implementation)
37
38	/**
39	* Sends a MIDI @e note @e on event to the sampler.
40	*
41	* @returns true on success, false if internal FIFO full
42	* (or provided values invalid)
43	*/
44	bool SendNoteOnToSampler(uint8_t Key, uint8_t Velocity);
45
46	/**
47	* Sends a MIDI @e note @e off event to the sampler.
48	*
49	* @returns true on success, false if internal FIFO full
50	* (or provided values invalid)
51	*/
52	bool SendNoteOffToSampler(uint8_t Key, uint8_t Velocity);
53
54	/**
55	* Sends a MIDI @e Control @e Change event to the sampler.
56	*
57	* @returns true on success, false if internal FIFO full
58	* (or provided values invalid)
59	*/
60	bool SendCCToSampler(uint8_t Controller, uint8_t Value);
61
62	/**
63	* Can be called by the virtual MIDI device to check whether a new note
64	* on or note off MIDI event arrived to the sampler during the last
65	* call to this method. So this is a asynchronously, "polling" based
66	* communication mechanism, which works in conjunction with the
67	* NoteIsActive() method call.
68	*/
69	bool NotesChanged();
70
71	/**
72	* Can be called by the virtual MIDI device to check whether a new note
73	* on or note off MIDI event arrived to the sampler for @a Key during
74	* the last call to this method. So this is a asynchronously,
75	* "polling" based communication mechanism, which works in
76	* conjunction with the NoteIsActive() method call.
77	*/
78	bool NoteChanged(uint8_t Key);
79
80	/**
81	* Can be called by the virtual MIDI device to check which key / note
82	* is currently active by the sampler, e.g. to highlight the
83	* respective keys on a graphical virtual keyboard.
84	*
85	* @see NotesChanged(), NoteChanged()
86	*/
87	bool NoteIsActive(uint8_t Key);
88
89	/**
90	* Returns the velocity of the @e last note on event. No FIFO is used!
91	*/
92	uint8_t NoteOnVelocity(uint8_t Key);
93
94	/**
95	* Returns the velocity of the @e last note off event. No FIFO is used!
96	*/
97	uint8_t NoteOffVelocity(uint8_t Key);
98
99	/**
100	* Can be called by the virtual MIDI device to check whether a Control
101	* Change MIDI event arrived to the sampler during the last
102	* call to this method. So this is a asynchronously, "polling" based
103	* communication mechanism, which works in conjunction with the
104	* ControllerValue() method call.
105	*/
106	bool ControllersChanged();
107
108	/**
109	* Can be called by the virtual MIDI device to check whether a Control
110	* Change MIDI event arrived to the sampler for @a Controller during
111	* the last call to this method. So this is a asynchronously,
112	* "polling" based communication mechanism, which works in
113	* conjunction with the ControllerValue() method call.
114	*/
115	bool ControllerChanged(uint8_t Controller);
116
117	/**
118	* Returns the value of the @e last Control Change event. No FIFO is used!
119	*/
120	uint8_t ControllerValue(uint8_t Controller);
121
122	/////////////////////////////////////////////////////////////////
123	// Sampler methods
124	// (usually only called by the Sampler)
125
126	/**
127	* Informs the virtual MIDI device that a @e note @e on event occured
128	* (e.g. caused by a MIDI keyboard connected to the sampler).
129	* Communication acts asynchronously, that is this method call doesn't
130	* lock in any way and returns immediately. It is thus realtime safe.
131	*
132	* @e Note: this method is usually only called by the sampler.
133	*
134	* @see ActiveNotesChanged(), NoteIsActive()
135	*/
136	void SendNoteOnToDevice(uint8_t Key, uint8_t Velocity);
137
138	/**
139	* Informs the virtual MIDI device that a @e note @e off event occured
140	* (e.g. caused by a MIDI keyboard connected to the sampler).
141	* Communication acts asynchronously, that is this method call doesn't
142	* lock in any way and returns immediately. It is thus realtime safe.
143	*
144	* @e Note: this method is usually only called by the sampler.
145	*
146	* @see ActiveNotesChanged(), NoteIsActive()
147	*/
148	void SendNoteOffToDevice(uint8_t Key, uint8_t Velocity);
149
150	/**
151	* Informs the virtual MIDI device that a @e Control @e Change event
152	* occured (e.g. caused by a MIDI keyboard connected to the sampler).
153	* Communication acts asynchronously, that is this method call doesn't
154	* lock in any way and returns immediately. It is thus realtime safe.
155	*
156	* @e Note: this method is usually only called by the sampler.
157	*
158	* @see ControllersChanged(), ControllerValue()
159	*/
160	void SendCCToDevice(uint8_t Controller, uint8_t Value);
161
162	/**
163	* Gets the next pending MIDI event from the virtual MIDI device by
164	* using a lockfree FIFO.
165	*
166	* @e Note: this method is usually only called by the sampler.
167	*
168	* @param Event - destination for writing the next event to
169	* @returns true on success, false if no event pending
170	*/
171	bool GetMidiEventFromDevice(event_t& Event);
172
173	/////////////////////////////////////////////////////////////////
174	// General Purpose Methods
175
176	/**
177	* Adjusts the internal event buffer to cover at least the given
178	* amount of MIDI events. This might be useful, since the internal
179	* event buffer is by default quite small (i.e. just 12 events).
180	*
181	* This method is not thread safe! Any operations upon this device
182	* have to be stopped before calling this method!
183	*/
184	void SetMaxEvents(int n);
185
186	/**
187	* Constructor
188	*/
189	VirtualMidiDevice();
190
191	/**
192	* Destructor
193	*/
194	virtual ~VirtualMidiDevice();
195
196	private:
197	struct private_data_t;
198	private_data_t* const p;
199	};
200
201	} // namespace LinuxSampler
202
203	#endif // LS_VIRTUALMIDIDEVICE_H